Access Management 7.4.1

Security Token Service (STS)

These topics cover concepts, configuration, and usage procedures for working with the Security Token Service provided by ForgeRock Access Management.

This information is intended for anyone using the Security Token Service in Access Management to manage token exchange.

Secure Token Service overview

Learn how the STS can transform, validate, issue, and cancel tokens.
Configure the Secure Token Service

Add one or more STS instances to your AM deployment.
Query, validate, and cancel tokens

Manage tokens stored in the CTS token store.

ForgeRock® Identity Platform serves as the basis for our simple and comprehensive Identity and Access Management solution. We help our customers deepen their relationships with their customers, and improve the productivity and connectivity of their employees and partners. For more information about ForgeRock and about the platform, see https://www.forgerock.com.

STS overview

The Security Token Service (STS) lets AM bridge identities across existing federated environments to establish cross-domain trust relationships using token transformations. For example, you can federate two different environments by transforming OpenID Connect ID tokens into SAML v2.0 assertions.

The WS-Trust specification introduces the concept of a centralized runtime component called the Security Token Service (STS), which issues, cancels, and validates security tokens. A WS-Trust model involves communication between the components, a requestor, web service, and STS:

  • The requestor is a web client or programmatic agent that wants to use a service offered by the web service.

  • The web service allows authenticated and authorized clients to access resources or applications.

  • The identity provider stores claims about subjects and works with the STS to issue security tokens.

  • The STS acts as a trusted third-party web service that asserts the identity of a requestor across different security domains through the exchange of security tokens and brokers a trust relationship between the requestor and the web service provider. The STS issues tokens based on its configurations, which model the identity of a given identity provider, and issues tokens to a specific relying party.

  • A security token is an STS data structure representing a set of claims that assert the identity of a subject. A single claim is identity information, such as a subject’s name, age, gender, and email address.

  • A security policy, defined in WS-SecurityPolicy, specifies the required elements, tokens, security bindings, supporting tokens, and protocol assertions, which are requirements for a web service to grant a subject access to its service.

    The security policy is defined in a WSDL document, which is an XML file that states what needs to be protected, what tokens are allowed for access, and transmission requirements for SOAP STS.

Web services and requestors (that is, consumers or clients) are typically deployed across different security domains and topologies. Each domain may require a specific security token type to assert authenticated identities. STS provides a means to exchange tokens across these different domains without re-authenticating or re-establishing trust relationships while allowing the requestor access to a web service’s protected resources.

Based on this standard, AM provides two Security Token Services:

  • REST STS, a REST-based Security Token Service that provides a simpler deployment alternative than SOAP STS for token transformations. The REST STS does not conform to the WS-Trust specification.

  • SOAP STS, a WS-Trust 1.4-compliant Security Token Service.

    The AM SOAP STS is built upon the Apache CXF STS, an open-source implementation of JAX-WS and JAX-RS, as well as Apache WSS4j, an open-source Java implementation of the WS-Security specification.

    The SOAP STS service is deprecated, and will be removed in a future release. Installing instances of this service is not supported.

Differences between REST STS and SOAP STS

Because the SOAP STS implementation is based on the WS-Trust specification and the REST STS implementation is not, there are differences between the features they support. They are summarized in the table below:

Differences between the STS implementations
Feature Description REST STS SOAP STS

REST endpoints

REST endpoints exposed upon instance creation.

✔

✖

SOAP endpoints

AM .war and the SOAP STS .war files must be deployed in separate web containers to expose the SOAP endpoints.

✖

✔

Token transformations

AM STS issues OpenID Connect V1.0 (OIDC) and SAML V2.0 tokens (bearer, holder-of-key, sender vouches).

Username token → OIDC
OIDC → OIDC
X.509 token → OIDC
AM Session token → OIDC

Username token → SAML v2.0
X.509 token → SAML v2.0
(REST STS only) OIDC token → SAML v2.0
AM Session token → SAML v2.0

✔

✔

Publish service

You can configure REST or SOAP STS instances using the AM admin UI or programmatically. AM provides a REST STS publish service that allows you to publish these instances using a POST to the endpoints. Note that a published instance can have only a single encryption key. Therefore, you need one published instance per service provider that the web service invoking the STS intends to call.

✔

✔

Custom SAML assertion plugins

AM supports customizable SAML assertion statements. You can create custom plug-ins for Conditions, Subject, AuthenticationStatements, AttributeStatements, and AuthorizationDecisionStatements statements.

✔

✔

Custom token validators and providers

The AM REST STS provides the ability to customize tokens that are not supported by default by the STS. For example, you can configure STS to transform a token of type CUSTOM to a SAML V2.0 token.

✔

✖

Client SDK

AM provides a SOAP STS client SDK module to allow developers to use Apache CXF-STS classes.

✖

✔

ActAs and OnBehalfOf elements

AM SOAP STS supports delegated and proxied token relationships, as defined by the ActAs and OnBehalfOf elements in WS-Trust, which is available for Username and AM session tokens.

✖

✔

Security binding assertions

AM SOAP STS supports the WS-SecurityPolicy binding assertions that protect communication to and from the STS: transport, asymmetric, symmetric.

✖

✔

Custom WSDL

The AM SOAP STS comes with a pre-configured WSDL file. You can customize the policy bindings governing the input or output messages to or from the STS.

✖

✔

Logging service

The AM STS allows SOAP-STS log entries to be configured via java.util.logging, which allows logging to be configured via the logging.properties file in the Tomcat conf directory.

✖

✔

For more information about both implementations, see:

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

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

A simple REST STS model.
Figure 1. Basic REST STS model

REST STS process flow

  1. A requestor makes an access request to a web resource.

  2. The web service redirects the requestor to the STS.

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

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

  5. The requestor is redirected to the web service and presents its token to the web service.

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

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

SOAP STS

AM lets AM administrators publish WS-Trust 1.4-compliant STS instances, each with a distinct security policy configuration, and each issuing OpenID Connect (OIDC) v1.0 Tokens or SAML v2.0 (bearer, holder of key, and sender vouches) assertions.

