Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 9. The Security Token Service

Abstract

The Security Token Service (STS) is the core component of the WS-Trust single-sign on framework. This chapter explains the modular architecture of the STS and takes you step-by-step through the demonstration included in the Apache CXF distribution.

9.1. STS Architecture
Copy link

9.1.1. Overview of the STS
Copy link

Architecture
Copy link

The Apache CXF STS has a modular architecture, with many components that are configurable or replaceable. Many of the optional features are enabled by implementing and configuring plug-ins that are injected into the STS runtime. Figure 9.1, “STS Architecture” gives a broad overview of the core components and optional components of the STS.

Figure 9.1. STS Architecture

STS WSDL
Copy link

The STS is accessed through a standard WSDL contract. As with any WSDL contract, you can think of the STS WSDL as consisting of two main parts, as follows:
  • Logical part of the WSDL—consists of WSDL type definitions and the STS WSDL port type. In other words, this part of the WSDL provides an abstract definition of the STS interface.
    The logical part is defined exactly in the WSDL appendix of the WS-Trust specification.
  • Physical part of the WSDL—consists of the WSDL binding and WSDL service definitions. In other words, this part of the WSDL specifies the details of the message encoding and the transport protocol used to access the STS.
    In contrast to the logical part, the physical part of the WSDL can be customized, enabling you to choose what kind of protocol to use when accessing the STS. The most common choice is SOAP/HTTP, but in principle you could use other SOAP-compatible transports supported by Apache CXF—for example, SOAP/JMS.

STS operations
Copy link

The STS WSDL defines the following standard operations (from the WS-Trust specification):
  • Issue binding—the specification defines this binding as follows: Based on the credential provided/proven in the request, a new token is issued, possibly with new proof information.
  • Validate binding—the specification defines this binding as follows: The validity of the specified security token is evaluated and a result is returned. The result may be a status, a new token, or both.
  • Renew binding—the specification defines this binding as follows: A previously issued token with expiration is presented (and possibly proven) and the same token is returned with new expiration semantics.
  • Cancel binding—the specification defines this binding as follows: When a previously issued token is no longer needed, the Cancel binding can be used to cancel the token, terminating its use.
  • Key Exchange Token binding (not supported)—in the context of the WS-Trust negotiation and challenge extensions, this binding is used for requesting a new Key Exchange Token.
  • RequestCollection binding (not supported)—similar to the Issue binding, except that it allows you to request multiple tokens in a single operation (the request message is a wst:RequestSecurityTokenCollection element, which consists of a list of wst:RequestSecurityToken elements).

STS policies
Copy link

When a secure application connects to the STS, this connection is also subject to security policies. For example, the STS might require STS clients to authenticate themselves using a WS-Security UsernameToken or by presenting an X.509 certificate, and so on.
For more details, see the section called “Choosing policies”.

Abstract STS provider framework
Copy link

The Apache CXF implementation of the STS is designed as a pluggable framework. The core class in this framework is the SecurityTokenServiceProvider class from the org.apache.cxf.ws.security.sts.provider package, which provides the Java implementation of the STS WSDL interface.
For each of the standard STS operations, the STS provider defines the following abstract interfaces:
  • IssueOperation
  • IssueSingleOperation
  • ValidateOperation
  • RenewOperation
  • CancelOperation
By implementing each of these interfaces and injecting the corresponding instances into the SecurityTokenServiceProvider instance, you can customize the implementation of each STS operation.
In practice, however, you would normally use the default implementations of these operations which are, as follows:

TokenIssueOperation class
Copy link

The TokenIssueOperation class from the org.apache.cxf.ws.security.sts.operation package is the default implementation of the Issue operation.
To configure a TokenIssueOperation instance, you would normally just provide it with a reference to a SAMLTokenProvider instance (which enables it to issue SAML tokens). For details, see Section 9.1.3, “Customizing the Issue Operation”.

TokenValidateOperation class
Copy link

The TokenValidateOperation class from the org.apache.cxf.ws.security.sts.operation package is the default implementation of the Validate operation.
To configure a TokenValidateOperation instance, you need to provide it with a list of token validators. For details, see Section 9.1.4, “Customizing the Validate Operation”.

TokenCancelOperation class
Copy link

The TokenCancelOperation class from the org.apache.cxf.ws.security.sts.operation package is the default implementation of the Cancel operation.
To configure a TokenCancelOperation instance, you need to provide it with a list of cancellers. At the moment, only the SCTCanceller canceller is available, which is used for cancelling Security Context Tokens in the context of secure conversations (WS-SecureConversation specification). For details, see Section 9.1.4, “Customizing the Validate Operation”.

9.1.2. Customizing the STS WSDL
Copy link

Overview
Copy link

