Specifying basic User Management Service configuration settings

The server template creates a generic version of the server.xml file that is suitable for most environments. Only some environment specific settings are externalized as variables. Configuration elements using externalized variables are marked with a comment:

<!-- configure variable values in configDropins/overrides/umsVariables.xml -->

To set up a startable server, only the following settings must be provided in wlp/usr/servers/serverName/configDropins/overrides/umsVariables.xml:

hostname

The hostname on which this server listens. Although you can specify * to listen on all host names and IP addresses that can be used to reach this machine, it is recommended to be as explicit as possible. For more information, see httpEndpoint - HTTP Endpoint (httpEndpoint).

Note: The default hostname is set to localhost to prevent the user from being available remotely before the configuration is complete.

http_port

The port for non-secure HTTP communication. The default value of -1 ensures that the server does not listen to non-secure HTTP. None of the capabilities are available over non-secure HTTP, however some browsers still assume HTTP if the user does not provide a protocol in the URL address bar. For these users, it is convenient to be reachable over non-secure HTTP on port 80 and then immediately redirect them to use HTTPS. For more information, see httpEndpoint - HTTP Endpoint (httpEndpoint).

https_port

The port for secure HTTPS communication. The default value is 9443, which is familiar to many WebSphere users. When running the User Management Service server on the same host as a IBM Business Automation Workflow server, be sure to use a different port. For more information about the httpsPort attribute in Liberty, see httpEndpoint - HTTP Endpoint (httpEndpoint).

admin.user and admin.password

Because the User Management Server is not yet connected to a remote user repository, you can define an administrative user account in basicRegistry. A username and password are the only properties that you can specify. For more information, see basicRegistry - Basic User Registry (basicRegistry).

ssl_keystore_password

To enable HTTPS communication, the server must have an SSL/TLS certificate. Enter the password that was printed when you created the SSL keystore. You can either use the clear text password or the encrypted password of the form "{xor}...".Only this instance of the User Management Service needs access to this keystore. You do not need to remember the password. For information about the minimum SSL configuration in Liberty, see https://www.ibm.com/support/knowledgecenter/en/SSEQTP_liberty/com.ibm.websphere.wlp.doc/ae/twlp_sec_ssl.html. Enabling SSL communication in Liberty

This ssl_keystore_password variable is used in SSL configuration in server.xml. If you do not want to use the default SSL specification you must perform the configration by using the liberty server.xml. You can replace this configuration in server.xml with your own SSL settings.

For more information about the Liberty keystore, see keyStore - Keystore (keyStore).

external_hostname

This variable applies to UMS version 1.1.0 and later. The hostname of the server as seen by external clients. In a quick start configuration, the external host name is the same as the internal hostname. In production in a highly available, load balanced environment, the external hostname is the address of the IBM Http Server. See Configuring a web server.

oidc.jwt.keystore.location

This variable applies to UMS version 1.1.0 and later. Location of the keystore for the JWK token certificate. To enable single sign on with JWK token exchange, the server needs a certificate to sign the JWK token. Single sign on clients will validate the JWK token by checking the public key of the certificate against the signature of the token. In production, the keystore must be the same for all server nodes. In a quick start configuration with a single server, the SSL keystore is reused, so you should keep the setting unchanged.

oidc.jwt.keystore.password

This variable applies to UMS version 1.1.0 and later. The password of the keystore for the JWK token. In a quick start configuration with a single server, keep the setting unchanged.

oidc.jwt.keystore.type

This variable applies to UMS version 1.1.0 and later. The type of the keystore for the JWK token. Keystores that end with the characters p12 have type PKCS12, keystores and those that end with the characters jks have type JKS. In a quick start configuration with a single server, keep the setting unchanged.

oidc.jwt.keyAliasName

This variable applies to UMS version 1.1.0 and later. The name of the key in the keystore to be used to sign the JWK token. In a quick start configuration with a single server, keep the setting unchanged.

db.type

This variable applies to UMS version 1.1.0 and later. The database type. Possible values are: db2, oracle, mssql, derby (Embedded Derby), derbyNet (Network Derby). This setting is used when one of the supplied database configurations is used, which can be found in the file datasources.xml. For a quick start configuration, keep the setting derby.

oauth.datasource.id

