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 screen.

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

or

--UserName Alice

Options

The options are as follows:
Short nameLong nameRemark
-t--TargetURL 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--ClientIdID 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--ClientSecretThis 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.
-c--CacheSecretThis 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--UserNameName of the user that the tool is being invoked for. For example, the user that is being added or removed.
-p--UserPasswordThe 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--GroupName 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 new user named bob with the password bobcat2 (with the admin client secret MyNotSoSecret specified on the command line, to be cached and used later):
    uaa_config_tool add_user -u bob -p bobcat2 -s MyNotSoSecret -c
  • To add user bob to the group historian_visualization.user, using the previously cached admin secret:
    uaa_config_tool add_user_to_group -u bob -g historian_visualization.user
  • To remove user 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.