The STS itself is a Web service and thus, like any Web service, it has a WSDL contract that defines how other applications and processes can interact with it. Although some core features of the STS WSDL are fixed by the WS-Trust specification (for example, the core data types and the WSDL port type), there are several important aspects of the STS WSDL contract that can be customized.
In particular, the following aspects of the STS WSDL can be customized:
  • Address of the STS WSDL port—the host, IP port, and context path of the STS Web service endpoint can be customized by editing the address attribute of the WSDL port.
    Note
    Moreover, it is possible to define multiple Web service ports for a single STS, where each port can specify a different address and different WS policies.
  • WS security policies—you can customize the WS security policies that apply to the STS WSDL binding. For example, you can choose between a symmetric, asymmetric, or transport binding and you can choose how clients authenticate themselves to the STS.

WSDL types and portType
Copy link

The WSDL types and WSDL port type for the STS are defined exactly by the WS-Trust specification. In outline, the WSDL port type is defined as follows: 
<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions
        targetNamespace="http://docs.oasis-open.org/ws-sx/ws-trust/200512/"
        xmlns:tns="http://docs.oasis-open.org/ws-sx/ws-trust/200512/"
        xmlns:wstrust="http://docs.oasis-open.org/ws-sx/ws-trust/200512/"
        xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
        xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
        xmlns:wsap10="http://www.w3.org/2006/05/addressing/wsdl"
        xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
        xmlns:wsp="http://www.w3.org/ns/ws-policy"
    xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata">
    >

  <wsdl:types>
    ...
  </wsdl:types>
  ...
  <!-- This portType is an example of an STS supporting full protocol -->
  <wsdl:portType name="STS">
    <wsdl:operation name="Cancel">
      <wsdl:input
        wsam:Action="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Cancel"
        message="tns:RequestSecurityTokenMsg"/>
      <wsdl:output
        wsam:Action="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/CancelFinal"
        message="tns:RequestSecurityTokenResponseMsg"/>
    </wsdl:operation>
    <wsdl:operation name="Issue"> ... </wsdl:operation>
    <wsdl:operation name="Renew"> ... </wsdl:operation>
    <wsdl:operation name="Validate"> ... </wsdl:operation>
    <wsdl:operation name="KeyExchangeToken"> ... </wsdl:operation>
    <wsdl:operation name="RequestCollection"> ... </wsdl:operation>
  </wsdl:portType>
  ...
</wsdl:definitions>
Copy to Clipboard Toggle word wrap
For each of the STS operations, the following message types are sent or received:
  • Request message types—are either:
    • RequestSecurityToken (RST) type, for the Issue, Renew, Validate, Cancel, and KeyExchangeToken operations; or
    • RequestSecurityTokenCollection type, for the RequestCollection operation.
  • Response message types—are either:
    • RequestSecurityTokenResponse (RSTR) type, for the Renew, Validate, Cancel, and KeyExchangeToken operations; or
    • RequestSecurityTokenResponseCollection type, for the Issue and RequestCollection operations.
For a full listing of the STS WSDL port type and WSDL types, see the sample WS-Trust 1.4 WSDL file in the Apache CXF samples: 
CXFInstallDir/samples/sts/wsdl/ws-trust-1.4-service.wsdl
Copy to Clipboard Toggle word wrap

Choosing a WSDL binding
Copy link

Because the STS is accessed through a standard WSDL contract, you can customize the WSDL binding just the same way as you can for any other Web service. You should use a SOAP binding, but you can in principle use a transport other than HTTP. The main choices are:
  • SOAP/HTTP (either SOAP 1.1 or SOAP 1.2)
  • SOAP/JMS
In practice, however, SOAP/HTTP is the normal use case.

SOAP/HTTP binding
Copy link

The following extract from the STS WSDL shows the physical part of the WSDL contract, consisting of a SOAP/HTTP binding (defined by the wsdl:binding element) and a HTTP port (defined by the wsdl:service element): 
<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions ... >
  ...
  <wsdl:binding name="UT_Binding" type="wstrust:STS">
      ...
      <soap:binding style="document"
          transport="http://schemas.xmlsoap.org/soap/http" />
      <wsdl:operation name="Issue"> ... </wsdl:operation>
      <wsdl:operation name="Validate"> ... </wsdl:operation>
      <wsdl:operation name="Cancel"> ... </wsdl:operation>
      <wsdl:operation name="Renew"> ... </wsdl:operation>
      <wsdl:operation name="KeyExchangeToken"> ... </wsdl:operation>
      <wsdl:operation name="RequestCollection"> ... </wsdl:operation>
  </wsdl:binding>
  
  <wsdl:service name="SecurityTokenService">
      <wsdl:port name="UT_Port" binding="tns:UT_Binding">
         <soap:address location="http://localhost:8080/SecurityTokenService/UT" />
      </wsdl:port>
  </wsdl:service>
  ...
</wsdl:definitions>
Copy to Clipboard Toggle word wrap
The soap:binding element is used to specify that this is a SOAP binding and the transport attribute identifies the transport type as HTTP. Inside the wsdl:port element, the location attribute of the soap:address element specifies the URL that is used to access the STS.
In a real deployment of the STS, you would edit the location URL to specify the host and IP port where the STS is actually running.

Choosing policies
Copy link

