STS instances

AM’s Security Token Service (STS) issues OpenID Connect v1.0 (OIDC) or SAML v2.0 tokens for a single service provider. An STS instance has the following mandatory configuration:

Issuer. The issuer corresponds to the IdP EntityID.
SP EntityID. The SP EntityID is used in the AudienceRestriction element of the Conditions statement of the issued assertion.
SP assertion consumer service URL. The SP assertion consumer service URL is used as the Recipient attribute of the subjectConfirmation element in the Subject statement, which is required for bearer assertions according to the Web SSO profile.

To support signing and encryption, each STS instance has a configuration state that specifies the location of the signing and encryption keys:

If you use assertion signature, you must specify the keystore path and password and the alias and password of the PrivateKey used to sign the assertion.
If you use assertion encryption, you must specify the keystore path and password. You must also must specify the alias of the SP’s X509 certificate that includes the PublicKey used to encrypt the symmetric key that encrypts the generated assertion.

The keystore location can be an absolute path on the local filesystem or a path relative to the AM classpath. You can choose to encrypt only the NameID and AttributeStatement attributes or the entire assertion.

Any statement that constitutes a SAML v2.0 assertion can be customized.

For each STS instance, you can provide custom plug-ins for Conditions, Subject, AuthenticationStatements, AttributeStatements, and AuthorizationDecisionStatements. If you specify custom plug-ins in the configuration state of the published STS instance, the custom classes are consulted to provide the specific statements. Learn more in org.forgerock.openam.sts.tokengeneration.saml2.statements.

Each STS instance must specify the authentication context (AuthnContext) that will be included in the AuthenticationStatements of the generated assertion. The AuthnContext lets the generated SAML v2.0 assertion specify how the assertion’s subject was authenticated. For a token transformation, the AuthnContext is a function of the input token type.

By default, the following AuthnContext strings are included in the SAML v2.0 assertion generated as part of the transformation of the following input token types:

Input token type AuthnContext string

Input token type	`AuthnContext` string
AM	`urn:oasis:names:tc:SAML:2.0:ac:classes:PreviousSession`
Username Token and OIDC Token	`urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport`
X.509 Token	`urn:oasis:names:tc:SAML:2.0:ac:classes:X509`

urn:oasis:names:tc:SAML:2.0:ac:classes:PreviousSession

Username Token and OIDC Token

urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport

X.509 Token

urn:oasis:names:tc:SAML:2.0:ac:classes:X509

To override these default mappings, implement the org.forgerock.openam.sts.token.provider.AuthnContextMapper interface and specify the name of the implementation in the configuration of the published STS instance.

Read the following specifications before you implement the STS:

The STS model illustrates a simple STS topology between a requestor, a web service, and an STS instance. The STS instance is set up with the identity provider, which has a trust relationship with the web service:

Figure 1. STS model

STS process flow

A requestor makes an access request to a web resource.
The web service redirects the requestor to the STS.

The requestor sends an HTTP(S) POST request to the STS endpoint. The request includes credentials, token input type, and desired token output type.

The following example generates a bearer token:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--data '{
    "input_token_state": {
        "token_type": "USERNAME",
        "username": "bjensen",
        "password": "Ch4ng31t"
    },
    "output_token_state": {
        "token_type": "SAML2",
        "subject_confirmation": "BEARER"
    }
}' \
https://am.example.com:8443/am/rest-sts/username-transformer?_action=translate

The following example generates an OIDC token:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--data '{
    "input_token_state": {
        "token_type": "USERNAME",
        "username": "bjensen",
        "password": "Ch4ng31t"
    },
    "output_token_state": {
        "token_type": "OPENIDCONNECT",
        "nonce":"12345678",
        "allow_access":true
    }
}' \
https://am.example.com:8443/am/rest-sts/username-transformer?_action=translate

The STS does the following:
1. Validates the signature.
2. Decodes the payload and verifies that the requestor issued the transaction.
3. Validates the requestor’s credentials.
4. Creates an interim AM session and, optionally, creates a CTS token for the session.
5. Issues a token to the requestor.
6. Invalidates the interim AM session, if configured.
The requestor is redirected to the web service and presents its token to the web service.
The web service does the following:
1. Validates the signature and decodes the payload.
2. Verifies that the requestor issued the request.
3. Extracts and validates the token and processes the request.
If a CTS token was created for the session, the web service can call the STS to invalidate the token and the corresponding AM session.

Validate input tokens

STS token transformations validate input tokens before generating output tokens. The STS uses authentication trees to perform token validation. When deploying STS, you must configure an appropriate authentication tree to validate input tokens.

This section describes authentication configuration requirements for username, X.509, and OIDC tokens. No special authentication configuration is required when using AM session tokens as the input tokens in token transformations.

Because STS instances aren’t part of a secure framework like WS-Trust, this section also discusses security considerations when sending tokens across a network to an STS instance.

In addition to configuring AM authentication to support input token validation, you must identify the authentication tree that will validate each input token type. To do so, configure the Authentication Target Mappings property in the STS instance configuration. Learn more in the STS configuration properties.

Validate username tokens

Username tokens passed to an STS instance contain the username/password combination in cleartext. Tokens can be validated using any tree that supports username/password authentication.

With usernames and passwords in cleartext, be sure to configure your deployment with an appropriate level of security. Deploy STS instances that support input username token transformations over TLS.

Validate X.509 certificate tokens

STS instances can obtain X.509 certificates used as input tokens in two ways:

From the header key defined in the STS instance’s Client Certificate Header Key property. In this case, STS also confirms the request came from a host specified in the Trusted Remote Hosts property.
From the jakarta.servlet.request.X509Certificate attribute in the ServletRequest. If you don’t set a header key in the Client Certificate Header Key property, the STS instance obtains the X.509 certificate from the ServletRequest.

To validate X.509 certificate tokens, an STS instance must reference a tree that includes the Certificate Collector node and the Certificate Validation node in the Authentication Target Mappings property.

The Certificate Validation node validates the X.509 certificate input token. The node optionally performs Certificate Revocation List (CRL) or Online Certificate Status Protocol (OCSP) checking, and can check that the specified certificate is in an LDAP datastore.

If certificates are passed to the STS using HTTP headers, you must configure the HTTP Header Name for the Client Certificate and the Trusted Remote Hosts properties in the Certificate Collector node to match the configuration of your STS instance.

Validate OIDC tokens

To validate OIDC input tokens, an STS instance must reference a tree that includes the OIDC ID Token Validator node in the Authentication Target Mappings property.

Configure the OIDC ID Token Validator node as follows:

ID Token Header Name: Specify a header. The STS instance’s Target Authentication Mapping property must reference the same header.
Token Issuer: Specify the issuer name. Set the token issuer’s discovery URL, JWK URL, or client secret in the OpenID Connect validation configuration value property.
Audience name: If incoming OIDC tokens contains aud claims, specify the valid claims in this property.
Authorized parties: If incoming OIDC tokens contain azp claims, specify valid claims in this property.
Transformation Script: Select a Social Identity Provider Profile Transformation script to map JWK claims to attributes in the identity store.

PingAM 8.0.0

STS instances

STS process flow

Validate input tokens

Validate username tokens

Validate X.509 certificate tokens

Validate OIDC tokens