PingAM 7.5.0

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