About the REST STS

AM's REST STS service provides an easier deployment alternative to SOAP STS to issue OpenID Connect 1.0 or SAML v2.0 tokens for a single service provider. Each REST STS instance is configured with the following elements:

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.

For signing and encryption support, each REST STS instance has a configuration state, which specifies the keystore location containing the signing and encryption keys:

If assertion signature is configured, the keystore path and password must be specified, as well as the alias and password corresponding to the PrivateKey used to sign the assertion.
If assertion encryption is configured, the keystore path and password must be specified, as well as the alias corresponding the SP’s X509Certificate encapsulating the PublicKey used to encrypt the symmetric key used to encrypt the generated assertion.
Note that the keystore location can be specified via an absolute path on the local filesystem, or a path relative to the AM classpath. Either the entire assertion can be encrypted, or the NameID and/or AttributeStatement Attributes.

All statements constituting 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 the custom plug-ins in the configuration state of the published REST STS instance, the custom classes are consulted to provide the specific statements. See the interfaces in the org.forgerock.openam.sts.tokengeneration.saml2.statements package for details.

Each REST STS instance must specify the authentication context (that is, AuthnContext) to be included in the AuthenticationStatements of the generated assertion. This AuthnContext allows the generated SAML v2.0 assertion to specify the manner in which the assertion’s subject was authenticated. For a token transformation, this AuthnContext is a function of the input token type. By default, the following AuthnContext strings will be included in the SAML v2.0 assertion generated as part of the transformation of the following input token types:

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

Note that you can override these default mappings by implementing the org.forgerock.openam.sts.token.provider.AuthnContextMapper interface, and specifying the name of this implementation in the configuration of the published REST STS instance.

If you are interested in the REST STS, you should be familiar with the following specifications before setting up your deployment:

"Basic REST STS Model" illustrates a simple REST STS topology between a requestor, web service, and STS. The STS instance is set up with the identity provider, which has an existing trust relationship with the web service. The difference between the REST STS versus the SOAP STS is that REST STS does not strictly follow the WS-Trust specification for input token and output token formats. However, the REST STS provides a simpler means to deploy an STS instance, compared to that of the SOAP STS.

Basic REST STS Model

A simple REST STS process flow is as follows:

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 to the STS endpoint. The request includes credentials, token input type, and desired token output type. An example curl request is shown below:

$ 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

Or, you can run a command for 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 validates the signature, decodes the payload, and verifies that the requestor issued the transaction. The STS validates the requestor's credentials, creates an interim AM session, and optionally, creates a CTS token for the session. The STS then issues a token to the requestor. If STS is configured to invalidate the interim AM session, it does so. The requestor gets redirected to the web service.
The requestor presents the token to the web service. The web service validates the signature, decodes the payload, and verifies that the requestor issued the request. It then 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 upon request.

Validating Input Tokens

STS token transformations validate input tokens before generating output tokens. 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 mentions security issues you should consider 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 module or chain to be used to validate each input token type. To do so, configure the Authentication Target Mappings property in the STS instance configuration. For more information about this property, see Reference.

Validating 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 forth.

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.

Validating 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 that 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 configured 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 optionally check to see that the specified certificate is in a LDAP datastore.

If certificates are passed to 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 your REST STS instance's configuration.

Validating 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:

Specify a header in the Name of header referencing the ID Token property. The REST STS instance's Target Authentication Mapping property must reference the same header.
Specify the issuer name in the Name of OpenID Connect ID Token Issuer property, and configure the token issuer's discovery URL, JWK URL or, client secret in the OpenID Connect validation configuration value property.
If incoming OpenID Connect tokens contain azp claims, specify valid claims in the List of accepted authorized parties property.
If incoming OpenID Connect tokens contains aud claims, specify the valid claim in the Audience property.
Configure attribute mappings so that JWK claims map to attributes in the AM user store.

For more information about OpenID Connect id_token bearer authentication module properties, see "OpenID Connect id_token bearer Module".

Note

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