The stsclientutil utility is an administrator-level troubleshooting utility used in troubleshooting OpenEdge database connections to the STS application. Specifically stsclientutil addresses these tasks:
  • Establish the OpenEdge installation's ability to connect to a PAS for OE server and use its STS application (i.e. ping the STS).
  • Test the ability of the OpenEdge installation to use an STS application for direct user login operation for a specific OpenEdge Domain (i.e. authenticate the user).
  • Test the ability of the OpenEdge installation to use an STS application for operating system user login SSO to a specific OpenEdge Domain (i.e. exchange the OS security token for an OpenEdge security token).
    stsclientutil -cmd command -url sts-url 
       [command-options]
-cmd command

Specify the task to perform from one of the following:

  • ping — Send an empty message to an STS application to test HTTPS connections and STS Key features.
  • authenticate — Send 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, as shown:

    -user user[@domain]
  • exchange — Send 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, as shown:

    -domain domain
Note: There is no default forcommand, one of the options must be specified.
-url sts-url
Specify the URL of the STS application (secure PAS for OE server that includes a Security-Token-Service (STS) application) used by the OpenEdge database. There is no default forsts-url, the URL must be specified.
command-options
The following options are available for each of the -cmd choices:
-sslversion { TLSv1 | SSLv2 | SSLv3 | TLSv1.0 | TLSv1.1 | TLSv1.2 | TLSv1.3 }
Specify 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...]
Specify 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
Specify 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
Specify 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
Specify 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
Specify 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
Specify this option to suppress 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 is capable of being 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