PingAM 8.0.0

STS configuration properties

Deployment Url Element

A string that identifies this STS instance.

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

General configuration properties

The following are general configuration properties for STS instances:

Persist Issued Tokens in Core Token Store

Indicate 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

The token transformations supported by this 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

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.

Learn more in Custom token types.

Custom Token Providers

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.

Learn more in Custom token types.

Custom Token Transforms

The 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.

The custom transform uses 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. Use 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

Indicate 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 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 STS instances:

Authentication Target Mappings

The mappings that define how the 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.

  3. (Required) The name of an authentication tree, which authenticates the input token.

  4. (Optional) The name of the header in which you place the token when authenticating to AM. Set 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.

    Make sure you specify the header names configured in the Certificate Collector node or OIDC ID Token Validator node 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|ldapService configures STS to authenticate input USERNAME tokens to the ldapService authentication tree.

  • X509|service|certificateAuth|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 a tree named certificateAuth that includes the certificate authentication nodes.

Client Certificate Header Key

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

Token transformations that take an X.509 certificate as the input token require the certificate to be presented using mTLS, so the TLS handshake can validate client certificate ownership.

A common way to obtain the client certificate with mTLS is to use the jakarta.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

The 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.

SAML2 token configuration properties

The following are SAML v2.0 token configuration properties for STS instances:

The properties fall into two categories:

The SAML2 Issuer Id

The IdP entity ID. Populates the Issuer element of the SAML v2.0 assertion.

Service Provider Entity Id

An audience attribute value. Populates the AudienceRestriction sub-element of the Conditions element of the SAML v2.0 assertion.

This value is required when issuing Bearer assertions.

Service Provider Assertion Consumer Service Url

A recipient attribute value. Populates the Recipient sub-element of the SubjectConfirmation element of the SAML v2.0 assertion.

The scheme, FQDN, and port configured must exactly match those of the service provider as they appear in its metadata.

This value is required when issuing Bearer assertions.

NameIdFormat

The name identifier format for the SAML v2.0 assertion.

Token Lifetime(Seconds)

The lifetime, in seconds, for the assertion. The default is 600 seconds.

Custom Conditions Provider Class Name

(Optional) The name of a custom class that generates a Conditions element in the SAML v2.0 assertion. Use a custom class when the Conditions element created by the default provider doesn’t meet your needs.

The class must implement the org.forgerock.openam.sts.tokengeneration.saml2.statements.ConditionsProvider interface, and must be bundled in the AM .war file.

Customs Subject Provider Class Name

(Optional) The name of a custom class that generates a Subject element in the SAML v2.0 assertion. Use a custom class when the Subject element created by the default provider doesn’t meet your needs.

The class must implement the org.forgerock.openam.sts.tokengeneration.saml2.statements.SubjectProvider interface and must be bundled in the AM .war file.

Custom AuthenticationStatements Class Name

(Optional) The name of a custom class that generates an AuthnStatement element in the SAML v2.0 assertion. Use a custom class when the AuthnStatement element created by the default provider doesn’t meet your needs.

The class must implement the org.forgerock.openam.sts.tokengeneration.saml2.statements.AuthenticationStatementsProvider interface and must be bundled in the AM .war file.

Custom AttributeStatements Class Name

(Optional) The name of a custom class that generates an AttributeStatement element in the SAML v2.0 assertion. Use a custom class when the AttributeStatement element created by the default provider doesn’t meet your needs.

The class must implement the org.forgerock.openam.sts.tokengeneration.saml2.statements.AttributeStatementsProvider interface and must be bundled in the AM .war file.

Custom Authorization Decision Statements Class Name

(Optional) The name of a custom class that generates an AuthzDecisionStatement element in the SAML v2.0 assertion. Use a custom class when the AuthzDecisionStatement element created by the default provider doesn’t meet your needs.

The class must implement the org.forgerock.openam.sts.tokengeneration.saml2.statements.AuthzDecisionStatementsProvider interface and must be bundled in the AM .war file.

Custom Attribute Mapper Class Name

The name of a custom attribute mapper class. An attribute mapper generates attribute elements to be included in the SAML v2.0 assertion.

The class must implement the org.forgerock.openam.sts.tokengeneration.saml2.statements.AttributeMapper interface and must be bundled in the AM .war file.

Custom Authentication Context Class Name

(Optional) The name of a custom class that generates an AuthnContext element in the SAML v2.0 assertion. Use a custom class when the AuthnContext element created by the default provider doesn’t meet your needs.

