STS server key configuration

An optional STS server key file can be installed to validate client requests to ensure that they are coming from authorized database client installations. By default, the Authentication Gateway does not require the STS server key file to perform authentication and SSO token exchange.

The STS server key file is generated by the stskeyutil command line utility installed with OpenEdge. For more information on stskeyutil, see STS Key Utility.

The following sections describe how to configure the Authentication Gateway with an STS server key, and how to install STS client keys.

Generating an STS server key

The first step is to generate a new STS server key using the stskeyutil command. For example:

>stskeyutil create
>Enter server key file password:
>Enter server key's domain access-code:
>created server key file: oests-key.ecp

Configuring an STS server domain access code

You must create a STS domain configuration that will be used by the STS server to store and access the domain access code for the server key in addition to any domains used for client authentication. (See the domain.json example in Configuring domains.)

Note the following:

The name of the domain should be oests.server. (The "enabled" property in the domain configuration should be changed from false to true.) If you choose a different domain name, be sure to update the sts.properties file. Set the new domain by editing the sts.server.keydomain property.

You must also specify the domain name via stskeyutil create.

The domain must have the SSO domain action.

The domain must specify the anonymous domain type.

When configuring the domain, provide the domain access code in domainsks.csv . The domain access code must exactly match the domain access code used when generating the STS server key. Run gendomreg domainsks.csv domains.keystore and then copy domains.keystore to the instance/webapps/ROOT/WEB-INF/config directory.

Configuring the Authentication Gateway with the STS server key

Once the key is generated, and the domain configuration added, you must enable the STS server key on the Authentication Gateway . The Authentication Gateway configuration must be modified both to turn on STS key support explicitly, and to reference the server key file location.

At a minimum, you must modify the following required properties in the sts.properties file:

Set sts.server.key.enabled to true.

Set sts.server.keyfile to the location of the server key file. This may be absolute or relative directory (i. e. relative to the PAS for OpenEdge working directory).

Note: Due to how Spring configuration interprets property files, on Windows you must use forward slashes ( / )for any file path separators for the key file name, or use double-back slashes ( \\ )to escape them.

Set sts.server.keyfilepassword to the password used to generate the server key file. Progress Software Corporation strongly recommends that the password be oech1:: encoded.

For example:

sts.properties snippet

sts.server.key.enabled=true
sts.server.keyfile=oests-key.ecpsts.server.keyfile
password=oech1::20333c34252a2137

Client key configuration

Once the STS server is configured you must configure the client with an STS client key generated from the STS server key.

To install the client key, run stskeyutil install. You must run this utility on the client machine with the OpenEdge install on that machien that will try to connect to the STS server. For example:

>stskeyutil install -url https://acme.com:8443/oests -overwrite
>Enter server key file password:
created client key file

The -url switch is mandatory and must reference the appropriate Authentication Gateway.

The client key file will be installed under %DLC%/keys by default.

The URL is hashed to generate the STS client key file name in the keystore. Each Authentication Gateway has a unique URL that is referenced by the database domain configuration. The STS client key installation must match this value exactly.

Start the Authentication Gateway

Once the STS server key has been installed and configured you can start the Authentication Gateway (or PAS for OpenEdge instance) where STS web application is installed.

For example:

oeauthserver/bin/tcman.sh start

Once the server starts you should see a message similar to the following in the server log file. You will need to adjust the logging level of the OESTS web application to see it. Edit ROOT/WEB-INF/logging.xml to increase logging level.

STS server key is enabled. Server key file configuration is required.
Clients will be required to be configured with the matching client key.

Testing the client key

Run the stsclientutil utility to test the client key installation. For example:

>stsclientutil -cmd ping -url https://sts.acme.com:8992
ping ... OK

For more information on stsclientutil, see STS Client Utility (stsclientutil).

Troubleshooting

Check the STS server log file in the Authentication Gateway instance's /logs/*.log for errors.

Normally STS web application logging is set to WARNING.You can get ping status messages in the STS log file if you increase the logging level. Edit ROOT/WEB-INF/logging.xml to increase the logging level.

The ping status messages in the log file will look similar to the following:

Ping succeeded. Received request with a valid client key header.
Ping succeeded. Received client request with a valid client key header, but client key header is not required.
Ping failed. Received request without the required client key header.
Ping failed. Received client request with an invalid client key header.
Ping succeeded. Received request without a client key header. Request header is not required.

See Progress Application Server for OpenEdge: Administration Guide for more information about log files and logging levels.

You can also use the -l 5 switch with stsclientutil to make the logging messages more verbose. However, ping returns very little information. It is primarily used to test if the installed client key, for a given URL, matches the server key that is installed with the Authentication Gateway.

Other STS key properties

The following table lists other properties in thests.properties file that are related to STS keys:

Property	Default	Description
sts.server.ststokenname	x-oests-token	Identifies the HTTP header that the Authentication Gateway looks for to identify the client. Can be changed to any string, but the client configuration must match. This value must match the name of the header name in the STS server key, if one is set up via stskeyutil.
sts.server.previouskeyfile	<blank>	(Optional) Specify the file name of the secondary STS server key. Used when rolling out STS client key updates incrementally. If left blank, there is no secondary STS server key.
sts.server. previouskeyfilepassword	<blank>	Secondary server key password.
sts.server.previouskeydomain	oests.server	A domain name that indicates which domain name to use to perform client key validation. Must match the value stored in the previous STS server key file.
sts.libstskey.loglevel	2	Logging level for libstskey.dll.
sts.libstskey.logfile	${catalina.base}/logs/libstskey.log	Log file for libstskey.dll output.