The SOAP STS is deployed remotely from AM in a Tomcat or Jetty container. Deploying both the AM .war and the SOAP STS .war in the same container is not supported. The remotely-deployed SOAP STS .war file authenticates to AM with SOAP STS agent credentials, and pulls the configuration state for all SOAP instances published in its realm, exposing WS-Trust-compliant SOAP web services based on this configuration state.

AM is the authentication authority for the STS instances and its configured data stores, which store the attributes that are included in OIDC tokens and generated SAML v2.0 assertions.

You can publish any number of SOAP STS instances programmatically, or by using the AM admin UI. Each instance is published with a specific WS-SecurityPolicy binding, which specifies:

  • Type of supporting token that asserts the caller’s identity.

  • Manner in which the supporting token is protected (symmetric, asymmetric, or transport binding).

Each published SOAP STS instance is protected by a security policy binding, which specifies what type of token must be presented to assert the caller’s identity (also known as the supporting token), and how this supporting token is protected. There are three protection schemes: transport, symmetric, and asymmetric:

  • Transport binding assertion. Transport binding is used when the message is protected at the transport level, such as HTTPS, and thus requires no explicit enforcement at the security policy binding enforcement level. The SOAP keystore configuration allows a SOAP STS instance to be published referencing the keystore state necessary to enforce the symmetric and asymmetric bindings.

  • Symmetric binding assertion. Symmetric binding is used when only one party needs to generate security tokens. In a symmetric binding, the client generates symmetric key state used to sign and encrypt messages, and encrypts this symmetric key state with the STS’s public key, and includes the encrypted symmetric key in the request. Thus, the SOAP keystore configuration of a published STS instance, which is protected by the symmetric binding, must reference a keystore with the STS’s PrivateKeyEntry, so that it may decrypt the symmetric key generated by the client.

  • Asymmetric binding assertion. Asymmetric binding is used when both the client and the service both have security tokens. In an asymmetric binding, client requests are signed with the client’s secret key, and encrypted with the STS’s public key. STS responses are signed with the STS’s private key and encrypted with the client’s public key. The client’s X.509 certificate is included in the request, so that the STS can validate the client’s signature and encrypt responses to the client without requiring the presence of the client’s X.509 certificate in the STS’s keystore. However, the SOAP keystore configuration of a published STS instance protected by an asymmetric binding must reference a keystore with the STS’s PrivateKeyEntry, which allows the STS to both: 1) sign messages from STS to client, and 2) decrypt messages from the client.

    The Decryption Key Alias in a SOAP STS instance’s configuration corresponds to the PrivateKeyEntry.

The following bindings are available:

UsernameToken over the transport, symmetric, and asymmetric binding
AM session token over the transport and unprotected binding
X.509 certificates examples seen in WS-SecurityPolicy Examples Version 1.0

A SAML v2.0 assertion, defined in SAML V2.0, contains a Subject element that identifies the principal, which is the subject of the statements in the assertion. The Subject element contains an identifier and zero or more SubjectConfirmation elements, which allows a relying party to verify the subject of the assertion with the entity with whom the relying party is communicating.

The SubjectConfirmation element contains a required Method attribute that specifies the URI identifying the protocol used to confirm the subject. The AM STS supports the following subject confirmation methods:

  • Holder of key. The holder of key subject confirmation method involves proving a relationship between the subject and claims. This is achieved by signing part of the SOAP message with a proof key sent in the SAML assertion. The additional proof key guards against any attempted man-in-the-middle attack by ensuring that the SAML assertion comes from the subject claiming to be the requestor.

    URI: urn:oasis:names:tc:SAML:2.0:cm:holder-of-key

  • Sender vouches. The sender vouches subject confirmation method is used in cases where you have a proxy gateway that propagates the client identity via the SOAP messages on behalf of the client. The proxy gateway must protect the SOAP message containing the SAML assertion, so that the web service can verify that it has not been tampered with.

    URI: urn:oasis:names:tc:SAML:2.0:cm:sender-vouches

  • Bearer. The bearer subject confirmation method assumes that a trust relationship exists between the subject and the claims, and thus no keys are required when using a bearer token. No additional steps are required to prove or establish a relationship.

    Since browser-based clients use bearer tokens and no keys are required, you must protect the SOAP message using a transport-level mechanism, such as SSL, as this is the only means to protect against man-in-the-middle attacks.

    URI: urn:oasis:names:tc:SAML:2.0:cm:bearer

If you are interested in the SOAP STS, you should be familiar with the SOAP STS specifications:

The Basic SOAP STS model illustrates a basic SOAP 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.

A basic SOAP STS model. The STS is associated with a identity provider-service provider combination.
Figure 2. Basic SOAP STS model

A basic SOAP STS process flow is as follows:

  1. A requestor first accesses a protected resource for a web service. The requestor gets the web service’s WSDL file, which specifies the policy requirements to access its services.

  2. The requestor creates and configures an STSClient object whose main task is to contact the STS.

  3. The STSClient contacts the STS to obtain its WSDL file. Each published STS instance exposes an API that is defined in its WSDL file. The WSDL file specifies the security policy bindings, which specify the type of token they must present to the API, and how this token is protected during transit.

  4. The STSClient generates and sends a Request for Security Token (RST) to the STS. The RST specifies the what type of token is desired. The requestor’s usernameToken is embedded in the SOAP envelope that contains the RST and is used for authentication.

    The SOAP STS client SDK provides the classes, templates, and documentation to allow developers to set the state necessary to allow the Apache CXF runtime to generate the SOAP envelopt containing the RST, which satisfies the security policy bindings of the targeted STS.

  5. The STS validates the requestor’s usernameToken, creates an interim AM session, and optionally, creates a CTS token for the session. Upon successful authentication, the STS constructs a Request for Security Token Response (RSTR), signs the SAML v2.0 token, and embeds the token within the RSTR. If STS is configured to invalidate the interim token, it does so. The STS sends a Request for Security Token Response (RSTR) to the STSClient.

  6. The STSClient extracts the security token and sends it in the request’s message header. The STSClient sends the message to the web service.

  7. The web service extracts the SAML token and validates the signature to ensure that it came from the STS. The web service allows the user whose ID is specified in the SAML token to access its protected resource.

  8. If a CTS token was created for the session, the web service can call the SOAP STS to invalidate the token and the corresponding AM session upon request.