The class must implement the org.forgerock.openam.sts.tokengeneration.saml2.statements.AuthnContextMapper interface and must be bundled in the AM .war file.

By default, AM generates the AuthnContext element based on the input token type as follows:

  • For input AM tokens: urn:oasis:names:tc:SAML:2.0:ac:classes:PreviousSession

  • For input username tokens and OIDC ID tokens: urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport

  • For input X.509 tokens: urn:oasis:names:tc:SAML:2.0:ac:classes:X509

Attribute Mappings

Configures mappings between SAML v2.0 attribute names (map keys) and AM user profile attributes or session properties to generate Attribute elements in the SAML v2.0 assertion.

AM’s default attribute mapper generates Attribute elements as follows:

  • The map key populates the Attribute element’s Name property.

  • The user profile or session property value populates the Attribute element’s AttributeValue property.

When specifying map keys in the Attribute Mappings property, use the following format: [NameFormatURI]|SAML_ATTRIBUTE_NAME.

Map values enclosed in quotes are included in the attribute without mapping. Add ;binary to the end of a map value for attributes with binary values.

The following are examples of attribute mappings:

  • EmailAddress=mail

  • Address=postaladdress

  • urn:oasis:names:tc:SAML:2.0:attrname-format:uri|urn:mace:dir:attribute-def:cn=cn

  • partnerID="staticPartnerIDValue"

  • urn:oasis:names:tc:SAML:2.0:attrname-format:uri|nameID="staticNameIDValue"

  • photo=photo;binary

  • urn:oasis:names:tc:SAML:2.0:attrname-format:uri|photo=photo;binary

Sign Assertion

Indicate whether to sign the SAML v2.0 assertion.

When enabling assertion signing, you must also specify the KeystorePath, Keystore Password, Signature Key Alias, and Signature Key Password properties.

Encrypt Assertion

Indicate whether to encrypt the entire SAML v2.0 assertion. When enabling assertion encryption:

  • You must also specify the KeystorePath, Keystore Password, and Encryption Key Alias properties.

  • You mustn’t specify the Encrypt Attributes or Encrypt NameID options.

The Encryption Key Alias corresponds to the public key of the service provider that is the intended audience of the assertion. SAML v2.0 assertion encryption works as follows:

  1. AM generates a symmetric key.

  2. AM encrypts the symmetric key with the recipient’s public key.

  3. AM includes the encrypted key in the part of the assertion that isn’t symmetric key-encrypted.

  4. The service provider (owner of the corresponding private key) uses the private key to decrypt the symmetric key included in the assertion.

  5. The service provider can then use the decrypted symmetric key to decrypt the assertion.

Encrypt Attributes

Indicate whether to encrypt the assertion’s attributes only. When specifying this option, don’t specify the Encrypt Assertion option.

When encrypting attributes, you must also specify the KeystorePath, Keystore Password, and Encryption Key Alias properties.

Encrypt NameID

Indicate whether to encrypt the assertion’s NameID only. When specifying this option, don’t specify the Encrypt Assertion option.

When encrypting the NameID, you must also specify the KeystorePath, Keystore Password, and Encryption Key Alias properties.

Encryption Algorithm

The encryption algorithm to use when encrypting the entire assertion, the assertion’s attributes, or the NameID.

Encryption Algorithm Strength

The encryption algorithm strength to use.

Key Transport Algorithm

The algorithm used to encrypt the symmetric encryption key when SAML v2.0 token encryption is enabled. Possible values are:

  • http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p.

  • http://www.w3.org/2009/xmlenc11#rsa-oaep.

    When this algorithm is configured, AM will use the Mask Generation Function Algorithm property (Configure > Global Services > Common Federation Configuration) to encrypt the transport key.

    Find a list of supported mask generation function algorithms in Algorithms.

  • http://www.w3.org/2001/04/xmlenc#rsa-1_5.

KeystorePath

The path to the JKS keystore containing the key aliases for encrypting and signing SAML assertions. Use an absolute path or a location in the AM classpath.

AM provides a JKS keystore with demo keys, /path/to/am/security/keystores/keystore.jks. Learn more in Secrets, certificates, and keys.

Keystore Password

The password used to decrypt the keystore.

Encryption Key Alias

The key alias in the keystore that holds the service provider’s X.509 certificate for this STS instance. This key alias is used to encrypt assertions.

Signature Key Alias

The private key alias in the keystore used to sign assertions.

Signature Key Password

The password of the private key used to sign the assertion.

OpenID Connect token configuration properties

The following are OIDC token configuration properties for STS instances:

