--- title: STS configuration properties description: A string that identifies this STS instance. component: pingam version: 8.1 page_id: pingam:sts:sts-configure-rest-properties canonical_url: https://docs.pingidentity.com/pingam/8.1/sts/sts-configure-rest-properties.html keywords: ["Security Token Service (STS)", "Rest", "Configuration", "Authentication", "Certificates"] page_aliases: ["sts-guide:sts-configure-rest-properties.adoc"] section_ids: general_configuration_properties: General configuration properties deployment_configuration_properties: Deployment configuration properties saml2_token_configuration_properties: SAML2 token configuration properties sts-issued-openid-token-props: OpenID Connect token configuration properties --- # 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](sts-custom-token-types.html). * 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](sts-custom-token-types.html). * 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 2.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](https://docs.pingidentity.com/auth-node-ref/8.1/certificate-collector.html) or [OIDC ID Token Validator node](https://docs.pingidentity.com/auth-node-ref/8.1/oidc-idtoken-validator.html) 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 2.0 token configuration properties for STS instances: The properties fall into two categories: * Properties that determine content in STS-issued SAML 2.0 assertions. Learn more about SAML 2.0 assertions in [Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) 2.0](https://www.oasis-open.org/committees/download.php/35711/sstc-saml-core-errata-2.0-wd-06-diff.pdf). * Properties that determine how the issued SAML 2.0 assertion is signed or encrypted. - The SAML2 Issuer Id The IdP entity ID. Populates the `Issuer` element of the SAML 2.0 assertion. - Service Provider Entity Id An audience attribute value. Populates the `AudienceRestriction` sub-element of the `Conditions` element of the SAML 2.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 2.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 2.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 2.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 2.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 2.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 2.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 2.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 2.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 2.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 2.0 attribute names (*map keys*) and AM user profile attributes or session properties to generate `Attribute` elements in the SAML 2.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 2.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 2.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 2.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 2.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](../setup/services-configuration.html#global-federation-common-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](../security/secrets-certs-keys.html). - 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](https://openid.net/specs/openid-connect-core-1_0.html#IDToken). * 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 2.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](../security/secrets-certs-keys.html). * 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.