The stsclientutil utility is an administrator-level utility used in troubleshooting OpenEdge database connections to the Secure Token Server (STS) application. Specifically, stsclientutil addresses these tasks:
  • Establishes the OpenEdge installation's ability to connect to a PAS for OpenEdge server and use its STS application (that is, ping the STS).
  • Tests the ability of the OpenEdge installation to use an STS application for a direct user login operation for a specific OpenEdge domain (that is, authenticate the user).
  • Tests the ability of the OpenEdge installation to use an STS application for an operating-system, user login SSO to a specific OpenEdge domain (that is, exchange the OS security token for an OpenEdge security token).

Command syntax

stsclientutil -cmd command -url sts-url 
       [command-options]
-cmd command

Specifies the task to perform from one of the following:

  • ping—Sends an empty message to an STS application to test HTTPS connections and STS key features.
  • authenticate—Sends user login credentials to the STS application to test its domain configuration.
    With authenticate, you must also specify the OpenEdge user ID used to send to the STS application for direct user login testing:
    -user user[@domain]
  • exchange—Sends the security token of the current process's operating system user login to the STS application to test its domain configuration.
    With exchange, you must also specify the OpenEdge domain name to send to the STS application for operating system SSO testing:
    -domain domain
Note: There is no default for command; one of the options must be specified.
-url sts-url
Specifies the URL of the STS application (secure PAS for OpenEdge server that includes a security token service (STS) application) used by the OpenEdge database. There is no default for sts-url; the URL must be specified.
command-options
The following options are available for each of the -cmd choices:
-sslversion { TLSv1.2 | TLSv1.3 }
Specifies TLS protocol to use when connecting to the PAS for OpenEdge server hosting the STS application. If not specified, the default is TLSv1.2.
-sslciphers cipher[,cipher...]
Specifies one or a list of TLS cipher suites to use when connecting to the PAS for OpenEdge server hosting the STS application. If not specified, the default is TLSv1.2 for all ciphers.
-installpath dlc-path
Specifies the operating system file path of the OpenEdge installation to test, in the event of multiple OpenEdge installations. If not specified, the default is $DLCor %DLC%.
-keystorepath ks-path
Specifies the operating system file path to where the STS client key is installed. If not specified, the default is $DLC/keys.

The STS client key is installed by a DBA who has physical access to the OpenEdge Authentication Gateway server key. The key is managed with the stskeyutil utility.

-certstorepath cs-path
Specifies the operating system file path to where the HTTPS (TLS) CA certificates can be found to validate the PAS for OpenEdge server's certificate. If not specified, the default is $DLC/certs.
-logginglevel level
Specifies the amount of stdout logging to be provided during troubleshooting activities. If not specified, the default level is 2. The range is 0-5.
-nohostverify
Suppresses the validation of the PAS for OpenEdge certificate's subject name against the URL host DNS name.

The host name checking of TLS server certificates compares the name returned by a DNS lookup of the URL's host field to the CN subfield of the server certificate's subject-name X509 name.

-servername
Use this parameter when the OpenEdge Authentication Gateway server is configured with multiple virtual hosts that are bound to a single IP address. Specify the hostname that you want the STS client utility to connect to. The STS client utility requests the virtual host's TLS certificate during the TLS handshake instead of the Server URL's host.

The stsclientutil utility is a secured application that can be included into DBA automation scripts without fear of disclosing sensitive user credentials or OpenEdge security tokens that could be used to gain access to OpenEdge databases.

Examples

Examples of stsclientutil with the ping command:
stsclientutil -cmd ping -url https://sts.acme.com:8992

stsclientutil -cmd ping -url https://sts.acme.com:8992/oests
Examples of stsclientutil with the authentication command:
stsclientutil -cmd authentication -url https://sts.acme.com:8992 -user fred -nohostverify

stsclientutil -cmd authentication -url https://sts.acme.com:8992 -user 'fred@acme.admins'

stsclientutil -cmd authentication -url https://sts.acme.com:8992 -user 'fred@acme.admins' -sslversion TLSv1.0
Examples of stsclientutil with the exchange command:
stsclientutil -cmd exchange -url https://sts.acme.com:8992 -domain 'acme.osusers'

stsclientutil -cmd exchange -url https://sts.acme.com:8992 -domain 'acme.osusers' -logginglevel 5