Delegated relationships in SOAP STS

SOAP STS supports the ability to issue SAML assertions with the sender vouches subject confirmation method. Sender vouches are used in proxy deployments, such as a proxying gateway, where the gateway requests a SAML assertion with a sender vouches confirmation from the STS.

In this case, the requestor’s credentials are set in the OnBehalfOf and ActAs elements in the request security token (RST) request included in the Issue invocation. The gateway calls the STS, and the gateway’s credentials satisfy the security policy bindings protecting the STS. The presence of either the OnBehalfOf and ActAs elements together with a token type of SAML v2.0 and a key type of PublicKey triggers the issuance of a sender vouches SAML v2.0 assertion.

STS can issue SAML v2.0 assertions with the sender vouches subject confirmation method.
Figure 3. STS sender vouches

The STS runs token validators that validate the authenticity of the ActAs or OnBehalfOf token.

The SOAP STS configuration indicates whether token delegation relationships are supported in the STS in the ActAs and OnBehalfOf elements. If token delegation is supported, the configuration also indicates the token types that token validators use to validate the ActAs and OnBehalfOf token elements.

In the Request for Security Token (RST) invocation, Username and AM tokens are supported for the OnBehalfOf element. In addition, you can specify that the SOAP STS instance be deployed with a user-specified implementation of the token delegation handler interface, org.apache.cxf.sts.token.delegation.TokenDelegationHandler.

A default token delegation handler is used if no custom token delegation handler is configured. The default token delegation handler rejects the delegation relationship if the token principal set to null in the token delegation parameters (that is, TokenDelegationParameters), as this is the case when no token validators have validated the ActAs and OnBehalfOf token. Thus, if you want the STS instance to support the ActAs and OnBehalfOf elements, you must specify one of the two following configuration properties:

  • The Delegation Relationships Supported property.

  • One or more Delegated Token types. For example, AM or Username for which token validators are deployed to validate the ActAs or OnBehalfOf tokens and/or a custom token delegation handler.

    If you configure the Username token type as a delegated token type, AM uses the configuration in the Authentication Target Mappings property to authenticate Username tokens. AM SSO tokens require no special configuration in the Authentication Target Mappings property.

Example proxy gateway STS deployment

Suppose you want to deploy the SOAP STS to receive requests from a proxy gateway and issue SAML v2.0 assertions with sender vouches subject confirmation method. The gateway sends the SAML v2.0 assertion that asserts the identity of the gateway client and vouches for its identity.

Suppose the SOAP STS deployment has a security policy binding requiring the presentation of an X.509 certificate. This security policy binding can be satisfied by presenting the gateway’s X.509 certificate. However, the SOAP STS-issued SAML v2.0 assertion should assert the identity of the gateway client that presents its identity to the gateway as either a username, password combination or as an AM session.

In this case, the published SOAP STS would specify an X.509-based security policy, the delegation relationships to be supported, and whether both AM and Username token types should be supported. No custom token delegation handler need be specified.

Furthermore, the SOAP STS instance must be published with Authentication Target Mappings that specify how the Username token should be presented to AM’s RESTful authentication context. The gateway code would then create a request for security token (RST) invocation using the classes in the openam-sts/openam-soap-sts/openam-soap-sts-client module, and include the gateway client’s username, password or AM session state as the OnBehalfOf element. This setting allows the gateway to consume the SOAP STS to issue SAML v2.0 assertions with the sender vouches subject confirmation method, which asserts the identity of the gateway client corresponding to the presented username, password or AM session state.

If, at a later date, you want to exclude or denylist some users from attaining SAML v2.0 assertions, regardless of their possession of valid username, password or AM session state, you can update the SOAP STS with the class name of a token delegation handler implementation, which would implement this denylist functionality. The SOAP STS .war file would have to be recreated with this file in the classpath. The token delegation handler could reject the invocation for users or principals on the denylist.

Configure STS instances

You configure STS instances to perform one or more token transformations. Each instance provides configuration details about how SAML v2.0 and/or OpenID Connect output tokens are encrypted or signed. Deployments that support multiple SAML v2.0 and/or OpenID Connect service providers require multiple STS instances.

When you publish an STS instance, you create an STS instance with a given configuration. You can publish instances using the AM admin UI or the REST API.

When you publish a REST STS instance, AM exposes a REST endpoint for accessing the instance, and the instance is immediately available for use to callers.

The SOAP STS service is deprecated, and will be removed in a future release. Installing instances of this service is not supported.

Configure the REST STS

To configure a REST STS instance using the AM admin UI, go to Realms > Realm Name > STS > REST STS Instances, and click Add.

See REST STS configuration properties for detailed information about STS configuration properties.

You can also publish REST STS instances programmatically. AM provides a Publish service, which is a collection of endpoints you can use to publish instances instead of accessing the AM admin UI.

For more information, see Publish REST STS instances.

Consume REST STS instances

You consume a REST STS instance by sending REST API calls to the instance’s endpoint.

REST STS instance endpoint

A REST STS instance endpoint is composed of the following:

  • The AM context

  • The string rest-sts

  • The realm in which the REST STS instance is configured

  • The deployment URL element (a configuration property of the STS instance)

For example, a REST STS instance configured in the realm myRealm with the deployment URL element username-transformer exposes the endpoint /rest-sts/myRealm/username-transformer.

JSON representation of token transformations

Token transformations are represented in JSON as follows:

{
  "input_token_state": {
    "token_type": "INPUT_TOKEN_TYPE"
    …​INPUT_TOKEN_TYPE_PROPERTIES…​
  },
  "output_token_state": {
    "token_type": "OUTPUT_TOKEN_TYPE"
    …​OUTPUT_TOKEN_TYPE_PROPERTIES…​
  }
}

REST STS supports the following token types and properties:

Input token types

  • USERNAME

    Requires the username and password properties.

  • OPENAM

    Requires the session_id property, with an SSO token as its value.

  • X509

    No properties are required because input X.509 tokens are presented in HTTP headers or through TLS. For more information about X.509 tokens, refer to the Authentication Target Mappings and Client Certificate Header Key properties in REST STS configuration properties.

  • OPENIDCONNECT

    Requires the oidc_id_token property, with the OpenID Connect token as its value.