Access to the STS itself must be made secure. Hence, you must apply WS-Security policies to the STS endpoint to define the relevant security policies. Although the requisite policy definitions themselves are fairly complex, it really boils down to a choice between three main alternatives, as follows:
  • Transport binding—security is provided by the HTTPS transport (that is, in the SSL/TLS layer). In this case, an initiator (for example, a WS client) authenticates itself by providing either of the following credentials:
    • X.509 certificate (sent through the SSL/TLS layer, during the TLS security handshake), or
    • WSS UsernameToken (sent through the SOAP layer, in a SOAP security header)
  • Symmetric binding—security is provided at the SOAP layer. An initiator must authenticate itself by providing WSS UsernameToken credentials.
  • Asymmetric binding—security is provided at the SOAP layer. An initiator must authenticate itself by providing an X.509 certificate.

Inserting policy references
Copy link

After defining a policy for connecting to the STS, you must then apply it to the STS endpoints. The easiest way to apply a policy is to use the wsp:PolicyReference element, which references the relevant WS policy (see Policies and policy references). The following extract from the STS WSDL shows how to apply policies to the SOAP/HTTP binding: 
<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions ... >
  ...
  <wsdl:binding name="UT_Binding" type="wstrust:STS">
 <wsp:PolicyReference URI="#UT_policy" />
      <soap:binding style="document"
          transport="http://schemas.xmlsoap.org/soap/http" />
      <wsdl:operation name="Issue">
          <soap:operation
              soapAction="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Issue" />
          <wsdl:input>
 <wsp:PolicyReference URI="#Input_policy" />
              <soap:body use="literal" />
          </wsdl:input>
          <wsdl:output>
 <wsp:PolicyReference URI="#Output_policy" />
              <soap:body use="literal" />
          </wsdl:output>
      </wsdl:operation>
      <wsdl:operation name="Validate"> ... </wsdl:operation>
      <wsdl:operation name="Cancel"> ... </wsdl:operation>
      <wsdl:operation name="Renew"> ... </wsdl:operation>
      <wsdl:operation name="KeyExchangeToken"> ... </wsdl:operation>
      <wsdl:operation name="RequestCollection"> ... </wsdl:operation>
  </wsdl:binding>
  ...
</wsdl:definitions>
Copy to Clipboard Toggle word wrap
The first wsp:PolicyReference element applies the UT_Policy policy (in the sample/sts demonstration, this is a symmetric binding policy) to the SOAP binding. This implies that the policy applies to all endpoints that use this SOAP binding.
The second wsp:PolicyReference element applies the Input_policy policy to the Issue operation's request message, and the third wsp:PolicyReference element applies the Output_policy policy to the Issue operation's response message. The Input_policy policy and the Output_policy policy are used to specify which parts of the SOAP messages to protect (see Specifying Parts of Message to Encrypt and Sign).
For example, the following sample policy is used to specify that clients must connect to the STS using the symmetric key binding and the clients must also include UsernameToken credentials, to authenticate themselves to the STS: 
  <wsp:Policy wsu:Id="UT_policy">
      <wsp:ExactlyOne>
         <wsp:All>
            <wsap10:UsingAddressing/>
            <sp:SymmetricBinding
               xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
               <wsp:Policy>
                  <sp:ProtectionToken>
                     <wsp:Policy>
                        <sp:X509Token
                           sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/Never">
                           <wsp:Policy>
                              <sp:RequireDerivedKeys />
                              <sp:RequireThumbprintReference />
                              <sp:WssX509V3Token10 />
                           </wsp:Policy>
                        </sp:X509Token>
                     </wsp:Policy>
                  </sp:ProtectionToken>
                  <sp:AlgorithmSuite>
                     <wsp:Policy>
                        <sp:Basic128 />
                     </wsp:Policy>
                  </sp:AlgorithmSuite>
                  <sp:Layout>
                     <wsp:Policy>
                        <sp:Lax />
                     </wsp:Policy>
                  </sp:Layout>
                  <sp:IncludeTimestamp />
                  <sp:EncryptSignature />
                  <sp:OnlySignEntireHeadersAndBody />
               </wsp:Policy>
            </sp:SymmetricBinding>
            <sp:SignedSupportingTokens
               xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
               <wsp:Policy>
                  <sp:UsernameToken
                     sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient">
                     <wsp:Policy>
                        <sp:WssUsernameToken10 />
                     </wsp:Policy>
                  </sp:UsernameToken>
               </wsp:Policy>
            </sp:SignedSupportingTokens>
            <sp:Wss11
               xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
               <wsp:Policy>
                  <sp:MustSupportRefKeyIdentifier />
                  <sp:MustSupportRefIssuerSerial />
                  <sp:MustSupportRefThumbprint />
                  <sp:MustSupportRefEncryptedKey />
               </wsp:Policy>
            </sp:Wss11>
            <sp:Trust13
               xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
               <wsp:Policy>
                  <sp:MustSupportIssuedTokens />
                  <sp:RequireClientEntropy />
                  <sp:RequireServerEntropy />
               </wsp:Policy>
            </sp:Trust13>
         </wsp:All>
      </wsp:ExactlyOne>
   </wsp:Policy>
