PingAM 7.5.0

Shared STS configuration properties

These properties are available in both the REST and STS configuration pages.

Issued SAML v2.0 token configuration properties

This section lists configuration properties associated with STS-issued SAML v2.0 assertions. The properties fall into two categories:

  1. Properties that determine content in STS-issued SAML v2.0 assertion. For information about SAML v2.0 assertions, see Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0.

  2. Properties that determine how the issued SAML v2.0 assertion is signed or encrypted.

The SAML2 Issuer Id

Specifies the IDP entity ID. Populates the Issuer element of the SAML v2.0 assertion.

Service Provider Entity Id

Specifies 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

Specifies 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

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

Token Lifetime(Seconds)

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

Custom Conditions Provider Class Name

Specifies the name of a custom class that generates a Conditions element in the SAML v2.0 assertion. This property is optional: use a custom class when the Conditions element created by the default provider does not 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

Specifies the name of a custom class that generates a Subject element in the SAML v2.0 assertion. This property is optional: use a custom class when the Subject element created by the default provider does not 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

Specifies the name of a custom class that generates an AuthnStatement element in the SAML v2.0 assertion. This property is optional: use a custom class when the AuthnStatement element created by the default provider does not 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

Specifies the name of a custom class that generates an AttributeStatement element in the SAML v2.0 assertion. This property is optional: use a custom class when the AttributeStatement element created by the default provider does not 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

Specifies the name of a custom class that generates an AuthzDecisionStatement element in the SAML v2.0 assertion. This property is optional: use a custom class when the AuthzDecisionStatement element created by the default provider does not 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

Specifies 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

Specifies the name of a custom class that generates an AuthnContext element in the SAML v2.0 assertion. This property is optional: use a custom class when the AuthnContext element created by the default provider does not 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 OpenID Connect 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—[term]map keys—and AM user profile attributes or session properties in order 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. Specify ';binary' at the end of a map value for attributes that have 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

Specifies whether or not 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

Specifies 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 must not 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 is not 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

Specifies whether to encrypt the assertion’s attributes only. When specifying this option, do not specify the Encrypt Assertion option.

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

Encrypt NameID

Specifies whether to encrypt the assertion’s NameID only. When specifying this option, do not specify the Encrypt Assertion option.

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

Encryption Algorithm

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

Key Transport Algorithm

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

    For a list of supported mask generation function algorithms, see Algorithms.

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

KeystorePath

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

AM provides a JKS keystore with demo keys, /path/to/openam/security/keystores/keystore.jks. For more information about keystores in AM, see Secrets, certificates, and keys.

Keystore Password

Specifies the password used to decrypt the keystore.

Encryption Key Alias

Specifies 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

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

Signature Key Password

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

Issued OpenID Connect token configuration properties

This section lists configuration properties associated with STS-issued OpenID Connect tokens. The properties fall into two categories:

  1. Properties that determine content in the issued OpenID Connect ID token. For information about OpenID Connect ID tokens, see the OpenID Connect Core 1.0 specification.

  2. Properties that determine how the issued token is signed.

An STS instance configured to issue OpenID Connect tokens models the relationship between an OpenID Connect 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 OpenID Connect 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 OpenID Connect ID token that corresponds to the authorization server’s authentication of the resource owner.

AM authenticates one of the following:

  • For REST STS, the token specified as the input_token_state for the token transformation

  • For SOAP STS, the supporting token necessary to traverse the SecurityPolicy bindings protecting the WS-Trust operation

Implicit in this model is the notion that an OpenID Connect 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 is not simply an an entity-provided verifiable authorized access to a specific resource, but rather a generic service provider that consumes an OpenID Connect ID token to authenticate and authorize the subject asserted by the token.

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

Note that the nonce claim in the ID token is not a configuration property of an STS instance. STS consumers requesting an output OpenID Connect token provide a nonce value when making token transformation requests.

OpenID Connect Token Provider ID

Specifies the OpenID Connect token provider issuer ID. Populates the iss claim of the ID token.

Token Lifetime(Seconds)

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

Token Signature Algorithm

Specifies an HMAC or RSA algorithm used to sign ID tokens.

Public Key Reference Type

Specifies how public keys should be referenced in issued ID tokens signed with RSA. OpenID Connect 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

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

Used with RSA signing.

AM provides a JKS keystore with demo keys, /path/to/openam/security/keystores/keystore.jks. For more information about keystores in AM, see Secrets, certificates, and keys.

KeyStore Password

Specifies the password used to decrypt the keystore.

Used with RSA signing.

KeyStore Signing Key Alias

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

Used with RSA signing.

Signature Key Password

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

Used with RSA signing.

Client secret

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

Used with HMAC signing.

Issued Tokens Audience

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

Authorized Party

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

Claim Map

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

Specifies entries using 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 OpenID Connect 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

Specifies the name of a custom claim mapper class. A claim mapper generates additional claims to be included in the OpenID Connect 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

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

For REST STS instances, the class must implement the org.forgerock.openam.sts.rest.token.provider.oidc.OpenIdConnectTokenAuthnContextMapper interface and must be bundled in the AM .war file.

For SOAP STS instances, the class must implement the org.forgerock.openam.sts.soap.token.provider.oidc.SoapOpenIdConnectTokenAuthnContextMapper interface and must be bundled into the SOAP STS deployment .war file.

Custom Authn Methods References Mapper Class

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

For REST STS instances, the class must implement the org.forgerock.openam.sts.rest.token.provider.oidc.OpenIdConnectTokenAuthMethodReferencesMapper interface and must be bundled in the AM .war file.

For SOAP STS instances, the class must implement the org.forgerock.openam.sts.soap.token.provider.oidc.SoapOpenIdConnectTokenAuthnMethodReferencesMapper interface and must be bundled into the SOAP STS deployment .war file.