Output token types

  • SAML2

    Requires the subject_confirmation property, the value of which determines the <saml:ConfirmationMethod> element for the generated SAML v2.0 assertion. Valid values are BEARER, SENDER_VOUCHES, and HOLDER_OF_KEY.

    When generating an assertion with a holder-of-key subject confirmation method, the proof_token_state property is required. The value for this property is an object that contains the base64EncodedCertificate property.

  • OPENIDCONNECT

    Requires the nonce and allow_access properties.

The following are examples of JSON payloads that define REST STS token transformations:

  1. Transform a username token to a SAML v2.0 token with the bearer subject confirmation method:

    {
  "input_token_state": {
    "token_type": "USERNAME",
    "username": "demo",
    "password": "Ch4ng31t"
  },
  "output_token_state": {
    "token_type": "SAML2",
    "subject_confirmation": "BEARER"
  }
}

  2. Transform an X.509 token to a SAML v2.0 token with the sender vouches subject confirmation method:

    {
  "input_token_state": {
    "token_type": "X509"
  },
  "output_token_state": {
    "token_type": "SAML2",
    "subject_confirmation": "SENDER_VOUCHES"
  }
}

  3. Transform an OpenID Connect token to a SAML v2.0 token with the holder-of-key subject confirmation method:

    {
  "input_token_state": {
    "token_type": "OPENIDCONNECT",
    "oidc_id_token": "eyAiYWxQ.euTNnNDExNTkyMjEyIH0.kuNlKwyvZJqaC8EYpDyPJMiEcII"
  },
  "output_token_state": {
    "token_type": "SAML2",
    "subject_confirmation": "HOLDER_OF_KEY",
    "proof_token_state": {
      "base64EncodedCertificate": "MIMbFAAOBjQAwgYkCgYEArSQ…​c/U75GB2AtKhbGS5pimrW0Y0Q=="
     }
  }
}

  4. Transform an AM SSO token to an OpenID Connect token:

    {
  "input_token_state": {
    "token_type": "OPENAM",
    "session_id": "AQIC5wM2…​TMQAA*"
  },
  "output_token_state": {
    "token_type": "OPENIDCONNECT",
    "nonce": "471564333",
    "allow_access": true
  }
}

For more examples of JSON payloads that you can send to REST STS instances, refer to the comments in the sample code in Java example.

Command-line example

You can use the curl command to check that a published REST STS instance is working as expected.

For example, if you publish a REST instance with a deployment URL element username-transformer that supports username to SAML v2.0 bearer assertion token transformation, you can send an HTTP POST request to the /rest-sts/username-transformer endpoint, setting the _action parameter to translate as follows:

$ 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
{
  "issued_token":
     "<saml:Assertion
       xmlns:saml=\"urn:oasis:names:tc:SAML:2.0:assertion\"
       Version=\"2.0\"
       ID=\"s2c51ebd0ad10aae44fb76e4b400164497c63b4ce6\"
       IssueInstant=\"2016-03-02T00:14:47Z\">\n
       <saml:Issuer>saml2-issuer</saml:Issuer>
       <saml:Subject>\n
        <saml:NameID
         Format=\"urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress\">demo
        </saml:NameID>
        <saml:SubjectConfirmation
         Method=\"urn:oasis:names:tc:SAML:2.0:cm:bearer\">\n
         <saml:SubjectConfirmationData
          NotOnOrAfter=\"2016-03-02T00:24:47Z\" >
         </saml:SubjectConfirmationData>
        </saml:SubjectConfirmation>\n
       </saml:Subject>
       <saml:Conditions
        NotBefore=\"2016-03-02T00:14:47Z\"
        NotOnOrAfter=\"2016-03-02T00:24:47Z\">\n
        <saml:AudienceRestriction>\n
         <saml:Audience>saml2-issuer-entity</saml:Audience>\n
        </saml:AudienceRestriction>\n</saml:Conditions>\n
        <saml:AuthnStatement
         AuthnInstant=\"2016-03-02T00:14:47Z\">
         <saml:AuthnContext>
          <saml:AuthnContextClassRef>
           urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
          </saml:AuthnContextClassRef>
         </saml:AuthnContext>
        </saml:AuthnStatement>
       </saml:Assertion>\n"
}

The iPlanetDirectoryPro header is required and should contain the SSO token of an administrative user, such as amAdmin, who has access to perform the operation.

Java example

The RestSTSConsumer.java sample code provides an example of how to consume a published REST STS instance programmatically. Tailor this example as required to provide programmatic consumption of your own REST STS instances.

For information on downloading and building AM sample source code, see How do I access and build the sample code provided for PingAM? in the Knowledge Base.

You can find the STS code examples under /path/to/openam-samples-external/sts-example-code.

You cannot compile the sample code referenced in this section because it uses classes that are not available publicly. The code provides patterns to developers familiar with the problem domain and is intended only to assist developers who want to programmatically consume REST STS instances.

Consume SOAP STS instances

You consume a SOAP STS instance by sending it SOAP messages to the instance’s endpoint, or by calling it using the AM SOAP STS client SDK.

SOAP STS instance URL

SOAP STS instances' URLs are comprised of the following parts:

  • The SOAP STS deployment context

  • The string sts

  • The realm in which the REST STS instance is configured

  • The deployment URL element, which is one of the configuration properties of an STS instance

The SOAP STS deployment context comprises the base URL of the web container to which the SOAP STS .war file is deployed, and the deployment web application name.

For example, a SOAP STS instance configured in the realm myRealm with the deployment URL element soap-username-transformer and the a deployment web application name openam-soap-sts would expose a URL similar to https://soap-sts-host.com:8443/openam-soap-sts/sts/myRealm/soap-username-transformer.

The WSDL for the service would be available at https://soap-sts-host.com:8443/openam-soap-sts/sts/myRealm/soap-username-transformer?wsdl.

Consume SOAP STS instances using SOAP messages