Copy to Clipboard Toggle word wrap

9.1.3. Customizing the Issue Operation
Copy link

TokenIssueOperation
Copy link

For the Issue operation, the TokenIssueOperation class provides the overall coordination of the token issuing process. There are some important aspects of a TokenIssueOperation instance that can be customized. In particular, because the TokenIssueOperation instance delegates token generation to token providers—where each token provider is capable of generating a particular kind of token—the token provider beans play a particularly important role in issuing tokens.
Figure 9.2, “Configuring TokenIssueOperation” shows an overview of the major components that are involved in token issuing.

Figure 9.2. Configuring TokenIssueOperation

Plug-in framework
Copy link

The implementation of TokenIssueOperation has a modular structure. You can inject various plug-ins into the TokenIssueOperation instance in order to customize the behavior of the Issue operation. The following properties can be set on the TokenIssueOperation class:
tokenProviders
Specifies a list of token providers, where each token provider is capable of generating tokens of a specific type. Whenever an STS client asks the Issue operation to issue a token of a specific type, the TokenIssueOperation class iterates over all of the token providers specified by this property, asking each of them whether they can handle the required token type (by invoking the canHandle() method on each token provider).
The available token providers are described in the section called “Token providers”.
stsProperties
References a bean that encapsulates generic configuration properties for the STS (normally an instance of StaticSTSProperties). This configuration data mainly consists of the details needed to access a signing certificate and an encrypting certificate.
services
Specifies a list of known services and their corresponding token requirements. This property must be set, if you want to support the AppliesTo policy in a token request. For details, see Section 9.4, “Enabling AppliesTo in the STS”.
encryptIssuedToken
Specifies whether or not to encrypt an issued token. Default is false.
If you enable this option, you must also associate an encryption key with the TokenIssueOperation, through the properties defined on the StaticSTSProperties instance—see the section called “Encrypting key”

Token providers
Copy link

The Apache CXF STS currently provides the following token provider implementations:

SAMLTokenProvider
Copy link

The SAMLTokenProvider token provider is used to generate SAML tokens. This is the most commonly used token provider.
A registered SAMLTokenProvider instance is triggered to issue a token, if the token type specified by the requesting STS client is one of the following:
Expand
Token Type URIs handled by the SAMLTokenProvider
http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1
urn:oasis:names:tc:SAML:1.0:assertion
http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0
urn:oasis:names:tc:SAML:2.0:assertion
The SAMLTokenProvider class comes pre-configured with sensible default behaviors, so it is normally acceptable to instantiate it without setting any of its properties. If you want to customize its behavior, however, you can set some or all of the following properties:
attributeStatementProviders
You can optionally use this property to add attribute statement providers, if you want to define your own custom attribute statements in the generated SAML token. If this property is not set, the DefaultAttributeStatementProvider class is automatically invoked, which generates the following attribute statements:
  • An attribute statement that confirms the SAML token has been authenticated.
  • An attribute statements containing a username, if an OnBehalfOf element or an ActAs element containing a UsernameToken was present in the Issue request.
  • An attribute statements containing a subject name, if an OnBehalfOf element or an ActAs element containing a SAML token was present in the Issue request.
authenticationStatementProviders
You can optionally add authentication statement providers, if you want to define your own custom authentication statements in the generated SAML token. No authentication statements are added by default.
authDecisionStatementProviders
You can optionally add authorization decision statement providers, if you want to define your own custom authorization decision statements in the generated SAML token. No authorization decision statements are added by default.
subjectProvider
You can optionally set this property to define a custom SAML subject provider.
If this property is not set, the DefaultSubjectProvider class is automatically invoked. The default implementation automatically populates the SAML subject with all of the fields needed to support the standard scenarios: Holder-of-Key with SymmetricKey; Holder-of-Key with PublicKey algorithm; and Bearer.
conditionsProvider
You can optionally set this property to define a custom conditions provider.
If this property is not set, the DefaultConditionsProvider class is automatically invoked. The default implementation applies a default lifetime of five minutes to the token and sets the audience restriction URI to the value of the received AppliesTo address (if any).
signToken
Specifies whether or not to sign the SAML token. Default is true.
realmMap
Specifies a map that associates realm names with SAMLRealm objects. Only required, if you want to enable support for realms. For details, see Section 9.5, “Enabling Realms in the STS”.

SCTProvider
Copy link

The SCTProvider token provider is used to generate security context tokens, which you only need if you are using the WS-SecureConversation protocol.
A registered SCTProvider instance is triggered to issue a token, if the token type specified by the requesting STS client is one of the following:
Expand
Token Type URIs handled by the SCTProvider
http://docs.oasis-open.org/ws-sx/ws-secureconversation/200512/sct
http://schemas.xmlsoap.org/ws/2005/02/sc/sct
You can optionally set the following properties on an SCTProvider instance:
lifetime
Specifies the lifetime of the generated security context token. Default is five minutes.
returnEntropy
Specifies whether to return entropy to the STS client. Default is true.