This variable applies to UMS version 1.1.0 and later. The ID of the <dataSource> configuration element in the server configuration XML files. Leave the setting unchanged when one of the supplied configurations is used, which can be found in the file datasources.xml. For a quick start configuration, leave the setting unchanged.

oauth.db.name

This variable applies to UMS version 1.1.0 and later. The name of the database. This setting is used when one of the supplied database configurations for DB2, Oracle, or MSSQL is used. Supplied configurations can be found in the file datasources.xml. For a quick start configuration, leave the setting unchanged.

oauth.db.hostname

This variable applies to UMS version 1.1.0 and later. The hostname of the database server. This setting is used when one of the supplied database configurations for DB2, Oracle, MSSQL or Network Derby (derbyNet) is used. Supplied configurations can be found in the file datasources.xml. For a quick start configuration, leave the setting unchanged.

oauth.db.port

This variable applies to UMS version 1.1.0 and later. The port where the database server listens for connections. This setting is used when one of the supplied database configurations for DB2, Oracle, MSSQL or Network Derby (derbyNet) is used. Supplied configurations can be found in the file datasources.xml. For a quick start configuration, leave the setting unchanged.

oauth.db.user

This variable applies to UMS version 1.1.0 and later. The user that is authorized to access the database. This setting is used when one of the supplied database configurations for DB2, Oracle, MSSQL, or Network Derby (derbyNet) is used. Supplied configurations can be found in the file datasources.xml. For a quick start configuration, leave the setting unchanged.

oauth.db.password

This variable applies to UMS version 1.1.0 and later. The password for the user that is authorized to access the database. This setting is used when one of the supplied database configurations for DB2, Oracle, MSSQL or Network Derby (derbyNet) is used. Supplied configurations can be found in the file datasources.xml. For a quick start configuration, leave the setting unchanged.

For example, for a quick start configuration:

<server>

    <variable name="hostname" value="localhost" />
    <variable name="http_port" value="-1" />
    <variable name="https_port" value="9443" />
    <variable name="external_hostname" value="${hostname}" />

    <variable name="admin.user" value="adminUser" />
    <variable name="admin.password" value="password" />

    <variable name="ssl_keystore_password" value="keystorePassword" />

    <variable name="oidc.jwt.keystore.location" value="resources/security/key.p12" /> 
    <variable name="oidc.jwt.keystore.password" value="${ssl_keystore_password}" /> 
    <variable name="oidc.jwt.keystore.type" value="PKCS12" /> 
    <variable name="oidc.jwt.keyAliasName" value="default" />
 
    <variable name="db.type" value="derby" />

    <variable name="oauth.datasource.id" value="${db.type}OAuthDataSource" />
    <variable name="oauth.db.name" value="" />
    <variable name="oauth.db.hostname" value="" />
    <variable name="oauth.db.port" value="1521" />
    <variable name="oauth.db.user" value="" />
    <variable name="oauth.db.password" value="" />

</server>

Where adminUser is an admin user, password is the admin user password, and keystorePassword is the SSL keystore password.

For example, for an Oracle database:

<server>

    <variable name="hostname" value="localhost" />
    <variable name="http_port" value="-1" />
    <variable name="https_port" value="9443" />
    <variable name="external_hostname" value="mypublicaddress.example.com" />
    <variable name="admin.user" value="adminUser" />
    <variable name="admin.password" value="password" />

    <variable name="ssl_keystore_password" value="keystorePassword" />
    
    <variable name="oidc.jwt.keystore.location" value="resources/security/jwtkey.p12" /> 
    <variable name="oidc.jwt.keystore.password" value="jktKeystorePassword" /> 
    <variable name="oidc.jwt.keystore.type" value="PKCS12" /> 
    <variable name="oidc.jwt.keyAliasName" value="default" />
 
    <variable name="db.type" value="oracle" />

    <variable name="oauth.datasource.id" value="${db.type}OAuthDataSource" />
    <variable name="oauth.db.name" value="ORCL" />
    <variable name="oauth.db.hostname" value="oracleserver.example.com" />
    <variable name="oauth.db.port" value="1521" />
    <variable name="oauth.db.user" value="UMSORCL" />
    <variable name="oauth.db.password" value="UMSORCLPassword" />

</server>

Where adminUser is an admin user, password is the admin user password, keystorePassword is the SSL keystore password, resources/security/jwtkey.p12 is the location of the keystore that is used for JSON Web Key (JWK) tokens, and jktKeystorePassword is the password of that keystore.