Because an AM SOAP STS instance is a WS-Trust 1.4-compliant security token service, users can consume the instance by sending it standard WS-Trust 1.4 SOAP STS framework messages, such as RequestSecurityToken messages, passed as the payload to WSDL ports that are implemented by the security token services.

For more information about WS-Trust 1.4 security token services, see the WS-Trust 1.4 specification.

Consume SOAP STS instances using the SOAP STS client SDK

You can consume an AM SOAP STS instance by calling it using the AM SOAP STS client SDK.

The SOAP STS client SDK is based on classes in Apache CXF, an open source service framework. Apache CXF provides the org.apache.cxf.ws.security.trust.STSClient class, which encapsulates consumption of a SOAP STS service. However, using this class requires considerable expertise.

The SOAP STS client SDK makes it easier to consume AM SOAP STS instances than using Apache CXF for the following reasons:

  • The org.forgerock.openam.sts.soap.SoapSTSConsumer class in the AM SOAP STS client SDK wraps the Apache CXF class org.apache.cxf.ws.security.trust.STSClient, providing a higher level of abstraction that makes consumption of SOAP STS instances easier to achieve.

  • The SoapSTSConsumer class' issueToken, validateToken, and cancelToken methods provide the three fundamental operations exposed by SOAP STS instances. Supporting classes facilitate the creation of state necessary to invoke these methods.

  • Classes in the SDK provide logic to allow AM session tokens to be presented in order to satisfy the security policy bindings that mandate AM sessions as supporting tokens. The STS client obtains secret password state—keystore entry passwords and aliases, username token credential information, and so forth—from a callback handler. The SoapSTSConsumerCallbackHandler class provides the means to create a callback handler initialized with state that will be encountered when consuming SOAP STS instances. The SoapSTSConsumerCallbackHandler instance can be passed to an STS client. The TokenSpecification class provides a way to create the varying token state necessary to obtain specific tokens and create any necessary supporting state.

You can use the classes in the SOAP STS client SDK as is, or you can tailor them to your needs. For more information about the SOAP STS client SDK classes, see the source code and the Javadoc.

The SOAP STS client SDK is not part of the AM client SDK. (The SOAP STS client SDK has a dependency on Apache CXF classes, which are not present in the AM API.) To use the SOAP STS client SDK, you must compile the source code for the SOAP STS client SDK and create a .jar file.

Build the SOAP STS client SDK

  1. Download the AM source code.

  2. Change to the openam-sts/openam-soap-sts directory.

  3. Run the mvn install command.

  4. Locate the openam-soap-sts-client-7.4.jar file in the openam-sts/openam-soap-sts/openam-soap-sts-client/target directory.

Query, validate, and cancel tokens

Both REST and SOAP STS instances support token persistence, which is the ability to store tokens issued for the STS instance in the Core Token Service (CTS). You enable token persistence for both REST and SOAP STS instances' configuration under Realms > Realm Name > STS > STS Instance Name > General Configuration > Persist Issued Tokens in Core Token Store. Tokens are saved in the CTS for the duration of the token lifetime, which is a configuration property for STS-issued SAML v2.0 and OpenID Connect tokens. Tokens with expired durations are periodically removed from the CTS.

With token persistence enabled for an STS instance, AM provides the ability to query, validate, and cancel tokens issued for the instance:

  • Querying tokens means listing tokens issued for an STS instance or for a user.

  • Validating a token means verifying that the token is still present in the CTS.

  • Cancelling a token means removing the token from the CTS.

Invoke the sts-tokengen endpoint

The sts-tokengen endpoint provides administrators with the ability to query and cancel tokens issued for both REST and SOAP STS instances using REST API calls.

When using the sts-tokengen endpoint, be sure to provide the token ID for an AM administrator, such as amAdmin, as the value of a header whose name is the name of the SSO token cookie, by default iPlanetDirectoryPro.

Query tokens

List tokens issued for an STS instance by using the queryFilter action in an HTTP GET call to the sts-tokengen endpoint with the /sts-id argument.

The following example lists all the tokens issued for the username-transformer STS instance. The results show that AM has issued two OpenID Connect tokens for the demo user for the username-transformer STS instance:

$ curl \
--request GET \
--header "iPlanetDirectoryPro: AQIC5..." \
https://openam.example.com:8443/openam/sts-tokengen?_queryFilter=\/sts_id+eq+\'username-transformer\'
{
    "result":[
        {
            "_id":"B663D248CE4C3B63A7422000B03B8F5E0F8E443B",
            "_rev":"",
            "token_id":"B663D248CE4C3B63A7422000B03B8F5E0F8E443B",
            "sts_id":"username-transformer",
            "principal_name":"demo",
            "token_type":"OPENIDCONNECT",
            "expiration_time":1459376096
        },
        {
            "_id":"7CB70009970D1AAFF177AC2A08D58405EDC35DF5",
            "_rev":"",
            "token_id":"7CB70009970D1AAFF177AC2A08D58405EDC35DF5",
            "sts_id":"username-transformer",
            "principal_name":"demo",
            "token_type":"OPENIDCONNECT",
            "expiration_time":1459376098
        }
    ],
    "resultCount":2,
    "pagedResultsCookie":null,
    "totalPagedResultsPolicy":"NONE",
    "totalPagedResults":-1,
    "remainingPagedResults":-1
}

List tokens issued for a particular user with the queryFilter action in an HTTP GET call to the sts-tokengen endpoint with the /token-principal argument.

The following example lists all the tokens issued for the demo user. The results show that AM has issued two OpenID Connect tokens:

$ curl \
--request GET \
--header "iPlanetDirectoryPro: AQIC5..." \
https://openam.example.com:8443/openam/sts-tokengen?_queryFilter=\/token_principal+eq+\'demo\'
{
    "result":[
        {
            "_id":"B663D248CE4C3B63A7422000B03B8F5E0F8E443B",
            "_rev":"",
            "token_id":"B663D248CE4C3B63A7422000B03B8F5E0F8E443B",
            "sts_id":"username-transformer",
            "principal_name":"demo",
            "token_type":"OPENIDCONNECT",
            "expiration_time":1459376096
        },
        {
            "_id":"7CB70009970D1AAFF177AC2A08D58405EDC35DF5",
            "_rev":"",
            "token_id":"7CB70009970D1AAFF177AC2A08D58405EDC35DF5",
            "sts_id":"username-transformer",
            "principal_name":"demo",
            "token_type":"OPENIDCONNECT",
            "expiration_time":1459376098
        }
    ],
    "resultCount":2,
    "pagedResultsCookie":null,
    "totalPagedResultsPolicy":"NONE",
    "totalPagedResults":-1,
    "remainingPagedResults":-1
}

