Configuring UMS

After you install the IBM RPA server with Single Sign-On (SSO), you can configure the User Management Service (UMS) to connect with your identity providers.

Encoding a password for UMS

Procedure

Open your command prompt.
Navigate to the directory where securityUtility.bat is located. Typically, this is located in the IBM RPA installation path under ums\wlp\bin.
```
cd "C:\Program Files\IBM Robotic Process Automation\ums\wlp\bin"
```
Execute the securityUtility.bat command with the encode option followed by your password.
```
securityUtility.bat encode YOUR_PASSWORD
```

Connecting with LDAP and LDAPS

See the following documentation for instructions about how to configure UMS to connect with your identity provider:

Changing the UMS certificate

The IBM RPA server generates a self-signed certificate during the installation to sign the connection to UMS. This certificate usually lasts for 1 year, and can be renewed after expiring.

You can also replace the certificate with your own certificate to maintain a safer connection.

Before you change the UMS certificate, ensure that you have a valid PKCS#12 certificate. These certificates are usually contained in a ".p12" file. For more information about certificates and how to generate them, see Create an SSL certificate.

Important:Self-signed certificates are not recommended for production environments. Use a secure certificate signed by a Certificate Authority instead.

Follow these steps to change the UMS certificate:

Place your key store file at "C:\ProgramData\IBM Robotic Process Automation\servers\umsServer\resources\security\key.p12".
Run the following command on PowerShell or the Command Prompt, replacing "KEYSTORE_PASSWORD" with the password for the key.p12 file:
```
"C:\Program Files\IBM Robotic Process Automation\ums\wlp\bin\securityUtility.bat" encode KEYSTORE_PASSWORD
```
This encodes the password for the next steps.
Update the keystore password at "C:\ProgramData\IBM Robotic Process Automation\servers\umsServer\server.xml", on the "defaultKeyStore" id, replacing "ENCODED_PASSWORD" with your encoded password from the previous step:
```
<keyStore id="defaultKeyStore" password="ENCODED_PASSWORD" />
```
Update the key store password of the certificate at "C:\ProgramData\IBM Robotic Process Automation\servers\umsServer\configDropins\overrides\umsVariables.xml", on the "ssl_keystore_password", replacing "ENCODED_PASSWORD" with the encoded password:
```
<variable name="ssl_keystore_password" value="ENCODED_PASSWORD" />
```
Run the following command on CMD to extract the alias of your key file, replacing "KEYSTORE_PASSWORD" with the unencoded password for the key.p12 file.
```
keytool -list -v -keystore key.p12 -storepass KEYSTORE_PASSWORD
```
Update the alias of the certificate at "C:\ProgramData\IBM Robotic Process Automation\servers\umsServer\configDropins\overrides\umsVariables.xml", on the "oidc.jwt.keyAliasName" key, replacing "ALIAS_NAME" with the output of the previous step. Make sure that the following line is uncommented:
```
<variable name="oidc.jwt.keyAliasName" value="ALIAS_NAME"/>
<variable name="ums.oauth.accessTokenLifetime" value="7200"/>
```
Restart the umsServer service.

Troubleshooting

If you encounter problems during this procedure, follow these steps:

Check the UMS log files at "C:\ProgramData\IBM Robotic Process Automation\servers\umsServer\logs\messages.log".
Check the server's API logs (usually located at "C:\ProgramData\IBM Robotic Process Automation\LOG\Api")
Ensure that the "oidc.jwt.keystore.password" key is not set on "C:\ProgramData\IBM Robotic Process Automation\servers\umsServer\configDropins\overrides\umsVariables.xml". Usually this line is commented out:
```

```

Changing the UMS hostname

Starting at version 23.0.15, you can now change the hostname used by the UMS service.

Follow these steps to change the hostname used by the SSO service in IBM RPA:

Open the PowerShell.

Go to the tool location:

cd "C:\Program Files\IBM Robotic Process Automation\IBM Robotic Process Automation Server\Commom_Files"

Run the following command to change the installation hostname. Replace HOSTNAME with your new hostname:
```
rpatool.exe --replaceapiandwebhostname --hostnamednsoripaddress HOSTNAME
```
The hostname can be either an IP address, Fully Qualified Domain Name (FQDN), or the machine's hostname

Note:The certificate configured on UMS might not match the new hostname. Renew the self-signed certificate or change the certificate to apply it to a new hostname.

Renewing expired UMS certificates

See the steps described in UMS certificate expired to renew the self-signed certificate automatically generated for UMS. This procedure is only valid for versions 23.0.15 and above.