Using the UAA Config Tool

About this task

Use the UAA Config tool to perform the following tasks:

Add a local UAA user.
Here a local UAA user means a user defined by UAA, not by an external identity provider such as LDAP.
Remove a local UAA user.
Reset the password for a local UAA user.
Add a local UAA user to an existing UAA group.
Since OAuth2 scopes are implemented as UAA groups, this means the same as adding a scope to a user.
Remove a local UAA user from an existing UAA group.

A user who performs these functions is acting as the “admin” client and needs to know the secret of the admin client. The tool does provide a way for the user to cache the secret safely to be used later.

By default, this tool is available in the following folder: C:\Program Files\GE Digital\Historian Config. Run the tool from a Windows command prompt window.

Syntax

The tool’s syntax follows this format:

uaa_config_tool verb [options]

where verb is one of the following:

add_user
remove_user
set_user_password
add_user_to_group
remove_user_from_group
clear_secret

Run the tool without a verb or any other options to view the help page.

The uaa_config_tool utility prompts for a port number. This is the port number that you have specified in the Public HTTS Port field in the TCP PORT ASSIGNMENTS page. By default, it is set to 443. If you have changed the public HTTPS port number, enter the number. Otherwise, enter 443.

Options can be specified in the form of single dash followed by a short name, or double dash followed by a long name, followed by the value of the option, if any. For example, you can specify the user name Alice by either

-u Alice

--UserName Alice

Options

The options are as follows:


Short name	Long name	Remark
`-t`	`--Target`	URL of the UAA instance that the command should be performed on. Typically, the URL is https://localhost:8443/uaa, which is the default value. This option is optional and is only needed when the user wants to run the command against a remote UAA instance (which is not recommended due to security concerns).
`-n`	`--ClientId`	ID of the client that the user is acting as. By default, it is `admin`. This option is optional and is only needed when the admin has set up the UAA to delegate certain operations to others.
`-s`	`--ClientSecret`	This is the secret used to authenticate the user for acting as the admin client (or an alternative client given in a `--ClientId` option). If the user has elected to cache the secret previously, then this option can be omitted. Otherwise, it has to be provided. The password must satisfy the following conditions: Must not contain only numbers. Must not begin or end with a special character. Must not contain curly braces.
`-c`	`--CacheSecret`	This option is not followed by a value and is optional. If specified, the tool will cache the client secret so when the next time this tool is invoked the secret does not have to be specified. Note that the secret is encrypted and only the current Windows logon user can access and decrypt.
`-u`	`--UserName`	Name of the user that the tool is being invoked for. For example, the user that is being added or removed.
`-p`	`--UserPassword`	The password for the user being added or whose password is being reset. The option is only needed for the `add_user` and `set_user_password` commands.
`-g`	`--Group`	Name of the UAA group (scope) that the user is being added to or removed from. The option is only needed for the `add_user_to_group` and `remove_user_from_group` commands.

Examples

To add a user named alice with the password Pa55word and the admin client secret myclientsecret (this is the admin client secret that you entered while installing Web-based Clients):
```
uaa_config_tool add_user -u alice -p Pa55word -s myclientsecret  -c
```
If the UAA server is on a remote machine named webhost.lab:
```
uaa_config_tool add_user -u alice -p Pa55word -s myclientsecret -t https://webhost.lab:443/uaa -c
```

To provide user privileges to access the Web Admin console and Trend Client:

uaa_config_tool add_user_to_group -u alice -g historian_visualization.user -t https://webhost.lab:443/uaa

To provide admin privileges to access the Web Admin console and Trend Client:

uaa_config_tool add_user_to_group -u alice -g historian_visualization.admin -t https://webhost.lab:443/uaa

To provide Configuration Hub privileges, add alice to the group historian_enterprise.admin, using the previously cached admin secret:
```
uaa_config_tool add_user_to_group -u Alice -g historian_visualization.user -t https://webhost.lab:443/uaa
```
To remove alice from a remote instance of UAA as an alternative client (that is, other than admin) useradmin:
```
uaa_config_tool remove_user -u alice -t https://webhost.lab:8443/uaa -n useradmin -s MyOtherNonSecret
```
To clear any cached client secret:
```
uaa_config_tool clear_secret
```
Note: If the Windows logon account is not shared, it is not necessary to clear cached secret, since the cache is encrypted and only the same Windows user account can decrypt.
When there are Historian security groups on the local historian machine or on the domain server:
1. Create a new user account on the local Historian machine or on the domain server with same login name and password as the local UAA user.
2. Add the new user to the appropriate Historian Security group on the local historian machine or on the domain server.