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.
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:
Feature | Description | REST STS | SOAP STS |
---|---|---|---|
REST endpoints |
REST endpoints exposed upon instance creation. |
✔ |
✖ |
SOAP endpoints |
AM |
✖ |
✔ |
Token transformations |
AM STS issues OpenID Connect V1.0 (OIDC) and SAML V2.0 tokens (bearer, holder-of-key, sender vouches). Username token → OIDC Username 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 |
✔ |
✔ |
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. |
✖ |
✔ |
|
AM SOAP STS supports delegated and proxied token relationships,
as defined by the |
✖ |
✔ |
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 |
✖ |
✔ |
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 theAudienceRestriction
element of theConditions
statement of the issued assertion. -
SP assertion consumer service URL. The SP assertion consumer service URL is used as the
Recipient
attribute of thesubjectConfirmation
element in theSubject
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
andAttributeStatement
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 |
|
Username Token and OpenID Connect Token |
|
X.509 Token |
|
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.
REST STS process flow
-
A requestor makes an access request to a web resource.
-
The web service redirects the requestor to the STS.
-
The requestor sends an HTTP(S) POST request to the STS endpoint. The request includes credentials, token input type, and desired token output type.
The following example generates a bearer token:
$ curl \ --request POST \ --header "Content-Type: application/json" \ --data '{ "input_token_state": { "token_type": "USERNAME", "username": "demo", "password": "Ch4ng31t" }, "output_token_state": { "token_type": "SAML2", "subject_confirmation": "BEARER" } }' \ https://openam.example.com:8443/openam/rest-sts/username-transformer?_action=translate
The following example generates an OIDC token:
$ curl \ --request POST \ --header "Content-Type: application/json" \ --data '{ "input_token_state": { "token_type": "USERNAME", "username": "demo", "password": "Ch4ng31t" }, "output_token_state": { "token_type": "OPENIDCONNECT", "nonce":"12345678", "allow_access":true } }' \ https://openam.example.com:8443/openam/rest-sts/username-transformer?_action=translate
-
The STS does the following:
-
Validates the signature.
-
Decodes the payload and verifies that the requestor issued the transaction.
-
Validates the requestor’s credentials.
-
Creates an interim AM session and, optionally, creates a CTS token for the session.
-
Issues a token to the requestor.
-
Invalidates the interim AM session, if configured.
-
-
The requestor is redirected to the web service and presents its token to the web service.
-
The web service does the following:
-
Validates the signature and decodes the payload.
-
Verifies that the requestor issued the request.
-
Extracts and validates the token and processes the request.
-
-
If a CTS token was created for the session, the web service can call the REST STS to invalidate the token and the corresponding AM session.
Validate input tokens
STS token transformations validate input tokens before generating output tokens. The STS uses AM authentication modules and chains to perform token validation. When deploying STS, you must configure AM authentication so that it can validate input tokens.
This section describes authentication configuration requirements for username, X.509, and OpenID Connect tokens. No special authentication configuration is required when using AM session tokens as the input tokens in token transformations.
Because REST STS instances are not part of a secure framework like WS-Trust 1.4, this section also discusses security considerations when sending tokens across a network to a REST STS instance.
In addition to configuring AM authentication to support input token validation, you must identify the authentication tree or module that will validate each input token type. To do so, configure the Authentication Target Mappings property in the STS instance configuration. For details, refer to Reference.
Validate username tokens
Username tokens passed to a REST STS instance contain the username/password combination in cleartext. Tokens can be validated using any module type that supports username/password authentication, including Data Store, LDAP, and so on.
With usernames and passwords in cleartext, be sure to configure your deployment with an appropriate level of security. Deploy REST STS instances that support input username token transformations on TLS.
Validate X.509 certificate tokens
REST STS instances can obtain X.509 certificates used as input tokens in two ways:
-
From the header key defined in the REST STS instance’s Client Certificate Header Key property. In this case, STS also confirms the request came from a host specified in the Trusted Remote Hosts property.
-
From the
javax.servlet.request.X509Certificate
attribute in the ServletRequest. The REST STS instance obtains the X.509 certificate from the ServletRequest if no header key is set in the Client Certificate Header Key property.
The AM Certificate module authenticates the X.509 certificate input token. The module optionally performs Certificate Revocation List (CRL) or Online Certificate Status Protocol (OCSP) checking, and can check that the specified certificate is in an LDAP datastore.
If certificates are passed to the REST STS using HTTP headers, you must configure the Trusted Remote Hosts and Http Header Name for Client Certificate properties in the Certificate module to match the configuration of your REST STS instance.
Validate OpenID Connect tokens
To validate OpenID Connect input tokens, a REST STS instance must reference an OpenID Connect id_token bearer authentication module in the Authentication Target Mappings property.
Configure the authentication module as follows:
- Name of header referencing the ID Token
-
Specify a header. The REST STS instance’s Target Authentication Mapping property must reference the same header.
- Name of OpenID Connect ID Token Issuer
-
Specify the issuer name. Set the token issuer’s discovery URL, JWK URL, or client secret in the OpenID Connect validation configuration value property.
- List of accepted authorized parties
-
If incoming OpenID Connect tokens contain
azp
claims, specify valid claims in this property. - Audience
-
If incoming OpenID Connect tokens contains
aud
claims, specify the valid claims in this property. - Attribute mappings
-
Map JWK claims to attributes in the AM user store.
For more information about OpenID Connect id_token bearer authentication module properties, refer to OpenID Connect id_token bearer module.
SOAP STS instances do not accept OpenID Connect tokens as input tokens in token transformations. |
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 thePrivateKeyEntry
.
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 process flow is as follows:
-
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.
-
The requestor creates and configures an
STSClient
object whose main task is to contact the STS. -
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. -
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’susernameToken
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.
-
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 theSTSClient
. -
The
STSClient
extracts the security token and sends it in the request’s message header. TheSTSClient
sends the message to the web service. -
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.
-
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.
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 theActAs
orOnBehalfOf
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 authenticateUsername
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
andpassword
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 areBEARER
,SENDER_VOUCHES
, andHOLDER_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 thebase64EncodedCertificate
property. -
OPENIDCONNECT
Requires the
nonce
andallow_access
properties.
-
The following are examples of JSON payloads that define REST STS token transformations:
-
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" } }
-
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" } }
-
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==" } } }
-
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 |
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 classorg.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
, andcancelToken
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. TheSoapSTSConsumerCallbackHandler
instance can be passed to an STS client. TheTokenSpecification
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.
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 |
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 theinput_token_state
object in the transformation request -
The
JsonValue
corresponding to thetoken_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.
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 thesoap-sts/publish
endpoint. - RestSTSInstanceConfigFactory
-
The
RestSTSInstancePublisher
class calls theRestSTSInstanceConfigFactory
class to create aRestSTSInstanceConfig
instance.RestSTSInstanceConfig
objects encapsulate all the configuration information of a REST STS instance, and emit JSON values that you can post to thests-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 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 berest-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:
-
The input token type
-
The output token type
-
Whether to invalidate the AM session created during token transformation. Specify
TRUE
to invalidate the session orFALSE
to let the session remain valid.
For example, a value of
CUSTOM|SAML2|TRUE
configures a token transformation that transforms aCUSTOM
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 tofalse
(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 thesessions
orsts-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:
-
(Required) The input token type:
USERNAME
,OPENAM
,X509
,OPENIDCONNECT
, or a custom token type. -
(Required) The value
service
ormodule
. If the third argument is an authentication chain, specifyservice
. If the third argument is an authentication module, specifymodule
. -
(Required) The name of an AM authentication chain or module to which the input token is authenticated.
-
(Optional) The name of the header in which you place the token when authenticating to AM. Specify this parameter for input
X509
andOPENIDCONNECT
tokens as follows:-
For
X509
input tokens, the format isx509_token_auth_target_header_key=Header Name
. -
For
OPENIDCONNECT
input tokens, the format isoidc_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 inputUSERNAME
tokens to themyLDAPChain
authentication chain. -
X509|module|CertModule|x509_token_auth_target_header_key=ClientCert
configures STS to obtain an X.509 certificate from theClientCert
header, use it as the input token, and authenticate it using theCertModule
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:
-
(Required) The input token type:
USERNAME
,OPENAM
,X509
,OPENIDCONNECT
, or a custom token type. -
(Required) The value
service
ormodule
. If the third argument is an authentication chain, specifyservice
. If the third argument is an authentication module, specifymodule
. -
(Required) The name of an AM authentication chain or module to which the input token is authenticated.
-
(Optional) The name of the header to place the token in when authenticating to AM. Specify this parameter for input
X509
andOPENIDCONNECT
tokens as follows:-
For
X509
input tokens, the format isx509_token_auth_target_header_key=Header Name
. -
For
OPENIDCONNECT
input tokens, the format isoidc_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 inputUSERNAME
tokens to themyLDAPChain
authentication chain. -
X509|module|CertModule|x509_token_auth_target_header_key=ClientCert
configures STS to obtain an X.509 certificate from theClientCert
header, use it as the input token, and authenticate it using theCertModule
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:
-
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.
-
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 theConditions
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 theSubjectConfirmation
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 theConditions
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 theSubject
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 theAuthnStatement
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 theAttributeStatement
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 theAuthzDecisionStatement
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 theAuthnContext
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’sName
property. -
The user profile or session property value populates the
Attribute
element’sAttributeValue
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:
-
AM generates a symmetric key.
-
AM encrypts the symmetric key with the recipient’s public key.
-
AM includes the encrypted key in the part of the assertion that is not symmetric key-encrypted.
-
The service provider—owner of the corresponding private key—uses the private key to decrypt the symmetric key included in the assertion.
-
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:
-
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.
-
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 valueemail=mail
. A generated OpenID Connect ID token for user Sam Carter would contain the claim"email":"scarter@example.com"
if themail
attribute in Sam Carter’s user profile had the valuescarter@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. Anacr
claim indicates which authentication context class was satisfied by the authentication of the principal asserted in the OpenID Connect ID token. Theacr
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. Anamr
claim indicates which authentication methods were used to authenticate the principal asserted in the OpenID Connect ID token. Theamr
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.