Sample configuration of SAMLTokenProvider
Copy link

Example 9.1, “Configuring the STS Issue Operation” shows an example of how to configure the STS Issue operation. In this example, the TokenIssueOperation class is configured to use a SAMLTokenProvider token provider.

Example 9.1. Configuring the STS Issue Operation

<beans ... >
    ...
    <bean id="utSTSProviderBean"
        class="org.apache.cxf.ws.security.sts.provider.SecurityTokenServiceProvider">
        <property name="issueOperation" ref="utIssueDelegate"/>
        ...
    </bean>    

    <bean id="utIssueDelegate"
        class="org.apache.cxf.sts.operation.TokenIssueOperation">
        <property name="tokenProviders" ref="utSamlTokenProvider"/>
        ...
        <property name="stsProperties" ref="utSTSProperties"/>
    </bean>
    ...    
    <bean id="utSamlTokenProvider"
        class="org.apache.cxf.sts.token.provider.SAMLTokenProvider">
    </bean>
    ...    
    <bean id="utSTSProperties"
         class="org.apache.cxf.sts.StaticSTSProperties">
        <property name="signaturePropertiesFile" value="stsKeystore.properties"/>
        <property name="signatureUsername" value="mystskey"/>
        <property name="callbackHandlerClass" value="demo.wssec.sts.STSCallbackHandler"/>
        <property name="issuer" value="DoubleItSTSIssuer"/>
    </bean>
    ...    
</beans>
Copy to Clipboard Toggle word wrap

9.1.4. Customizing the Validate Operation
Copy link

TokenValidateOperation
Copy link

For the Validate operation, the TokenValidateOperation class provides the overall coordination of the token validation process. The TokenValidateOperation instance delegates token validation to token validators—where each token validator is capable of validating a particular kind of token.
The TokenValidateOperation class can also support token transformation and this capability is discussed in detail in the context of realms, Section 9.5.3, “Token Transformation across Realms”.
Figure 9.3, “Configuring TokenValidateOperation” shows an overview of the major components that are involved in token validation.

Figure 9.3. Configuring TokenValidateOperation

Plug-in framework
Copy link

You can inject various plug-ins into the TokenValidateOperation instance in order to customize the behavior of the Validate operation. The following properties can be set on the TokenValidateOperation class:
tokenValidators
Specifies a list of token validators, where each token validator is capable of validating tokens of a specific type. Whenever an STS client asks the Validate operation to validate a token of a specific type, the TokenValidateOperation class iterates over all of the token validators specified by this property, asking each of them whether they can handle the required token type (by invoking the canHandle() method on each token validator).
The available token validators are described in the section called “Token validators”.
stsProperties
References a bean that encapsulates generic configuration properties for the STS (normally an instance of StaticSTSProperties). This configuration data mainly consists of the details needed to access a signing certificate and an encrypting certificate.
services
(Only relevant, if token transformation is requested) Specifies a list of known services and their corresponding token requirements. This property must be set, if you want to support the AppliesTo policy in a token request. For details, see Section 9.4, “Enabling AppliesTo in the STS”.
tokenProviders
(Only relevant, if token transformation is requested) Specifies a list of token providers, where each token provider is capable of generating tokens of a specific type.
For details of token transformation, see Section 9.5.3, “Token Transformation across Realms”.

Token validators
Copy link

The Apache CXF STS currently provides the following token validator implementations:

SAMLTokenValidator
Copy link

A registered SAMLTokenValidator instance is triggered to validate a token, if the received token is a SAML assertion and its token type is one of the following:
Expand
Token Type URIs handled by the SAMLTokenValidator
urn:oasis:names:tc:SAML:1.0:assertion
urn:oasis:names:tc:SAML:2.0:assertion
Validating a SAML token consists, essentially, of verifying the signature on the SAML token and checking that the signer is trusted (the SAML token must be signed, otherwise it cannot be validated). In outline, a typical signed SAML 2.0 token has a structure like the following: 
<saml2:Assertion xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"
                 ID="_181835fb981efecaf71d80ecd5fc3c74"
                 IssueInstant="2011-05-09T09:36:37.359Z" Version="2.0">
    <saml2:Issuer> ... </saml2:Issuer>
    <saml2:Subject> ... </saml2:Subject>
    <saml2:Conditions NotBefore=" ... " NotOnOrAfter=" ... "/>
    ...
    <Signature:Signature xmlns:Signature="http://www.w3.org/2000/09/xmldsig#"
                         xmlns="http://www.w3.org/2000/09/xmldsig#">
        <SignedInfo>
            <!-- Details of the signing algorithm used -->
        </SignedInfo>
        <SignatureValue>
            <!-- The signature value -->
        </SignatureValue>
        <KeyInfo>
            <X509Data>
                <X509SubjectName> ... </X509SubjectName>
                <X509Certificate>
                    <!-- The certificate that can decrypt the signature value -->
                </X509Certificate>
            </X509Data>
        </KeyInfo>
    </Signature:Signature>
