Ce contenu n'est pas disponible dans la langue sélectionnée.
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
9.1.1. Overview of the STS
Architecture
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
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
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:RequestSecurityTokenCollectionelement, which consists of a list ofwst:RequestSecurityTokenelements).
STS policies
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
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:
IssueOperationIssueSingleOperationValidateOperationRenewOperationCancelOperation
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
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
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
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
Overview
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, TCP port, and context path of the STS Web service endpoint can be customized by editing the address attribute of the WSDL port.NoteMoreover, 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
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>
For each of the STS operations, the following message types are sent or received:
- Request message types—are either:
RequestSecurityToken(RST) type, for theIssue,Renew,Validate,Cancel, andKeyExchangeTokenoperations; orRequestSecurityTokenCollectiontype, for theRequestCollectionoperation.
- Response message types—are either:
RequestSecurityTokenResponse(RSTR) type, for theRenew,Validate,Cancel, andKeyExchangeTokenoperations; orRequestSecurityTokenResponseCollectiontype, for theIssueandRequestCollectionoperations.
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
Choosing a WSDL binding
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
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>
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 TCP port where the STS is actually running.
Choosing policies
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
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>
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).
Example of SymmetricBinding and UsernameToken policy
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>9.1.3. Customizing the Issue Operation
TokenIssueOperation
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.
Note
The STS issues tokens using the RSA-SHA256 signature algorithm and the SHA-256 digest algorithm by default.
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
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
TokenIssueOperationclass 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 thecanHandle()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
AppliesTopolicy 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 theTokenIssueOperation, through the properties defined on theStaticSTSPropertiesinstance—see the section called “Encrypting key”
Token providers
The Apache CXF STS currently provides the following token provider implementations:
SAMLTokenProvider
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:
| 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
DefaultAttributeStatementProviderclass 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
OnBehalfOfelement or anActAselement containing aUsernameTokenwas present in the Issue request. - An attribute statements containing a subject name, if an
OnBehalfOfelement or anActAselement 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
DefaultSubjectProviderclass 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 withSymmetricKey; Holder-of-Key withPublicKeyalgorithm; andBearer. conditionsProvider- You can optionally set this property to define a custom conditions provider.If this property is not set, the
DefaultConditionsProviderclass 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 receivedAppliesToaddress (if any). signToken- Specifies whether or not to sign the SAML token. Default is
true. realmMap- Specifies a map that associates realm names with
SAMLRealmobjects. Only required, if you want to enable support for realms. For details, see Section 9.5, “Enabling Realms in the STS”.
SCTProvider
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:
| 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
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>9.1.4. Customizing the Validate Operation
TokenValidateOperation
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
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
TokenValidateOperationclass 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 thecanHandle()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
AppliesTopolicy 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
The Apache CXF STS currently provides the following token validator implementations:
SAMLTokenValidator
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:
| 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>
The
SAMLTokenValidator class uses the following algorithm to validate the received SAML token:
- The SAML assertion is first checked, to ensure that it is well-formed.
- If the assertion is not signed, it is rejected.
- 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.
- 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
signaturePropertiesFileproperty or thesignatureCryptoproperty on theStaticSTSPropertiesobject—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). - If the
subjectConstraintsproperty is set on theSAMLTokenValidatorinstance, 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
SignatureTrustValidatorclass is used. samlRealmCodec- If you want to use realms with SAML tokens, you must implement the
SAMLRealmCodecinterface 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
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
CallbackHandlerobject to look up passwords, where the callback handler, is specified by setting thecallbackHandlerproperty on theStaticSTSPropertiesobject—see Section 9.1.6, “Configuring STS Properties”.To use this validator, you must provide your ownCallbackHandlerimplementation. 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
JAASUsernameTokenValidatorand inject it into thevalidatorproperty of theUsernameTokenValidatorbean.
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
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
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:
| 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
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>9.1.5. Customizing the Cancel Operation
TokenCancelOperation
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
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
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:
| 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
verifyProofOfPossessionflag 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 istrue.
Sample configuration of SCTCanceller
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>9.1.6. Configuring STS Properties
Overview
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
You can use the STS properties to configure the following aspects of the STS:
Issuer
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>Callback handler
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>Signing key
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.Cryptoinstance. This is the most flexible way of configuring the signing key, but also the most complicated. ThesignaturePropertiesFileproperty 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.SignaturePropertiesinstance 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>
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
Where the signing key is stored in the
stsstore.jks Java keystore file and the stsspass password unlocks the keystore file.
Encrypting key
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.Cryptoinstance. This is the most flexible way of configuring the encryption key, but also the most complicated. TheencryptionPropertiesFileproperty 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.EncryptionPropertiesinstance into this property, you can fine-tune the encryption algorithm used by the STS.
Realm settings
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.RealmParserinstance 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.IdentityMapperinstance 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”.