Cancel tokens

Cancel tokens by making an HTTP DELETE call to the sts-tokengen/token-id endpoint:

$ curl \
--request DELETE \
--header "iPlanetDirectoryPro: AQIC5..." \
https://openam.example.com:8443/openam/sts-tokengen/B663D248CE4C3B63A7422000B03B8F5E0F8E443B
{
    "_id":"B663D248CE4C3B63A7422000B03B8F5E0F8E443B",
    "_rev":"B663D248CE4C3B63A7422000B03B8F5E0F8E443B",
    "result":"token with id B663D248CE4C3B63A7422000B03B8F5E0F8E443B successfully removed."
}

Validate and cancel tokens by invoking a REST STS instance

REST STS users can validate and cancel tokens by making an HTTP POST call to a REST STS instance’s endpoint.

To validate a token, use the validate action. The following example validates an OpenID Connect token previously issued by the username-transformer REST STS instance:

$ curl \
--request POST \
--header "iPlanetDirectoryPro: AQIC5..." \
--header "Content-Type: application/json" \
--data '{
    "validated_token_state": {
        "token_type": "OPENIDCONNECT",
        "oidc_id_token": "eyAidHlwIjogIkpXVCIsIC..."
    }
}' \
https://openam.example.com:8443/openam/rest-sts/username-transformer?_action=validate
{
    "token_valid":true
}

To cancel a token, use the cancel action. The following example cancels an OpenID Connect token previously issued by the username-transformer REST STS instance:

$ curl \
--request POST \
--header "iPlanetDirectoryPro: AQIC5..." \
--header "Content-Type: application/json" \
--data '{
    "cancelled_token_state": {
        "token_type": "OPENIDCONNECT",
        "oidc_id_token": "eyAidHlwIjogIkpXVCIsIC..."
    }
}' \
 https://openam.example.com:8443/openam/rest-sts/username-transformer?_action=cancel
{
    "result":"OPENIDCONNECT token cancelled successfully."
}

Validate and cancel tokens by invoking a SOAP STS instance

The source code for the validateToken and cancelToken methods in the org.forgerock.openam.sts.soap.SoapSTSConsumer class provides information needed to construct WS-Trust 1.4-compliant calls for validating and cancelling tokens.

Locate the org.forgerock.openam.sts.soap.SoapSTSConsumer class under openam-sts/openam-soap-sts/openam-soap-sts-client in the AM source code.

Custom token types

AM supports token transformations to and from a variety of token types, including username, SAML v2.0, OpenID Connect, and X.509. In addition to these supported token types, REST STS instances can use custom token types as the input or output token, or both, in a token transformation. When you configure a REST STS instance to support a token transformation that takes a custom token type, you can also configure a custom validator and provider class for the custom token type. AM uses custom validator classes to validate custom tokens and custom provider classes to produce custom tokens.

For information on downloading and building AM sample source code, see How do I access and build the sample code provided for PingAM? in the Knowledge Base.

You can find the STS code examples under /path/to/openam-samples-external/sts-example-code.

Specify custom token validator and provider classes in the AM admin UI by configuring the Custom Token Validators and Custom Token Providers properties under Realms > Realm Name > STS > REST STS Instance Name.

A custom validator class can be used in transformations that produce standard STS output tokens, such as SAML v2.0 tokens or OpenID Connect tokens, and in transformations that produce custom output token types.

A custom provider class can be used in token transformations that take standard STS input tokens, such as username tokens or AM SSO tokens, and in transformations that take custom input token types.

Before a REST STS instance can use a custom token type validator or provider class, you must bundle the class into the AM .war file and restart AM.

AM invokes a single instance of a validator or provider class to run all concurrently dispatched token transformations that use the custom token type. Because there is only a single instance of the class, you must code custom validator and provider classes to be thread-safe.

Develop custom token type validator classes

To create a custom token type validator class, implement the org.forgerock.openam.sts.rest.token.validator.RestTokenTransformValidator class.

Custom token type validator classes implement the validateToken method. This method takes a RestTokenValidatorParameters object as input. Note that the generic type of RestTokenValidatorParameters is org.forgerock.json.fluent.JsonValue. As a result of using this type, custom validator classes can access the JSON representation of the input token passed to the REST STS instance in the input_token_state JSON key.

The validateToken method returns an org.forgerock.openam.sts.rest.token.validator.RestTokenTransformValidatorResult object. At a minimum, this object contains the AM SSO token corresponding to the validated principal. It can also contain additional information specified as a JSON value, allowing a custom validator to pass extra state to a custom provider in a token transformation.

Develop custom token type provider classes

To create a custom token type provider class, implement the org.forgerock.openam.sts.rest.token.provider.RestTokenProvider class.

Custom token type provider classes implement the createToken method. This method takes an org.forgerock.openam.sts.rest.token.provider.CustomRestTokenProviderParameters object as input. This object gives the custom provider access to the following information:

  • The principal returned by the RestTokenTransformValidator

  • The AM SSO token corresponding to the validated principal

  • Any additional state returned in the RestTokenValidatorResult object

  • The type of input token validated by the RestTokenTransformValidator in the token transformation

  • The JsonValue corresponding to this validated token, as specified by the input_token_state object in the transformation request

  • The JsonValue corresponding to the token_output_state object specified in the token transformation request (which can provide additional information pertinent to the creation of the output token)

The createToken method returns a string representation of the custom token in a format that can be transmitted across HTTP in JSON. It should be base64-encoded if binary.

Use custom token type validators and providers

This section provides an example of how to use custom token type validators and providers.

