REST STS

AM’s REST STS service issues OIDC v1.0 or SAML v2.0 tokens for a single service provider. A REST 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 REST 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 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 REST 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 REST STS instance, the custom classes are consulted to provide the specific statements. For details, refer to the interfaces in the org.forgerock.openam.sts.tokengeneration.saml2.statements package.

Each REST 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 OpenID Connect 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 OpenID Connect 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 REST STS instance.

Read the following specifications before you implement the REST STS:

The Basic REST STS model illustrates a simple REST 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.

Unlike the SOAP STS, the REST STS does not strictly follow the WS-Trust specification for input token and output token formats; however, the REST STS makes it much easier to deploy an STS instance.

Figure 1. Basic REST STS model

REST 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": "demo",
        "password": "Ch4ng31t"
    },
    "output_token_state": {
        "token_type": "SAML2",
        "subject_confirmation": "BEARER"
    }
}' \
https://openam.example.com:8443/openam/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": "demo",
        "password": "Ch4ng31t"
    },
    "output_token_state": {
        "token_type": "OPENIDCONNECT",
        "nonce":"12345678",
        "allow_access":true
    }
}' \
https://openam.example.com:8443/openam/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 REST 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 AM authentication modules and chains to perform token validation. When deploying STS, you must configure AM authentication so that it can validate input tokens.

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

Because REST STS instances are not part of a secure framework like WS-Trust 1.4, this section also discusses security considerations when sending tokens across a network to a REST STS instance.

In addition to configuring AM authentication to support input token validation, you must identify the authentication tree or module that will validate each input token type. To do so, configure the Authentication Target Mappings property in the STS instance configuration. For details, refer to Reference.

Validate username tokens

Username tokens passed to a REST STS instance contain the username/password combination in cleartext. Tokens can be validated using any module type that supports username/password authentication, including Data Store, LDAP, and so on.

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

Validate X.509 certificate tokens

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

From the header key defined in the REST 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 javax.servlet.request.X509Certificate attribute in the ServletRequest. The REST STS instance obtains the X.509 certificate from the ServletRequest if no header key is set in the Client Certificate Header Key property.

The AM Certificate module authenticates the X.509 certificate input token. The module 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 REST STS using HTTP headers, you must configure the Trusted Remote Hosts and Http Header Name for Client Certificate properties in the Certificate module to match the configuration of your REST STS instance.

Validate OpenID Connect tokens

To validate OpenID Connect input tokens, a REST STS instance must reference an OpenID Connect id_token bearer authentication module in the Authentication Target Mappings property.

Configure the authentication module as follows:

Name of header referencing the ID Token: Specify a header. The REST STS instance’s Target Authentication Mapping property must reference the same header.
Name of OpenID Connect ID 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.
List of accepted authorized parties: If incoming OpenID Connect tokens contain azp claims, specify valid claims in this property.
Audience: If incoming OpenID Connect tokens contains aud claims, specify the valid claims in this property.
Attribute mappings: Map JWK claims to attributes in the AM user store.

For more information about OpenID Connect id_token bearer authentication module properties, refer to OpenID Connect id_token bearer module.

SOAP STS instances do not accept OpenID Connect tokens as input tokens in token transformations.

PingAM 7.5.0

REST STS

REST STS process flow

Validate input tokens

Validate username tokens

Validate X.509 certificate tokens

Validate OpenID Connect tokens