</saml2:Assertion>
Copy to Clipboard Toggle word wrap
The SAMLTokenValidator class uses the following algorithm to validate the received SAML token:
  1. The SAML assertion is first checked, to ensure that it is well-formed.
  2. If the assertion is not signed, it is rejected.
  3. The signature is checked, using the X.509 certificate embedded in the assertion's signature. If the signature is verified, this proves that whoever signed the SAML token is in possession of the private key corresponding to the embedded X.509 certificate.
  4. The embedded X.509 certificate is checked to make sure that it is trusted. The validator looks up the trusted certificates stored in the STS properties signature trust store (as configured by the signaturePropertiesFile property or the signatureCrypto property on the StaticSTSProperties object—see Section 9.1.6, “Configuring STS Properties”) and checks that the certificate is either present in the trust store or is signed by a private key corresponding to one of the certificates in the trust store (certificate chaining).
  5. If the subjectConstraints property is set on the SAMLTokenValidator instance, the validator checks that the Subject DN string from the embedded X.509 certificate matches one of the specified regular expressions. If there is no match, the SAML assertion is rejected.
    This optional feature gives you more fine-grained control over which signing certificates to trust.
One of the most important configuration settings for SAMLTokenValidator is made indirectly, by specifying the signature trust store for the parent TokenValidateOperation instance. The signature trust store is usually configured by setting the signaturePropertiesFile property on the StaticSTSProperties bean, and then injecting the StaticSTSProperties bean into the TokenValidateOperation instance. For example, see Example 9.2, “Configuring the STS Validate Operation”.
To configure and customize the SAMLTokenValidator class, you can set some or all of the following properties:
subjectConstraints
Specifies a list of regular expression strings. If this property is set, the subject DN extracted from the X.509 embedded in the SAML assertion must match one of the specified regular expressions. If this property is not set, no test is applied to the subject DN.
validator
You can optionally set this property to customize the step that checks whether or not the embedded X.509 certificate is trusted or not. By default, the WSS4J SignatureTrustValidator class is used.
samlRealmCodec
If you want to use realms with SAML tokens, you must implement the SAMLRealmCodec interface and inject an instance into this property. The purpose of the SAML realm codec is to assign a realm to the SAML token, based on the contents of the SAML assertion. No SAML realm codec is set by default.
For more details about using realms with the STS, see Section 9.5, “Enabling Realms in the STS”.

UsernameTokenValidator
Copy link

A registered UsernameTokenValidator instance is triggered to validate a token, if the received token can be parsed as a UsernameToken.
Validating a WSS UsernameToken consists, essentially, of checking that the client has supplied the correct password for the username. This implies that the STS server must be configured with a database of usernames and passwords, so that it can check the UsernameToken credentials.
The WSS4J library provides two alternative validator implementations for validating UsernameToken credentials, as follows:
UsernameTokenValidator
(Default) This WSS4J validator implementation uses a CallbackHandler object to look up passwords, where the callback handler, is specified by setting the callbackHandler property on the StaticSTSProperties object—see Section 9.1.6, “Configuring STS Properties”.
To use this validator, you must provide your own CallbackHandler implementation. For example, see the section called “STS callback handler ”
JAASUsernameTokenValidator
This WSS4J validator implementation integrates password lookup with JAAS, so that the UsernameToken credentials are checked using a JAAS login module. In particular, by configuring an appropriate JAAS login module, you could integrate the UsernameToken validator with an LDAP database.
To use this token validator, create an instance of JAASUsernameTokenValidator and inject it into the validator property of the UsernameTokenValidator bean.
It is also possible to add support for realms, by implementing the UsernameTokenRealmCodec interface and registering it with the UsernameTokenValidator bean—for details, see Section 9.5, “Enabling Realms in the STS”.

X509TokenValidator
Copy link

A registered X509TokenValidator instance is triggered to validate a token, if the received token can be parsed as a BinarySecurityToken type.
Validating an X.509 token (encoded as a BinarySecurityToken in Base-64 encoding) consists of checking that the received certificate is trusted.
The default validator used by the X509TokenValidator class is the WSS4J SignatureTrustValidator, which checks that the X.509 certificate is either present in the trust store or is signed by a private key corresponding to one of the certificates in the trust store (certificate chaining). The trust store that is used for this purpose is the signature trust store on the StaticSTSProperties object—see Section 9.1.6, “Configuring STS Properties”.

SCTValidator
Copy link

A registered SCTValidator instance is triggered to validate a token, if the received token can be parsed as a SecurityContextToken type and belongs to one of the following namespaces:
Expand
Namespaces handled by SCTValidator
http://schemas.xmlsoap.org/ws/2005/02/sc
http://docs.oasis-open.org/ws-sx/ws-secureconversation/200512
The SCTValidator is used to validate security context tokens in the context of WS-SecureConversation sessions, which is currently not covered by this documentation.

Sample configuration
Copy link