The example assumes that you already configured a token transformation by completing the following tasks:

  • Implementing the RestTokenTransformValidator interface to create a custom token type validator

  • Implementing the RestTokenProvider interface to create a custom token type provider

  • Bundling the two classes into the AM .war file

  • Restarting AM

  • Publishing a REST STS instance with a custom token type named CUSTOM, specifying the custom validator and provider classes in the instance’s configuration

To transform a CUSTOM token to an OpenID Connect token, you might specify a JSON payload similar to the following:

{
    "input_token_state":
        {
            "token_type": "CUSTOM",
            "extra_stuff": "very_useful_state"
        },
    "output_token_state":
        {
            "token_type": "OPENIDCONNECT",
            "nonce": "1234",
            "allow_access": true
        }
}

With the preceding JSON payload, AM passes a JsonValue instance to the validateToken method of the custom token type validator class:

{
    "token_type": "CUSTOM",
    "extra_stuff": "very_useful_state"
}

To transform a username token to a CUSTOM token, you might specify a JSON payload similar to the following:

{
    "input_token_state":
        {
            "token_type": "USERNAME",
            "username": "unt_user17458687",
            "password": "password"
        },
    "output_token_state":
        {
            "token_type": "CUSTOM",
            "extra_stuff_for_custom": "some_useful_information"
        }
}

With the preceding JSON payload, AM passes the following information to the createToken method of the custom token type provider:

  • The principal returned by the USERNAME token validator: unt_user17458687.

  • The AM SSO token corresponding to this authenticated principal.

  • Additional state returned by the token validator, if any. Because the USERNAME token validator does not return any additional state, the additional state for this example would be null.

  • The input token type: CUSTOM

  • A JsonValue representation of the following:

    {
    "token_type": "USERNAME",
    "username": "unt_user17458687",
    "password": "password"
}

  • A JsonValue representation of the following:

    {
    "token_type": "CUSTOM",
    "extra_stuff_for_custom": "some_useful_information"
}

To transform a CUSTOM token to a CUSTOM token, you might specify a JSON payload similar to the following:

{
    "input_token_state":
        {
            "token_type": "CUSTOM",
            "extra_stuff": "very_useful_state"
        },
    "output_token_state":
        {
            "token_type": "CUSTOM",
            "extra_stuff_for_custom": "some_useful_information"
        }
}

The input to the custom validator and provider would be similar to the preceding examples, with the possible addition of any additional state that the custom validator returned from the validateToken method.

Reference

The reference pages cover configuration settings for the Security Token Service.

The Publish service

To publish an STS instance, perform an HTTP POST on the /sts-publish/rest endpoint, specifying the _action=create parameter in the URL.

For example, you could publish a REST STS instance named username-transformer in the Top Level Realm as follows:

$ curl \
--request POST \
--header "iPlanetDirectoryPro: AQIC5…​" \
--header "Content-Type: application/json" \
--data '{
    "invocation_context": "invocation_context_client_sdk",
    "instance_state":
    {
        "saml2-config":
        {
            "issuer-name":"saml2-issuer",
            …​
        },
        "deployment-config":
        {
            "deployment-url-element":"username-transformer",
            "deployment-realm":"/",
            …​
        },
        "persist-issued-tokens-in-cts":"false",
        "supported-token-transforms":[{
            "inputTokenType":"USERNAME",
            "outputTokenType":"OPENIDCONNECT",
            "invalidateInterimOpenAMSession":false
        }],
        "oidc-id-token-config":{
            "oidc-issuer":"test",
            …​
        }
    }
}' \
https://openam.example.com:8443/openam/sts-publish/rest?_action=create
{
  "_id":"username-transformer",
  "_rev":"21939129",
  "result":"success",
  "url_element":"username-transformer"}
}

The instance_state object in the JSON payload represents the STS instance’s configuration.

For a complete example of an instance_state object, see the sample code for the RestSTSInstancePublisher class in Publish REST STS instances.

Accessing the sts-publish endpoint requires administrative privileges. Authenticate as an AM administrative user, such as amAdmin, before attempting to publish an STS instance.

In addition to publishing instances, the sts-publish endpoint can also return the configuration of an STS instance when you perform an HTTP GET on endpoint for the instance, such as /sts-publish/rest/realm/deployment-URL-element.

In the endpoint, deployment-URL-element is the value of the STS instance’s deployment URL element—one of the instance’s configuration properties. realm is the realm in which the instance has been configured.

For example, you could obtain the configuration of a REST STS instance configured in the Top Level Realm with the deployment URL element username-transformer as follows:

$ curl \
--request GET \
--header "iPlanetDirectoryPro: AQIC5…​" \
https://openam.example.com:8443/openam/sts-publish/rest/username-transformer
{
   "_id":"username-transformer",
   "_rev":"-659999943",
   "username-transformer":{
      "saml2-config":{
         "issuer-name":"saml2-issuer",
         …​
      },
      "deployment-config":{
         "deployment-url-element":"username-transformer",
         …​
      },
      "persist-issued-tokens-in-cts":"false",
      "supported-token-transforms":[
         {
            "inputTokenType":"USERNAME",
            "outputTokenType":"OPENIDCONNECT",
            "invalidateInterimOpenAMSession":false
         }
      ],
      "oidc-id-token-config":{
         "oidc-issuer":"test",
         …​
      }
   }
}

You can delete STS instances by performing an HTTP DELETE on the sts-publish endpoint:

  • For REST STS instances, perform an HTTP DELETE on /sts-publish/rest/realm/deployment-URL-element.

  • For SOAP STS instances, perform an HTTP DELETE on /sts-publish/soap/realm/deployment-URL-element.

    SOAP STS instances are deprecated and cannot be deployed in ths version of AM. If you delete your instances, you will not be able to redeploy them.

Publish REST STS instances

The sample code referenced in this section provides an example of how to programmatically publish REST STS instance. The code is not intended to be a working example. Rather, it is a starting point—code that you can modify to satisfy your organization’s specific requirements.

For information on downloading and building AM sample source code, see How do I access and build the sample code provided for PingAM? in the Knowledge Base.

You can find the STS code examples under /path/to/openam-samples-external/sts-example-code.

After publishing a REST STS instance programmatically, you can view the instance’s configuration in the AM admin UI. The instance is ready for consumption.

