PingAM 7.5.1

REST STS configuration properties

Deployment Url Element

A string that identifies this REST STS instance.

The Deployment Url Element is a component of the REST STS instance’s endpoint. For example, if you set myRESTSTSInstance as the Deployment Url Element, the REST STS endpoint would be rest-sts/myRealm/myRESTSTSInstance.

General configuration properties

The following are general configuration properties for REST STS instances:

Persist Issued Tokens in Core Token Store

Specifies whether to enable token persistence in the Core Token Service (CTS).

AM saves all STS-issued tokens to CTS when token persistence is enabled. A token’s lifetime in CTS has the same length as the Token Lifetime property specified for issued tokens.

STS token validation and cancellation capabilities require tokens to be present in CTS. Therefore, if your deployment requires token validation and cancellation, you must enable token persistence.

Supported Token Transforms

Specifies one or more token transformations supported by this REST STS instance. Token transformations are listed in the AM admin UI using the notation input-token-type → output-token-type.

For each supported token transformation, AM provides an option to invalidate the interim AM session. When transforming a token, the STS creates an AM session. If desired, you can invalidate the AM session after token transformation is complete.

Custom Token Validators

Specifies a validator class for a custom token type.

Use the format CUSTOM-TOKEN-TYPE|custom-validator-class to specify each validator class. For example, CUSTOM|org.mycompany.tokens.myCustomTokenValidator.

For details, refer to Custom token types.

Custom Token Providers

Specifies a provider class for a custom token type.

Use the format CUSTOM-TOKEN-TYPE|custom-provider-class to specify each provider class. For example, CUSTOM|org.mycompany.tokens.myCustomTokenProvider.

For details, refer to Custom token types.

Custom Token Transforms

Specifies one or more token transformations that take a custom token type as the input or output token. If you specify a custom token validator or provider, you must also specify a custom token transform.

Specify the custom transform using three values separated by the vertical bar character | as follows:

  1. The input token type

  2. The output token type

  3. Whether to invalidate the AM session created during token transformation. Specify TRUE to invalidate the session or FALSE to let the session remain valid.

For example, a value of CUSTOM|SAML2|TRUE configures a token transformation that transforms a CUSTOM token to a SAML v2.0 assertion and then invalidates the created AM session.

STS Instance is running as remote instance

Specifies whether the STS instance is running on the AM host or as a separate, remote Java process.

This property determines how calls are made to the STS instance during session token validation.

Default: true

If true, the REST STS does an outbound HTTP call to itself during session validation. If you set this property to false (for example, for an AM instance running in a clustered Docker pod), the STS validates sessions and generates tokens locally, with no HTTP call to the sessions or sts-gen endpoints.

Deployment configuration properties

The following are deployment configuration properties for REST STS instances:

Authentication Target Mappings

Specifies one or more mappings that define how the REST STS instance authenticates input tokens.

Each mapping is a set of arguments separated by the vertical bar character | as follows:

  1. (Required) The input token type: USERNAME, OPENAM, X509, OPENIDCONNECT, or a custom token type.

  2. (Required) The value service or module. If the third argument is an authentication chain, specify service. If the third argument is an authentication module, specify module.

  3. (Required) The name of an AM authentication chain or module to which the input token is authenticated.

  4. (Optional) The name of the header in which you place the token when authenticating to AM. Specify this parameter for input X509 and OPENIDCONNECT tokens as follows:

    • For X509 input tokens, the format is x509_token_auth_target_header_key=Header Name.

    • For OPENIDCONNECT input tokens, the format is oidc_id_token_auth_target_header_key=Header Name.

    Be sure to specify the header names configured in the Certificate or OpenID Connect id_token bearer authentication module properties as the Header Name argument.

    This argument can also be used with custom token types to specify the name of a header or cookie from which to obtain a token. When using this argument with a custom token type, its format is determined by the custom validator class that validates the custom token type.

The following are example mappings:

  • USERNAME|service|myLDAPChain configures STS to authenticate input USERNAME tokens to the myLDAPChain authentication chain.

  • X509|module|CertModule|x509_token_auth_target_header_key=ClientCert configures STS to obtain an X.509 certificate from the ClientCert header, use it as the input token, and authenticate it using the CertModule authentication module.

Client Certificate Header Key

Specifies the name of a header that a TLS offloader should use to use to transmit client certificates.

Token transformations that take an X.509 certificate as the input token require the certificate to be presented using two-way TLS, so that the TLS handshake can validate client certificate ownership. A common way of obtaining the client certificate with two-way TLS is to use the javax.servlet.request.X509Certificate attribute in the servlet request.

However, in deployments with TLS offloading, the offloader must use an HTTP header to transmit the certificate to its destination. This configuration property is the name of the HTTP header whose value contains the certificate.

Trusted Remote Hosts

Specifies one or more IP addresses of hosts trusted to transmit client X.509 certificates in deployments with TLS offloading.

To allow any host to transmit a certificate, specify any as the value of this property.

As with the Client Certificate Header Key property, configure this property for deployments with TLS offloading.