Configure STS client key management using the AdminServer STSKey plugin

In OpenEdge 12.3, an optional STSKey plugin was added to the OpenEdge AdminServer. This plugin gives the OpenEdge AdminServer the ability to maintain the STS client key on an OpenEdge installation.

Note: This procedure requires an OpenEdge AdminServer on each OpenEdge Authentication Gateway client's OpenEdge installation. If your site does not meet this requirement, then you can manage STS client keys using the stskeyutil utility on each client OpenEdge installation. For more information, see Configure STS client key management using stskeyutil.

The configuration for the STSKey plugin is defined in the AdminServerPlugins.properties file, which is located in the $DLC/properties directory. Accompanying the STSKey plugin for the AdminServer is a supporting stskeyplugin.properties file (also in $DLC/properties), which is where administrators define connection properties for the STS client key generation.

The STSKey plugin manages the STS client key of the OpenEdge Authentication Gateway client's OpenEdge installation using the stskeyutil utility and its ability to use the OpenEdge Authentication Gateway Key Distribution service. The STSKey plugin includes additional functionality over the stskeyutil utility, including specifying the frequency of when the plugin checks the Key Distribution service to see whether a new STS server key was installed on the OpenEdge Authentication Gateway server, and supporting encoded passwords for STS client key generation.

To use the AdminServer STSKey plugin to manage client OpenEdge installation's STS client keys:
  1. Ensure the Key Distribution application is deployed on your OpenEdge Authentication Gateway server that is configured with an STS server key, for example:
    proenv>oeauthserver/bin/tcman deploy %DLC%/servers/pasoe/extras/keydist.war

    For more information about using an STS server key, see STS server key configuration.

  2. On the OpenEdge Authentication Gateway client's OpenEdge installation, stop the AdminServer:
    proenv>proadsv -stop
  3. Edit the $DLC/properties/stskeyplugin.properties file on the client machine to specify the OpenEdge Authentication Gateway server as the keydistURL. For more information about the additional supported properties, see STSKey plugin for the AdminServer.
  4. Start the AdminServer on the OpenEdge client machine:
    proenv>proadsv -start
    The AdminServer uses the Key Distribution service to periodically check the OpenEdge Authentication Gateway server for an STS server key, and if the STS server key changed, then it generates an encoded STS client key into the directory specified by the keystorepath field in the stskeyplugin.properties file. Then the AdminServer updates the client OpenEdge installation's STS client key. The default location is $DLC/keys/encoded-client-key.ecp).
  5. Verify the connection to the OpenEdge Authentication Gateway server using the stsclientutil command, for example:
    proenv>stsclientutil -nohostverify -url https://hostname:port -cmd authenticate -user test -password test

    For more information about the stsclientutil command, see STS client utility (stsclientutil) in OpenEdge Getting Started: OpenEdge Authentication Gateway Guide.

STS client key management logs for the AdminServer

The client-side logging from the AdminServer is shown in the $WRK/admserv.log file.

When the AdminServer successfully generates a new STS client key, the following message is printed to the admserv.log file: 
stskeyutil request successful : key updated
If the AdminServer checks the Key Distribution service and finds that the STS server key did not change, then the following message is printed to the admserv.log file: 
server key not modified since last client key update

Logging verbosity is set using the verbose property in the stskeyplugin.properties file. For more information, see STSKey plugin for the AdminServer.

Advanced logging for the STSKey plugin can also be configured using the AdminServer Log Console in OpenEdge Management.

Updating the STS server key and STS client keys

If the stskeyutil generates a new STS server key (using, for example, the stskeyutil create utility in OpenEdge Getting Started: OpenEdge Authentication Gateway Guide, with the -overwrite option) for the OpenEdge Authentication Gateway server, the OpenEdge client machines' STSKey plugins check the OpenEdge Authentication Gateway server to see if a new STS server key was installed (the frequency of these checks is determined by the pinginterval setting). If the OpenEdge Authentication Gateway server has a new STS server key, and if the onlyifmodified option is set to 1 on the client machines, then the STSKey plugin updates the STS client key on the client machines.

You can verify the STS server key update by looking at the hostname.access.{date}.log file for the OpenEdge Authentication Gateway server, and checking the timestamp to see that a new STS server key was generated and sent by the Key Distribution application to the client machines.