Sample code is available for the following classes:

RestSTSInstancePublisher

The RestSTSInstancePublisher class exposes an API to publish, delete, and update REST STS instances by calling methods that perform an HTTP POST operation on the soap-sts/publish endpoint.

RestSTSInstanceConfigFactory

The RestSTSInstancePublisher class calls the RestSTSInstanceConfigFactory class to create a RestSTSInstanceConfig instance. RestSTSInstanceConfig objects encapsulate all the configuration information of a REST STS instance, and emit JSON values that you can post to the sts-publish/rest endpoint to publish a REST STS instance.

STSPublishContext

The sample STSPublishContext class specifies the configuration necessary to publish REST and SOAP STS instances. The class provides a programmatic method for setting configuration properties—the same configuration properties available through the AM admin UI under Realms > Realm Name > STS.

CustomTokenOperationContext

The sample CustomTokenOperationContext class specifies custom validators, token types, and transformations that a REST STS instance can support.

The sample code referenced in this section is not compilable, because it uses classes that are not available publicly. The code provides patterns to developers familiar with the problem domain and is intended only to assist developers who want to programmatically publish REST STS instances.

The sample code imports a number of classes, introducing dependencies. Classes imported from the AM API can remain in your code, but other imported classes must be removed and replaced with code that provides similar functionality in your environment. For example, the RestSTSInstanceConfigFactory class uses a constant named CommonConstants.DEFAULT_CERT_MODULE_NAME from the imported com.forgerock.openam.functionaltest.sts.frmwk.common.CommonConstants utility class. This utility class is not publicly available. Therefore, you need to replace this constant with another construct.

The critical part of the sample code is the idioms that programmatically set all the state necessary to publish a REST STS instance.

REST STS configuration properties

Deployment Url Element

A string that identifies this REST STS instance.

The Deployment Url Element is a component of the REST STS instance’s endpoint. For example, if you set myRESTSTSInstance as the Deployment Url Element, the REST STS endpoint would be rest-sts/myRealm/myRESTSTSInstance.

General configuration properties

The following are general configuration properties for REST STS instances:

Persist Issued Tokens in Core Token Store

Specifies 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

Specifies one or more token transformations supported by this REST 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

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

For details, refer to Custom token types.

Custom Token Providers

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

For details, refer to Custom token types.

Custom Token Transforms

Specifies one or more 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.

Specify the custom transform using 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. Specify 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 v2.0 assertion and then invalidates the created AM session.

STS Instance is running as remote instance

Specifies 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 REST 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 REST STS instances:

Authentication Target Mappings

Specifies one or more mappings that define how the REST 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 or module. If the third argument is an authentication chain, specify service. If the third argument is an authentication module, specify module.

  3. (Required) The name of an AM authentication chain or module to which the input token is authenticated.

  4. (Optional) The name of the header in which you place the token when authenticating to AM. Specify 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.

    Be sure to specify the header names configured in the Certificate or OpenID Connect id_token bearer authentication module 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|myLDAPChain configures STS to authenticate input USERNAME tokens to the myLDAPChain authentication chain.

  • X509|module|CertModule|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 the CertModule authentication module.

Client Certificate Header Key

Specifies the name of a header that a TLS offloader should use to use to transmit client certificates.

Token transformations that take an X.509 certificate as the input token require the certificate to be presented using two-way TLS, so that the TLS handshake can validate client certificate ownership. A common way of obtaining the client certificate with two-way TLS is to use the javax.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

Specifies one or more 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.

SOAP STS configuration properties

Deployment Url Element

Specifies a string that identifies this SOAP STS instance.

The Deployment Url Element is a component of the SOAP STS instance’s endpoint. For example, if you specified mySOAPSTSInstance as the Deployment Url Element, the SOAP STS endpoint would be /SOAP STS .war File Name/myRealm/mySOAPSTSInstance.

General configuration properties

The following are general configuration properties for SOAP STS instances:

Persist Issued Tokens in Core Token Store

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

Issued Tokens

Specifies the types of tokens that this SOAP STS instance issues as output tokens for token transformations.

Security Policy Validated Token

Specifies the SupportingToken type in the WS-SecurityPolicy bindings in the SOAP STS deployment’s WSDL, and whether the AM session created during token transformation should be invalidated after the token is issued.

Deployment configuration properties

The following are deployment configuration properties for REST STS instances:

Authentication Target Mappings

Specifies one or more mappings that define how the REST 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 or module. If the third argument is an authentication chain, specify service. If the third argument is an authentication module, specify module.

  3. (Required) The name of an AM authentication chain or module to which the input token is authenticated.

  4. (Optional) The name of the header to place the token in when authenticating to AM. Specify 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.

    Be sure to specify the header names configured in the Certificate or OpenID Connect id_token bearer authentication module 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|myLDAPChain configures STS to authenticate input USERNAME tokens to the myLDAPChain authentication chain.

  • X509|module|CertModule|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 the CertModule authentication module.

Client Certificate Header Key

Specifies the name of a header that a TLS offloader should use to use to transmit client certificates.

Token transformations that take an X.509 certificate as the input token require the certificate to be presented using two-way TLS, so that the TLS handshake can validate client certificate ownership. A common way of obtaining the client certificate with two-way TLS is to use the javax.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

Specifies one or more 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.

SOAP keystore configuration properties

The following are SOAP keystore configuration properties for SOAP STS instances:

Soap Keystore Location

Specifies the path to a JKS keystore containing keys for signing and encryption when using the symmetric and asymmetric bindings with SOAP messaging. Specify an absolute path or a location in the AM classpath.

Note that the WSDL File Referencing Security Policy Binding Selection property determines the binding for a SOAP STS instance.

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.

Signature Key Alias

Specifies the key alias in the keystore used to sign messages from this SOAP STS instance. You must configure this property when using asymmetric binding.

Signature Key Password

Specifies the password for the signature key.

Decryption Key Alias

Specifies the key alias in the keystore used by this SOAP STS instance to decrypt client messages for the asymmetric binding, and to decrypt the client-generated symmetric key for the symmetric binding.

Decryption Key Password

Specifies the password for the decryption key.

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.