The properties fall into two categories:

  • Properties that determine content in the issued OIDC ID token. Learn more about OIDC ID tokens in the OpenID Connect Core 1.0 specification.

  • Properties that determine how the issued token is signed.

An STS instance configured to issue OIDC tokens models the relationship between an OIDC token provider and relying party. In other words, an STS instance issues tokens for a particular OAuth 2.0 client. The tokens contain aud and azp claims for the OAuth 2.0 client, and signing key state corresponding to a token provider.

In this model, when users call an STS instance to generate an OIDC ID token, the process is analogous to the exchange between an OAuth 2.0 authorization server and resource owner following the initial redirection from an OAuth 2.0 client initiating the implicit flow. The STS instance returns the OIDC ID token that corresponds to the authorization server’s authentication of the resource owner.

AM authenticates the token specified as the input_token_state for the token transformation

Implicit in this model is the notion that an OIDC ID token has value outside of an OAuth 2.0 flow, and that an OAuth 2.0 client, as a relying party, could be generalized as a SAML v2.0 service provider. The ID token isn’t simply an an entity-provided verifiable authorized access to a specific resource, but rather a generic service provider that consumes an OIDC ID token to authenticate and authorize the subject asserted by the token.

Therefore, the configuration of an STS instance that issues OIDC ID tokens contains information that defines the token provider and relying party.

The nonce claim in the ID token isn’t a configuration property of an STS instance. STS consumers requesting an output OIDC token provide a nonce value when making token transformation requests.
OpenID Connect Token Provider ID

The OIDC token provider issuer ID. Populates the iss claim of the ID token.

Token Lifetime(Seconds)

The ID token’s expiration in seconds. Populates the exp claim of the ID token.

Token Signature Algorithm

An HMAC or RSA algorithm used to sign ID tokens.

Public Key Reference Type

Indicate how public keys should be referenced in issued ID tokens signed with RSA. OIDC ID tokens are issued as JSON web tokens (JWTs). Tokens can reference RSA public keys as JSON web keys (JWKs), or not at all.

Used with RSA signing.

KeyStore Location

The path to the JKS keystore containing the key alias for signing the ID token. Use an absolute path or a location in the AM classpath.

Used with RSA signing.

AM provides a JKS keystore with demo keys, /path/to/am/security/keystores/keystore.jks. Learn more about keystores in Secrets, certificates, and keys.

KeyStore Password

The password used to decrypt the keystore.

Used with RSA signing.

KeyStore Signing Key Alias

The private key alias in the keystore used to sign the ID token.

Used with RSA signing.

Signature Key Password

The password of the private key alias used to sign the ID token.

Used with RSA signing.

Client secret

The secret shared between the client and the ID token generator used to sign the ID token.

Used with HMAC signing.

Issued Tokens Audience

The intended audience for the ID token. Populates the aud claim of the ID token.

Authorized Party

The party to which the ID token is being issued. Populates the azp claim of the ID token.

Claim Map

The additional claim entries to be inserted into the ID token.

The entries use the format claim-name=user-profile-attribute. When issuing the ID token, AM populates the claim value with the value of the attribute in the authenticated user’s profile.

For example, suppose the Claim map property had an entry with the value email=mail. A generated OIDC ID token for user Sam Carter would contain the claim "email":"scarter@example.com" if the mail attribute in Sam Carter’s user profile had the value scarter@example.com.

Custom Claim Mapper Class

The name of a custom claim mapper class. A claim mapper generates additional claims to be included in the OIDC ID token.

The class must implement the org.forgerock.openam.sts.tokengeneration.oidc.OpenIdConntectTokenClaimMapper interface and must be bundled in the AM .war file.

Custom Authn Context Mapper Class

The name of a custom class that generates an acr claim in the OIDC ID token. An acr claim indicates which authentication context class was satisfied by the authentication of the principal asserted in the OIDC ID token. The acr claim is optional and isn’t included in the generated ID token by default.

The class must implement the org.forgerock.openam.sts.rest.token.provider.oidc.OpenIdConnectTokenAuthnContextMapper interface and must be bundled in the AM .war file.

Custom Authn Methods References Mapper Class

The name of a custom class that generates an amr claim in the OIDC ID token. An amr claim indicates which authentication methods were used to authenticate the principal asserted in the OIDC ID token. The amr claim is optional and isn’t included in the generated ID token by default.

The class must implement the org.forgerock.openam.sts.rest.token.provider.oidc.OpenIdConnectTokenAuthMethodReferencesMapper interface and must be bundled in the AM .war file.