Example 9.2, “Configuring the STS Validate Operation” shows an example of how to configure the STS Validate operation. In this example, the TokenValidateOperation class is configured to use a SAMLTokenValidator token validator.

Example 9.2. Configuring the STS Validate Operation

<beans ... >
    ...
    <bean id="utSTSProviderBean"
        class="org.apache.cxf.ws.security.sts.provider.SecurityTokenServiceProvider">
        ...
        <property name="validateOperation" ref="utValidateDelegate"/>
    </bean>    
    ...    
    <bean id="utValidateDelegate"
        class="org.apache.cxf.sts.operation.TokenValidateOperation">
        <property name="tokenValidators" ref="utSamlTokenValidator"/>
        <property name="stsProperties" ref="utSTSProperties"/>
    </bean>
    ...    
    <bean id="utSamlTokenValidator"
        class="org.apache.cxf.sts.token.validator.SAMLTokenValidator">
    </bean>
    ...    
    <bean id="utSTSProperties"
         class="org.apache.cxf.sts.StaticSTSProperties">
        <property name="signaturePropertiesFile" value="stsKeystore.properties"/>
        <property name="signatureUsername" value="mystskey"/>
        <property name="callbackHandlerClass" value="demo.wssec.sts.STSCallbackHandler"/>
        <property name="issuer" value="DoubleItSTSIssuer"/>
    </bean>
    ...
</beans>
Copy to Clipboard Toggle word wrap

9.1.5. Customizing the Cancel Operation
Copy link

TokenCancelOperation
Copy link

Figure 9.4, “Configuring TokenCancelOperation” shows an overview of the components that are involved in the Cancel operation.

Figure 9.4. Configuring TokenCancelOperation

Plug-in framework
Copy link

The following property can be set on the TokenCancelOperation class:
tokencancellers
Specifies a list of token cancellers, where each token canceller is capable of canceling tokens of a particular type. Currently, the only token canceller implementation provided is the SCTCanceller, for canceling WS-SecureConversation tokens.

SCTCanceller
Copy link

The SCTCanceller token canceller is used in the context of WS-SecureConversation to cancel security context tokens.
A registered SCTCanceller instance is triggered to cancel a token, if the token namespace specified by the requesting STS client is one of the following:
Expand
Namespaces handled by the SCTCanceller
http://docs.oasis-open.org/ws-sx/ws-secureconversation/200512
http://schemas.xmlsoap.org/ws/2005/02/sc
You can optionally set the following property on an SCTCanceller instance:
verifyProofOfPossession
When the verifyProofOfPossession flag is enabled, only the owner of the security context token is allowed to cancel the token. To prove possession of the token, the client must demonstrate that it knows the secret key associated with the security context token. The client demonstrates knowledge of the key by signing some part of the SOAP message using the secret key.
Default is true.

Sample configuration of SCTCanceller
Copy link

Example 9.3, “Configuring the STS Cancel Operation” shows an example of how to configure the STS Cancel operation. In this example, the TokenCancelOperation class is configured to use an SCTCanceller token canceller.

Example 9.3. Configuring the STS Cancel Operation

<beans ... >
    ...
    <bean id="utSTSProviderBean"
        class="org.apache.cxf.ws.security.sts.provider.SecurityTokenServiceProvider">
        <property name="cancelOperation" ref="utCancelDelegate"/>
        ...
    </bean>    

    <bean id="utCancelDelegate"
        class="org.apache.cxf.sts.operation.TokenCancelOperation">
        <property name="tokencancellers" ref="utSctCanceller"/>
        ...
        <property name="stsProperties" ref="utSTSProperties"/>
    </bean>
    ...    
    <bean id="utSctCanceller"
        class="org.apache.cxf.sts.token.canceller.SCTCanceller">
        <property name="verifyProofOfPossession" value="false"/>
    </bean>
    ...    
    <bean id="utSTSProperties"
         class="org.apache.cxf.sts.StaticSTSProperties">
        <property name="signaturePropertiesFile" value="stsKeystore.properties"/>
        <property name="signatureUsername" value="mystskey"/>
        <property name="callbackHandlerClass" value="demo.wssec.sts.STSCallbackHandler"/>
        <property name="issuer" value="DoubleItSTSIssuer"/>
    </bean>
    ...    
</beans>
Copy to Clipboard Toggle word wrap

9.1.6. Configuring STS Properties
Copy link

Overview
Copy link

The STS properties are a general collection of properties, used for various purposes in the STS. In particular, some of the properties are used to load resources for the STS, such as a signing key and an encryption key.
The STS properties are encapsulated in a StaticSTSProperties instance (which implements the STSPropertiesMBean interface) and can be injected into the various operation implementations (TokenIssueOperation, TokenValidateOperation, and so on).

What you can configure with STS properties
Copy link

You can use the STS properties to configure the following aspects of the STS:

Issuer
Copy link

