STS server key configuration

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 Configure 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-name/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. Modify the Authentication Gateway configuration 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 encoded with the genpassword utility. See Encoding prefix for an example of the encoded password.

For example:

sts.properties snippet

sts.server.key.enabled=true
sts.server.keyfile=oests-key.ecp
sts.server.keyfile password=ae2h4::ddf0d957826c0f076a8e06426a9b3d305bdf7897859f696c0cf088f8d414ae1b2ca7f9200c4ee8cccf21d142b8143baa

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.

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

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 oeauthserver/webapps/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 oeauthserver/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 oeauthserver/webapps/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.

For more information about log files and logging levels, see Log files in Learn about Progress Application Server for OpenEdge and Configure logging in PAS for OpenEdge in Manage Progress Application Server (PAS) for OpenEdge.

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 the sts.properties file that are related to STS keys:

sts.server.ststokenname

x-oests-token

sts.server.previouskeyfile

<blank>

sts.server.
  previouskeyfilepassword

<blank>

sts.server.previouskeydomain

oests.server

sts.libstskey.loglevel

2

sts.libstskey.logfile

${catalina.base}/logs/libstskey.log