The issuer is a string that uniquely identifies the issuing STS. The issuer string is normally embedded in issued tokens and, when validating tokens, the STS normally checks the issuer string value. Consequently, it is important to use the issuer string in a consistent way, so that the STS can recognize the tokens that it has issued.
The issuer string is also important in the context of using realms. See Section 9.5, “Enabling Realms in the STS”.
For example, you can set the issuer string as follows: 
<beans ... >
    ...
    <bean id="utSTSProperties"
         class="org.apache.cxf.sts.StaticSTSProperties">
        ...
        <property name="issuer" value="DoubleItSTSIssuer"/>
    </bean>
    ...    
</beans>
Copy to Clipboard Toggle word wrap

Callback handler
Copy link

The callback handler is a Java class that implements the javax.security.auth.callback.CallbackHandler interface. The purpose of the callback handler is to provide any passwords required by the STS. In particular, the callback handler is normally used to provide the password to access the STS signing key.
For an example of an STS callback handler implementation, see the section called “STS callback handler ”. 
<beans ... >
    ...
    <bean id="utSTSProperties"
         class="org.apache.cxf.sts.StaticSTSProperties">
        ...
        <property name="callbackHandlerClass" value="demo.wssec.sts.STSCallbackHandler"/>
        ...
    </bean>
    ...    
</beans>
Copy to Clipboard Toggle word wrap

Signing key
Copy link

The must important use of the STS signing key is for signing SAML tokens, so that WS servers can establish trust in the issued SAML token. There are several properties available for specifying the signing key, which allow you to specify the signing key in a variety of different ways and to customize the signing algorithm. The properties are as follows:
signatureCrypto
Specifies the signing key directly as an org.apache.ws.security.components.crypto.Crypto instance. This is the most flexible way of configuring the signing key, but also the most complicated. The signaturePropertiesFile property offers an easier alternative for specifying the signing key.
signaturePropertiesFile
Specifies the location of a file containing WSS4J keystore properties, that provide access to the signing key in a Java keystore file. For details of the WSS4J keystore properties that you can set in this file, see Table 6.2.
signatureUsername
Specifies the alias of the signing key in the specified Java keystore.
signatureProperties
(Optional) By injecting an org.apache.cxf.sts.SignatureProperties instance into this property, you can fine-tune the signing algorithm used by the STS.
For example, the following example shows how to specify the signing key using the signaturePropertiesFile property, where the private key with the alias, mystskey, is selected from the specified Java keystore. 
<beans ... >
    ...
    <bean id="utSTSProperties"
         class="org.apache.cxf.sts.StaticSTSProperties">
        <property name="signaturePropertiesFile" value="stsKeystore.properties"/>
        <property name="signatureUsername" value="mystskey"/>
        ...
    </bean>
    ...    
</beans>
Copy to Clipboard Toggle word wrap
The stsKeystore.properties file typically contains WSS4J keystore properties like the following: 
org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin
org.apache.ws.security.crypto.merlin.keystore.type=jks
org.apache.ws.security.crypto.merlin.keystore.password=stsspass
org.apache.ws.security.crypto.merlin.keystore.file=keys/stsstore.jks
Copy to Clipboard Toggle word wrap
Where the signing key is stored in the stsstore.jks Java keystore file and the stsspass password unlocks the keystore file.

Encrypting key
Copy link

The encrypting key is (optionally) used for encrypting issued tokens. It is only necessary to configure the encrypting key, if the encryptIssuedToken option is set to true on the TokenIssueOperation instance—see Section 9.1.3, “Customizing the Issue Operation”.
There are several properties available for specifying the encrypting key, which allow you to specify the encrypting key in a variety of different ways and to customize the encryption algorithm. The properties are as follows:
encryptionCrypto
Specifies the encryption key directly as an org.apache.ws.security.components.crypto.Crypto instance. This is the most flexible way of configuring the encryption key, but also the most complicated. The encryptionPropertiesFile property offers an easier alternative for specifying the encryption key.
encryptionPropertiesFile
Specifies the location of a file containing WSS4J keystore properties, that provide access to the encryption key in a Java keystore file. For details of the WSS4J keystore properties that you can set in this file, see Table 6.2.
encryptionUsername
Specifies the alias of the encryption key in the specified Java keystore.
encryptionProperties
(Optional) By injecting an org.apache.cxf.sts.service.EncryptionProperties instance into this property, you can fine-tune the encryption algorithm used by the STS.

Realm settings
Copy link

The following properties are relevant only when realm support is enabled in the STS (as described in Section 9.5, “Enabling Realms in the STS”)L
realmParser
(Optional) In the context of enabling realms in the STS, you would inject an org.apache.cxf.sts.RealmParser instance into this property, to give STS the ability to decide which realm the current token should be issued in. For more details, see Section 9.5.1, “Issuing Tokens in Multiple Realms”.
identityMapper
(Optional) In the context of token transformation in the STS, you would inject an org.apache.cxf.sts.IdentityMapper instance into this property, which has the capability to map a principal in the context of one realm to the corresponding principal in the context of another realm. For more details, see Section 9.5.3, “Token Transformation across Realms”.
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat