Open Source Security

WS-Trust SPNego support in Apache CXF

2012-02-22T05:02:00.000-08:00

Support for SPNego using WS-Trust has been added to Apache CXF and will be available in the forthcoming 2.4.7 and 2.5.3 releases. This new functionality allows a CXF client to integrate with WCF 4.0, as WCF 4.0 uses message level NTLM/Kerberos based on SPNego using WS-Trust. See the following blog for an in-depth explanation of how to do exactly this. Support for obtaining and validating SPNEGO tokens was added to Apache WSS4J in the 1.6.4 release. WSS4J 1.6.5 will feature support for making the Spnego Client and Service Action classes pluggable, so that the user can specify a custom means of obtaining the ticket.

Using WS-Trust for SPNego is described in the following application note. The client contacts a KDC and obtains a SP Negotiation token, which it sends to the service provider via WS-Trust. If the negotiation is incomplete, the service provider can respond to the client to continue the negotiation. Once the negotiation is complete, a WS-Trust RequestedProofToken is created which contains a secret key that has been encrypted with the negotiated key, and this is returned to the client along with an Authenticator and a SecurityContextToken. The client can decrypt the EncryptedKey, and use this key with a symmetric encryption or signature algorithm to secure a request.

Note that the focus is on making sure that a CXF client can interoperate with WCF, and hence the STS support for SPNego is only intended as a means of testing the client code. In particular, the STS does not return an Authenticator, which is required by the spec. One additional limitation is that the STS client does not currently support continued negotation.

1) Running the WS-Trust SPNego system tests in Apache CXF

To run the WS-Trust SPNego system tests in CXF, it is first necessary to set up a KDC correctly. Follow the instructions given in section 1 in a previous blog post which describes how to run the Kerberos system tests in CXF. Next, make sure that the JDK has unlimited security policies installed, and then checkout the CXF trunk via:

svn co https://svn.apache.org/repos/asf/cxf/trunk/

Go into the "trunk" directory, and compile and install CXF via "mvn -Pfastinstall" (this will avoid running tests). Finally go into the WS-Security system tests in "systests/ws-security". The SpnegoTokenTest contains two tests, which are @Ignore'd by default. Open SpnegoTokenTest.java and comment out the "@org.junit.Ignore" entries for both tests. If you want to see the message exchanges, open src/test/resources/logging.properties, and change the level from WARNING to INFO, and the ConsoleHandler level from SEVERE to INFO. Finally, run the tests via:

mvn test -Dtest=SpnegoTokenTest -Djava.security.auth.login.config=src/test/resources/kerberos.jaas

1.1) WS-SecurityPolicy configuration

The wsdl that defines the service endpoints contains WS-SecurityPolicy expressions that define the security requirements of the endpoints. The following security policies are used for the tests:

DoubleItSpnegoSymmetricProtectionPolicy: This uses a Symmetric binding, where the protection token is a SpnegoContextToken.
DoubleItSpnegoSymmetricProtectionDerivedPolicy: This uses a Symmetric binding, where the protection token is key derived from a SpnegoContextToken.

1.2) Kerberos LoginModule configuration

Both the CXF client and service endpoint use JAAS to authenticate to the KDC. The JAAS file used as part of the system test is passed to the tests via the System property "java.security.auth.login.config". The client (alice) uses the following login module:

alice {
    com.sun.security.auth.module.Krb5LoginModule required
    refreshKrb5Config=true useKeyTab=true keyTab="/etc/alice.keytab"
    principal="alice";
};

and the service endpoint (bob) uses:

bob {
com.sun.security.auth.module.Krb5LoginModule required
refreshKrb5Config=true useKeyTab=true storeKey=true
keyTab="/etc/bob.keytab" principal="bob/service.ws.apache.org";
};

1.3) Client and Service endpoint configuration

Both the service and client endpoints are spring-loaded. The contain the following JAX-WS properties, which are defined in SecurityConstants:

"ws-security.kerberos.jaas.context" - This refers to the JAAS context given in the configuration file above. The clients use a value of "alice", and the service endpoints use "bob".
"ws-security.kerberos.spn"- This is only configured on the client side, and specifies the Kerberos Service Provider Name ("bob@service.ws.apache.org").

Finally, there is one additional JAX-WS property that can be defined on the client, if you want to plug in a custom WSS4J SpnegoClientAction implementation:

"ws-security.spnego.client.action" - The SpnegoClientAction implementation to use for SPNEGO. This allows the user to plug in a different implementation to obtain a service ticket. See here for more details on how to use this property.

Apache Santuario (XML Security for Java) 1.5.0 released

2012-01-24T07:51:00.000-08:00

Apache Santuario (XML Security for Java) 1.5.0 has been released. It can be downloaded here. Please read the release notes (collated from my previous blog entries) if you are planning to upgrade.

Apache Santuario (XML Security for Java) 1.5.0 RC2

2012-01-13T08:52:00.000-08:00

I posted a RC1 for Apache Santuario (XML Security for Java) almost a month ago now. Since then, a large number of changes have been made to address some inconsistencies in RC1 as well to add some new functionality. The RC2 release is available here. Please download it and post any issues that are found to the mailing list. The changes compared to the RC1 release (documented here) are as follows:

1) Support for RSA-OAEP key transport algorithms with strong digests

The 1.4.x releases only support using SHA-1 with the RSA-OAEP key transport algorithm for encryption and decryption. The 1.5.0 RC2 release supports stronger digests using the ds:DigestMethod child of xenc:EncrytionMethod. In addition, it fully supports the xenc11:MGF Algorithm as documented in the XML Encryption 1.1 specification.

To test this functionality, all of the XML Encryption 1.1 Key Wrapping test-cases have been implemented, both for encryption and decryption. These tests also serve to better test the support for GCM algorithms in the 1.5.0 release. Support for 192 bit AES-GCM was added as part of this work.

2) Major changes to how Elements are resolved

The release notes for RC1 described how the IdResolver no longer searches the current Document for an Element matching the requested Id in certain "known" namespaces, and instead how it was the responsibility of the user to register Elements by Id in the IdResolver (or via setIdAttributeNS if using the JSR-105 API), if they are required as part of the signature validation process.

In RC2, the static cache of Id->Elements that was maintained in the IdResolver has been removed. Instead, the ResourceResolver implementations that are responsible for resolving same-Document URI references resolve Elements by querying Document.getElementById(). The IdResolver has been deprecated, so that it is no longer possible to register an Element by Id, and the "get" methods simply delegate to the DOM call above.

So what does this mean for the user? The user is now responsible for registering any same-Document Elements by Id, which must be resolved as part of the signature creation/validation process. This can be done in two ways:

Using the DOM APIs: Element.setIdAttribute*
Using the JSR-105 API: DOMCryptoContext.setIdAttributeNS

3) Better protection against Signature Wrapping Attacks

A Signature Wrapping attack can occur when a malicious entity duplicates some signed Element in a document, and then modifies the content of the duplicated Element, but keeps the same Id. If the signature validation process only finds the initial Element, then signature validation will pass, and the user might be fooled into thinking that the modified Element has been signed, as it has the same Id as the original validated Element.

The implication of this attack is that it is vital that the user checks that the Elements that were signed correspond to the Elements that he/she expects to be signed. In other words, the Elements that were signed should be located in a specific "known" place in the Document. The best way of facilitating this check is to make sure that the signature validation process returns the Elements that it validated. The JSR-105 API supports this via the "javax.xml.crypto.dsig.cacheReference" boolean property, that can be set on the context.

However, the older XMLSignature, which pre-dates the JSR-105 API, did not include this functionality. This has been fixed in the RC2 release, e.g.:

XMLSignature signature = ...
// Perform validation and then...
SignedInfo signedInfo = signature.getSignedInfo();
for (int i = 0; i < signedInfo.getLength(); i++) {
    Reference reference = signedInfo.item(i);
    ReferenceData refData = reference.getReferenceData();
    ....
}

ReferenceData is a new interface that duplicates the way the JSR-105 API returns references. Three different implementations have been provided depending on whether the dereferenced Element is a NodeSet, Element or OctetStream.

Finally, some new functionality has been added when secure validation is enabled, to ensure that when an Element is de-referenced via Document.getElementById() (as described above), no other Element in the tree has an Attribute that is also registered as an Id with the same value. This is done via a tree search, and guarantees that the Element retrieved via the getElementById call is unique in the Document (something that is not guaranteed by the contract of getElementById). However note that another Element could still exist in the tree with a matching Id in another namespace.

Apache CXF 2.5.1 STS updates

2012-01-13T06:25:00.000-08:00

Last year I wrote a series of blog posts (starting here) documenting the Security Token Service (STS) implementation included as part of Apache CXF 2.5.0. Apache CXF 2.5.1 was released a few weeks ago, and includes a number of bug fixes and improvements to the STS. In this post I'll document the more important changes.

1) Support to configure keystores per SAML realm

In CXF 2.5.0 it was possible to sign an issued SAML Token using a different private key per realm, by setting the "signatureAlias" property of the SAMLRealm class. However, the signature alias is used with a single KeyStore, which is shared across all realms. This problem has been fixed in CXF 2.5.1, where it is now possible to also configure a keystore to use per-realm.

2) Support to handle claims per realm

In CXF 2.5.1 support has been added to handle claims per-realm. The ClaimsHandler interface has been updated to so that the current realm and WebServiceContext object are available when retrieving claim values. This means that any custom ClaimsHandler implementation based on CXF 2.5.0 must be updated to reflect the changed method signature.

3) Support validating a token per realm

In CXF 2.5.0 the current realm is ignored when validating a token. In CXF 2.5.1, support has been added to include the current realm when querying a TokenValidator implementation to see if it can "handle" a given token. In addition, all TokenValidator implementations that ship with the STS return a Principal as part of the TokenValidatorResponse object, regardless of whether validation was successful or not.

4) OnBehalfOf Token Validation

In CXF 2.5.0 the responsibility for validating "OnBehalfOf" tokens was delegated to the TokenProvider implementation. In CXF 2.5.1, OnBehalfOf Token Validation has been moved to the TokenIssueOperation, and so OnBehalfOf Tokens are validated for all subsequent TokenProviders. This validation is achieved by querying a list of TokenValidator implementations to see if any can validate the received token. If validation is successful, then the state of the ReceivedToken (VALID, INVALID, NONE) is updated to reflect this. If no TokenValidator implementation exists that can validate the OnBehalfOf token, then the token has a state set to INVALID. Identity Mapping also now applies to the (VALID) OnBehalfOf Token.

5) Support for OnBehalfOf in the SAMLTokenProvider

In CXF 2.5.0, the SAMLTokenProvider can issue a SAML token based on the authenticated principal associated with the request, e.g. the principal associated with the security token in the WS-Security header. It does not support the scenario that a client is requesting a SAML token "OnBehalfOf" another SAML Token, in other words that the principal name associated with the "OnBehalfOf" token is used as the subject name of the issued SAML token. This functionality has been added in CXF 2.5.1.

6) Validate SAML Conditions against the current time

Support has been added to validate the Conditions of a received SAML Token against the current time.

WS-SecurityPolicy Examples in Apache CXF

2011-12-20T04:35:00.000-08:00

The OASIS WS-SecurityPolicy Examples Version 1.0 specification gives a set of example policies for standard security deployments, as well as the corresponding message exchanges generated by those policies. The policies in the spec cover UsernameTokens, X509 Tokens, SAML Tokens and SecureConversation, used in conjunction with various security bindings (symmetric/asymmetric/transport).

I have implemented a set of system tests in Apache CXF that use these policies with a standard "double it" web service invocation. All of the policies in the specification are covered, apart from 2.2.2.1 which is an uncommon use-case of using an IssuedToken policy to reference an agreed out-of-band token.

The example tests are a good way of understanding how to implement and use various security policies. Here are links to the various tests and WSDLs which include the corresponding security policies:

Username Token: Test and WSDL.
X509 Token: Test and WSDL.
SAML Token: Test and WSDL.
Secure Conversation: Test and WSDL.

Apache Santuario (XML Security for Java) 1.5.0 RC1

2011-12-19T08:16:00.000-08:00

A release candidate for Apache Santuario (XML Security for Java) 1.5.0 has been published. Please download it and post any issues that are found to the mailing list. The 1.5.0 release is not binary compatible with the 1.4.x code due to extensive refactoring. Some of the more significant changes are as follows:

1) JDK 1.4.x support dropped

The 1.5.0 release drops support for JDK 1.4.x (see here and here). The APIs have been updated to use generics where possible.

2) Xalan is no longer a required dependency

Xalan/Xerces/Xml-apis are now optional dependencies, and have been marked as such in the pom. These libraries are only required if you want to support the XPath here() function, which is not supported by the XPath API in the JDK.

3) GCM support added

Support for GCM algorithms has been added via a third-party provider. See here for an example of how this is done in Apache WSS4J via BouncyCastle.

4) JSR-105 provider has been renamed

The Santuario JSR-105 provider "org.jcp.xml.dsig.internal.XMLDSigRI" has been renamed as "org.apache.jcp.xml.dsig.internal.XMLDSigRI". This is to avoid conflict with the JDK provider of the same name. In addition, the XMLDSigRI provider's name has changed from "XMLDSig" to "ApacheXMLDSig". See here for more details.

Please note that it won't be possible to drop in the xmlsec.jar inthe endorsed directory anymore and expect it to override the JDK's JSR 105provider. You will need to edit the java.security file to register the newprovider, or hard-code the provider name in your application code.

5) Secure Validation property

A new property has been added to enable "secure validation". This property is false by default. When set to true, it enforces the following processing rules:

Limits the number of Transforms per Reference to a maximum of 5.
Does not allow XSLT transforms.
Does not allow a RetrievalMethod to reference another RetrievalMethod.
Does not allow a Reference to call the ResolverLocalFilesystem orthe ResolverDirectHTTP (references to local files and HTTP resourcesare forbidden).
Limits the number of references per Manifest (SignedInfo) to a maximum of 30.
MD5 is not allowed as a SignatureAlgorithm or DigestAlgorithm.

This functionality is supported in the core library through additional method signatures which take a boolean, and in the JSR-105 API via the property "org.apache.jcp.xml.dsig.secureValidation, e.g.:

XMLValidateContext context = new DOMValidateContext(key, elem);
context.setProperty("org.apache.jcp.xml.dsig.secureValidation", Boolean.TRUE);

6) Dynamic registration of default algorithms

The 1.4.x release loads all supported algorithms/implementations by reading and parsing an xml configuration file. This gives the user the power to override the default configuration file by setting the appropriate system property, and to add/remove algorithms as desired.

The downside to the current configuration approach is the performance issue of reading a file from the filesystem, parsing it, and then class-loading all of the implementations. Given that the majority of users probably just use the default algorithms that come with the library, this represents a performance issue on start-up.

In 1.5.0, the default algorithms are loaded dynamically. To revert to the older behaviour of loading algorithms from a properties file then set the System property "org.apache.xml.security.resource.config" to point to the file.

7) The IdResolver no longer searches for Elements in "known" namespaces

The IdResolver class is responsible for retrieving Elements for a given Id. In the 1.5.0 release it will no longer attempt to search the current Document for an Element matching the requested Id in certain "known" namespaces (e.g. SOAP Message Security). It is the responsibility of the user to register Elements by Id in the IdResolver, if they are required as part of the signature validation process. This can be done via the "setIdAttributeNS" method in the DOMCryptoContext for users of the JSR-105 API.

Apache CXF STS documentation - part XII

2011-11-22T08:57:00.001-08:00

A previous blog post detailed the AbstractOperation class that provides some core functionality for the STS operations, such as parsing the client request into a format that the TokenProviders/TokenValidators/TokenCancellers can consume. In this, the final post of this series of articles on the Apache CXF STS, we will examine an extension of AbstractOperation that is used to cancel tokens. Finally, we will look at the STS sample that ships with the CXF 2.5.x distribution.

1) The TokenCancelOperation

TokenCancelOperation is used to cancel tokens in the STS. It implements the CancelOperation interface in the STS provider framework. In addition to the properties that it inherits from AbstractOperation (detailed previously), it has a single property that can be configured:

List<TokenCanceller> tokencancellers - A list of TokenCanceller implementations to use to cancel tokens.

Recall that AbstractOperation uses the RequestParser to parse a client request into TokenRequirements and KeyRequirementsobjects. TokenCancelOperation first checks that a "CancelTarget" token was received and successfully parsed (if so it will be stored in the TokenRequirements object). If no token was received then an exception is thrown.

TokenCancelOperation then populates a TokenCancellerParametersobject with values extracted from the TokenRequirements and KeyRequirements objects. It iterates through the list of defined TokenCanceller implementations to see if any "can handle" the received token. If no TokenCanceller is defined, or if no TokenCanceller can handle the received token, then an exception is thrown. Otherwise, the received token is cancelled. If there is an error in cancelling the token, then an exception is also thrown. A response is constructed with the context attribute (if applicable), and the cancelled token type.

2) The STS sample in Apache CXF

Finally, we'll take a brief look at the STS sample that ships with Apache CXF. Download and extract the Apache CXF 2.5.x distribution. Navigate into "samples/sts" and take a look at the README.txt. The service provider has a policy that requires a SAML 2.0 token issued by an STS. The client authenticates itself to the STS with a UsernameToken over the symmetric binding. The STS issues a SAML 2.0 token to the client, which sends it to the service. The IssuedToken is defined as an InitiatorToken of an Asymmetric binding in the policy of the service, and so the client will use the secret key associated with the Subject of the Assertion to sign various parts of the message.

Build the sample with "mvn install", and then open up three separate command prompts. Start the STS with "mvn -Psts" in one, and start the service with "mvn -Pserver" in another. Finally, start the sample in the other window with "mvn -Pclient". You will see the (encrypted) messages flowing first between the client and the STS, and then between the client and the service provider.

Apache CXF STS documentation - part XI

2011-11-21T06:14:00.000-08:00

1) The TokenValidateOperation

TokenValidateOperation is used to validate tokens in the STS. It implements the ValidateOperation interface in the STS provider framework. In addition to the properties that it inherits from AbstractOperation (detailed previously), it has a single property that can be configured:

List<TokenValidator> tokenValidators - A list of TokenValidator implementations to use to validate tokens.

Recall that AbstractOperation uses the RequestParser to parse a client request into TokenRequirements and KeyRequirements objects. TokenValidateOperation first checks that a "ValidateTarget" token was received and successfully parsed (if so it will be stored in the TokenRequirements object). If no token was received then an exception is thrown.

2) Token validation and response

TokenValidateOperation then populates a TokenValidatorParameters object with values extracted from the TokenRequirements and KeyRequirements objects. It iterates through the list of defined TokenValidator implementations to see if any "can handle" the received token. If no TokenValidator is defined, or if no TokenValidator can handle the received token, then an exception is thrown. Otherwise, the received token is validated. The TokenValidateOperation then checks to see whether token transformation is required.

2.1) Token Transformation

If the received token is successfully validated, and if the client supplies a TokenType in the request that does not correspond to the WS-Trust "status" namespace, then the TokenValidateOperation attempts to transform the validated token into a token of the requested type. Token transformation works in a similar way to token issuing, as detailed previously. A TokenProviderParameters object is constructed and the same processing steps (Realm parsing, AppliesTo parsing) are followed as for token issuing.

One additional processing step occurs before the token is transformed. If the TokenValidatorResponse object has a principal that was set by the TokenValidator implementation, then it is set as the principal of the TokenProviderParameters object. However, it is possible that the token is being issued in a different realm to that of the validated token, and the principal might also need to be transformed. Recall that the STSPropertiesMBean configuration object defined on AbstractOperation has an IdentityMapper property. This interface is used to map identities across realms. It has a single method:

Principal mapPrincipal(String sourceRealm, Principal sourcePrincipal, String targetRealm) - Map a principal from a source realm to a target realm

If the source realm is not null (the realm of the validated token as returned in TokenValidatorResponse), and if it does not equal the target realm (as set by the RealmParser), then the identity mapper is used to map the principal to the target realm and this is stored in TokenProviderParameters for use in token generation. After the (optional) identity mapping step, TokenValidateOperation iterates through the TokenProvider list to find an implementation that can "handle" the desired token type in the given (target) realm (if applicable). If no TokenProvider is defined, or if no TokenProvider can handle the desired token type, then an exception is thrown.

2.2) Token response

After token validation has been performed, and after any optional token transformation steps, a response object is constructed containing the following items:

The context attribute (if any was specified).
The received Token Type (if any was specified, or the "status" token type if validation was successful).
Whether the received token was valid or not (status code & reason).
If the received token was valid, and if token transformation successfully occurred:
- The transformed token.
- The lifetime of the transformed token.
- A number of references to that token (can be disabled by configuration).

3) TokenValidateOperation example

Finally, it's time to look at an example of how to spring-load the STS so that it can validate tokens. This particular example uses a security policy that requires a UsernameToken over the transport binding (client auth is disabled). As the STS is a web service, we first define an endpoint:

<jaxws:endpoint id="transportSTS"
    implementor="#transportSTSProviderBean"
    address="http://.../SecurityTokenService/Transport"
    wsdlLocation=".../ws-trust-1.4-service.wsdl"
    xmlns:ns1="http://docs.oasis-open.org/ws-sx/ws-trust/200512/"
    serviceName="ns1:SecurityTokenService"
    endpointName="ns1:Transport_Port">
    <jaxws:properties>
        <entry key="ws-security.callback-handler" value="..."/>
    </jaxws:properties>
</jaxws:endpoint>

The CallbackHandler JAX-WS property is used to validate the UsernameToken. The "implementor" of the jaxws:endpoint is the SecurityTokenServiceProvider class defined in the STS provider framework:

<bean id="transportSTSProviderBean"
    class="org.apache.cxf.ws.security.sts.provider.SecurityTokenServiceProvider">
    ...
    <property name="validateOperation" ref="transportValidateDelegate"/>
</bean>

This bean supports the Validate Operation via a TokenValidateOperation instance:

<bean id="transportValidateDelegate"
    class="org.apache.cxf.sts.operation.TokenValidateOperation">
    <property name="tokenValidators" ref="transportTokenValidators"/>
    <property name="stsProperties" ref="transportSTSProperties"/>
</bean>

This TokenValidateOperation instance has a number of different TokenValidator instances configured:

<util:list id="transportTokenValidators">
    <ref bean="transportSamlTokenValidator"/>
    <ref bean="transportX509TokenValidator"/>
    <ref bean="transportUsernameTokenValidator"/>
</util:list>

<bean id="transportX509TokenValidator"
    class="org.apache.cxf.sts.token.validator.X509TokenValidator"/>

<bean id="transportUsernameTokenValidator"
    class="org.apache.cxf.sts.token.validator.UsernameTokenValidator"/>

<bean id="transportSamlTokenValidator"
    class="org.apache.cxf.sts.token.validator.SAMLTokenValidator"/>
</bean>

Finally the STSPropertiesMBean object that is used is given as follows:

<bean id="transportSTSProperties"
    class="org.apache.cxf.sts.StaticSTSProperties">
    <property name="signaturePropertiesFile" value="..."/>
    <property name="signatureUsername" value="mystskey"/>
    <property name="callbackHandlerClass" value="..."/>
    <property name="encryptionPropertiesFile" value="..."/>
    <property name="issuer" value="DoubleItSTSIssuer"/>
    <property name="encryptionUsername" value="myservicekey"/>
</bean>

Apache CXF STS documentation - part X

2011-11-15T06:56:00.001-08:00

The previous blog post introduced the TokenIssueOperation, which is used to issue tokens in the STS. The article covered the various processing steps that the TokenIssueOperation does on the parsed request, before it calls a TokenProvider instance to provide a token that is returned to the client. One step that was not covered was claims handling, as this is a complex topic that merits a deeper discussion. In this post, we will look at how claims are handled in the STS as a whole.

1) Claims Handling in the STS

A typical scenario for WS-Trust is when the client requires a particular security token from an STS to access a service provider. The service provider can let the client know what the requirements are for the security token in an IssuedToken policy embedded in the WSDL of the service. In particular, the service provider can advertise the claims that the security token must contain in the policy (either directly as a child element of IssuedToken, or else as part of the RequestSecurityTokenTemplate). An example is contained in the STS systests:


<sp:RequestSecurityTokenTemplate>
    <t:TokenType>http://...#SAMLV1.1</t:TokenType>
    <t:KeyType>http://.../PublicKey</t:KeyType>
    <t:Claims Dialect="http://.../identity">
        <ic:ClaimType Uri="http://.../claims/role"/>
    </t:Claims>
</sp:RequestSecurityTokenTemplate>

This template specifies that a SAML 1.1 Assertion is required with an embedded X509 Certificate in the subject of the Assertion. The issued Assertion must also contain a "role" claim. The template is sent verbatim by the client to the STS when requesting a security token.

1.1) Parsing claims

The RequestParser object parses the client request into TokenRequirements and KeyRequirements objects. As part of this processing it converts a received Claims element into a RequestClaimCollection object. The RequestClaimCollection is just a list of RequestClaim objects, along with a dialect URI. The RequestClaim object holds the claimType URI as well as a boolean indicating whether the claim is optional or not.

1.2) The ClaimsHandler

The ClaimsHandler is an interface that the user must implement to be able to "handle" a requested claim. It has two methods:

List getSupportedClaimTypes() - Return the list of ClaimType URIs that this ClaimHandler object can handle.
ClaimCollection retrieveClaimValues(Principal principal, RequestClaimCollection claims) - Return the claim values associated with the requested claims (and client principal).

The ClaimCollection object that is returned is just a list of Claim objects. This object represents a Claim that has been processed by a ClaimsHandler instance. It essentially contains a number of properties that the ClaimsHandler implementation will set, e.g.:

URI claimType - The claimtype URI as received from the client.
String value - The claim value

Each Claim object in a ClaimCollection corresponds to a RequestClaim object in the RequestClaimCollection, and contains the Claim value corresponding to the requested claim. How the ClaimsHandler is invoked to create the ClaimCollection will be covered later. The STS ships with a single ClaimsHandler implementation, the LDAPClaimsHandler, which can retrieve claims from an LDAP store. A simpler example is available in the unit tests.

1.3) The ClaimsManager

Recall that in the previous post, the TokenIssueOperation has a single additional property that can be configured:

ClaimsManager claimsManager - An object that is used to handle claims.

The ClaimsManager holds a list of ClaimsHandler objects. So to support claim handling in the STS, it is necessary to implement one or more ClaimsHandler objects for whatever Claim URIs you wish to support, and register them with a ClaimsManager instance, which will be configured on the TokenIssueOperation object.

As detailed in the previous article, the TokenIssueOperation gets the realm of the current request, and does some processing of the AppliesTo address, after the RequestParser has finished parsing the request. The RequestClaimCollection object that has been constructed by the RequestParser is then processed. For each RequestClaim in the collection, it checks to see whether the ClaimsManager has a ClaimsHandler implementation registered that can "handle" that Claim (by checking the URIs). If it does not, and if the requested claim is not optional, then an exception is thrown.

If a ClaimsHandler implementation is registered with the ClaimsManager that can handle the desired claim, then the claims are passed through to the TokenProvider implementation, which is expected to be able to invoke the relevant ClaimHandler object, and insert the processed Claim into the generated security token. How this is done is entirely up to the user. For example, for the use-case given above of a SAML 1.1 token containing a "role" claim, the user could implement a custom AttributeStatementProvider instance that evaluates the claim values (via a custom ClaimsHandler implementation registered with the ClaimsManager) and constructs a set of Attributes accordingly in an AttributeStatement. An example of how to do this is given in the unit tests.

Apache CXF STS documentation - part IX

2011-11-10T06:35:00.001-08:00

The previous blog post detailed the AbstractOperation class that provides some core functionality for the STS operations, such as parsing the client request into a format that the TokenProviders/TokenValidators/TokenCancellers can consume. In this post we will examine an extension of AbstractOperation that is used to issue tokens.

1) The TokenIssueOperation

TokenIssueOperation is used to issue tokens in the STS. It implements the IssueOperation and IssueSingleOperation interfaces in the STS provider framework. In addition to the properties that it inherits from AbstractOperation (detailed in the previous post), it has a single property that can be configured:

ClaimsManager claimsManager - An object that is used to handle claims. This will be covered in a future post.

Recall that AbstractOperation uses the RequestParser to parse a client request into TokenRequirements and KeyRequirements objects. TokenIssueOperation populates a TokenProviderParameters object with values extracted from the TokenRequirements and KeyRequirements objects. A number of different processing steps then occur before a TokenProvider implementation is used to retrieve the desired token, comprising of realm parsing, claims handling, and AppliesTo parsing.Claims handling will be discussed in the next article.

1.1) Realm Parsing

We have discussed how realms are used with TokenProviders to provide tokens, and also how they work with TokenValidators to validate a given token. However, we did not cover how realms are defined in the first place. Recall that the STSPropertiesMBean configuration object defined on AbstractOperation has a RealmParser property. The RealmParser is an interface which defines a pluggable way of defining a realm for the current request. It has a single method:

String parseRealm(WebServiceContext context) - Return the realm of the current request given a WebServiceContext object.

Therefore if you wish to issue tokens in multiple realms, it is necessary to create an implementation of the RequestParser which will return a realm String given a context object. For example, different realms could be returned based on the endpoint URL or a HTTP parameter. This realm will then get used to select a TokenProvider implementation to use to issue a token of the desired type. It will also be used for token validation in a similar way.

1.2) AppliesTo parsing

An AppliesTo element contains an address that refers to the recipient of the issued token. If an AppliesTo element was sent as part of the request then the CXF STS requires that it must be explicitly handled. This is done by the list of ServiceMBean objects that can be configured on AbstractOperation. The ServiceMBean interface represents a service, and has the following methods (amongst others):

boolean isAddressInEndpoints(String address) - Return true if the supplied address corresponds to a known address for this service.
void setEndpoints(List<String> endpoints) - Set the list of endpoint addresses that correspond to this service.

The STS ships with a single implementation of this interface, the StaticService. For the normal use-case of handling an AppliesTo element, the user creates a StaticService object and calls setEndpoints with a set of Strings that correspond to a list of regular expressions that match the allowable set of token recipients (by address). The TokenIssueOperation will extract the URL address from the EndpointReference child of the received AppliesTo element, and then iterate through the list of ServiceMBean objects and ask each one whether the given address is known to that ServiceMBean object. If an AppliesTo address is received, and no ServiceMBean is configured that can deal with that URL, then an exception is thrown.

The ServiceMBean also defines a number of optional configuration options, such as the default KeyType and TokenType Strings to use for that Service, if the client does not supply them. It also allows the user to set a custom EncryptionProperties object, which defines a set of acceptable encryption algorithms to use to encrypt issued tokens for that service.

2) Token creation and response

Once the TokenIssuerOperation has processed the client request, it iterates through the list of defined TokenProvider implementations to see if each "can handle" the desired token type in the configured realm (if any). If no TokenProvider is defined, or if no TokenProvider can handle the desired token type, then an exception is thrown. Otherwise, a token is created, and a response object is constructed containing the following items:

The context attribute (if any was specified).
The Token Type.
The requested token (possibly encrypted, depending on configuration).
A number of references to that token (can be disabled by configuration).
The received AppliesTo address (if any).
The RequestedProofToken (if a Computed Key Algorithm was used).
The Entropy generated by the STS (if any, can be encrypted).
The lifetime of the generated token.
The KeySize that was used (if any).

3) TokenIssueOperation Example

Finally, it's time to look at an example of how to spring-load the STS so that it can issue tokens. This particular example uses a security policy that requires a UsernameToken over the symmetric binding. As the STS is a web service, we first define an endpoint:


<jaxws:endpoint id="UTSTS"
    implementor="#utSTSProviderBean"
    address="http://.../SecurityTokenService/UT"
    wsdlLocation=".../ws-trust-1.4-service.wsdl"
    xmlns:ns1="http://docs.oasis-open.org/ws-sx/ws-trust/200512/"
    serviceName="ns1:SecurityTokenService"
    endpointName="ns1:UT_Port">
    <jaxws:properties>
        <entry key="ws-security.callback-handler" value="..."/>
        <entry key="ws-security.signature.properties" value="stsKeystore.properties"/>
    </jaxws:properties>
</jaxws:endpoint>

The jaxws:properties are required to parse the incoming message. The CallbackHandler is used to validate the UsernameToken and provide the password required to access the private key defined in the signature properties parameter. The "implementor" of the jaxws:endpoint is the SecurityTokenServiceProvider class defined in the STS provider framework:


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

This bean supports the Issue Operation via a TokenIssueOperation instance:


<bean id="utIssueDelegate"
    class="org.apache.cxf.sts.operation.TokenIssueOperation">
    <property name="tokenProviders" ref="utSamlTokenProvider"/>
    <property name="services" ref="utService"/>
    <property name="stsProperties" ref="utSTSProperties"/>
</bean>

This TokenIssueOperation instance has a single TokenProvider configured to issue SAML Tokens (with a default Subject and Attribute statement):


<bean id="utSamlTokenProvider"
    class="org.apache.cxf.sts.token.provider.SAMLTokenProvider">
</bean>

The TokenIssueOperation also refers to a single StaticService implementation, which in turn defines a single URL expression to use to compare any received AppliesTo addresses:


<bean id="utService"
    class="org.apache.cxf.sts.service.StaticService">
    <property name="endpoints" ref="utEndpoints"/>
</bean>


<util:list id="utEndpoints">
    <value>http://localhost:(\d)*/(doubleit|metrowsp)/services/doubleit(UT|.*symmetric.*|.*)</value>
</util:list>

Finally, the TokenIssueOperation is configured with a StaticSTSProperties object. This class contains properties that define what private key to use to sign issued SAML tokens, as well as the Issuer name to use in the generated token.


<bean id="utSTSProperties"
    class="org.apache.cxf.sts.StaticSTSProperties">
    <property name="signaturePropertiesFile" value="stsKeystore.properties"/>
    <property name="signatureUsername" value="mystskey"/>
    <property name="callbackHandlerClass" value="..."/>
    <property name="issuer" value="DoubleItSTSIssuer"/>
    ...
</bean>

Apache CXF STS documentation - part VIII

2011-11-08T09:29:00.000-08:00

Previous blog posts on the Apache CXF STS have focused on how tokens are provided, validated and canceled in the STS. These operations are (at least in theory) relatively independent of WS-Trust. For example, they could be used as an API to provide/validate/etc tokens. In the next couple of posts we will look at the bigger picture of how this internal token handling functionality works in the context of a client invocation. In this post we will cover some common functionality that is used by all of the WS-Trust operations in the STS implementation.

1) AbstractOperation

In the first post of this series of articles, the STS provider framework in Apache CXF was introduced. A number of interfaces were defined for each of the operations that can be invoked on the STS. Before looking at the implementations of these interfaces that ship with the STS, we will look a base class that all of the operations extend, namely the AbstractOperation class. This class defines a number of properties that are shared with any subclasses, and can be accessed via set/get methods:

STSPropertiesMBean stsProperties - A configuration MBean that holds the configuration for the STS as a whole, such as information about the private key to use to sign issued tokens, etc.
boolean encryptIssuedToken - Whether to encrypt an issued token or not. The default is false.
List<ServiceMBean> services - A list of ServiceMBean objects, which correspond to "known" services. This will be covered later.
List<TokenProvider> - A list of TokenProvider implementations to use to issue tokens.
boolean returnReferences - Whether to return SecurityTokenReference elements to the client or not, that point to the issued token. The default is true.
STSTokenStore tokenStore - A cache used to store/retrieve tokens.

Several of the properties refer to issuing tokens - this is because this functionality is shared between the issuing and validating operations. At least one TokenProvider implementation must be configured, if the STS is to support issuing a token. Some of these properties have been seen in previous posts, for example the STSTokenStore cache was covered in a previous blog post. This cache could be shared across a number of different operations, or else kept separate. AbstractOperation also contains some common functionality to parse requests, encrypt tokens, create references to return to the client, etc.

1.1) STSPropertiesMBean

The AbstractOperation object must be configured with an STSPropertiesMBean object. This is an interface that encapsulates some configuration common to a number of different operations of the STS:

void configureProperties() - load and process the properties
void setCallbackHandler(CallbackHandler callbackHandler) - Set a CallbackHandler object. This is used in the TokenProviders/TokenValidators to retrieve passwords for various purposes.
void setSignatureCrypto(Crypto signatureCrypto) - Set a WSS4J Crypto object to use to sign tokens, or validate signed requests, etc.
void setSignatureUsername(String signatureUsername) - Set the default signature username to use (e.g. corresponding to a keystore alias)
void setEncryptionCrypto(Crypto encryptionCrypto) - Set a WSS4J Crypto object to use to encrypt issued tokens.
void setEncryptionUsername(String encryptionUsername) - Set the default encryption username to use (e.g. corresponding to a keystore alias)
void setIssuer(String issuer) - Set the default issuer name of the STS
void setSignatureProperties(SignatureProperties signatureProperties) - Set the SignatureProperties object corresponding to the STS.
void setRealmParser(RealmParser realmParser) - Set the object used to define what realm a request is in. This will be covered later.
void setIdentityMapper(IdentityMapper identityMapper) - Set the object used to map identities across realms. This will be covered later.

The STS ships with a single implementation of the STSPropertiesMBean interface - StaticSTSProperties. This class has two additional methods:

void setSignaturePropertiesFile(String signaturePropertiesFile)
void setEncryptionPropertiesFile(String encryptionPropertiesFile)

If no Crypto objects are supplied to StaticSTSProperties, then it will try to locate a properties file using these values, and create a WSS4J Crypto object internally from the properties that are parsed.

1.2) SignatureProperties

A SignatureProperties object can be defined on the STSPropertiesMBean. Note that this is unrelated to the signaturePropertiesFile property of StaticSTSProperties. This class provides some configuration relating to the signing of an issued token, as well as symmetric key generation. It has the following properties:

boolean useKeyValue - Whether to use a KeyValue or not to refer to a certificate in a signature. The default is false.
long keySize - The (default) key size to use when generating a symmetric key. The default is 256 bits.
long minimumKeySize - The minimum key size to use when generating a symmetric key. The requestor can specify a KeySize value to use. The default is 128 bits.
long maximumKeySize - The maximum key size to use when generating a symmetric key. The requestor can specify a KeySize value to use. The default is 512 bits.

For example, when the client sends a "KeySize" element to the STS when requesting a SAML Token (and sending a SymmetricKey KeyType URI), the SAMLTokenProvider will check that the requested keysize falls in between the minimum and maximum key sizes defined above. If it does not, then the default key size is used.

2) Request Parsing

The first thing any of the AbstractOperation implementations do on receiving a request is to call some functionality in AbstractOperation to parse the request. This parsing is done by the RequestParser object, which iterates through the objects of the JAXB RequestSecurityTokenType. The request is parsed into two components, TokenRequirements and KeyRequirements, which are available on the RequestParser object and are subsequently passed to the desired TokenProvider/TokenValidator/etc objects.

2.1) TokenRequirements

The TokenRequirements class holds a set of properties that have been extracted and parsed by RequestParser. These properties loosely relate to the token itself, rather than anything to do with keys. The properties that can be set by RequestParser are:

String tokenType - The desired TokenType URI. This is required if a token is to be issued.
Element appliesTo - The AppliesTo element that was received in the request. This normally holds a URL that indicates who the recipient of the issued token will be.
String context - The context attribute of the request.
ReceivedToken validateTarget - This object holds the contents of a received "ValidateTarget" element, i.e. a token to validate.
ReceivedToken onBehalfOf - This object holds the contents of a received "OnBehalfOf" element.
ReceivedToken actAs - This object holds the contents of a received "ActAs" element.
ReceivedToken cancelTarget - This object holds the contents of a received "CancelTarget" element, i.e. a token to cancel.
Lifetime lifetime - The requested lifetime of the issued token. This just holds created and expires Strings, that are parsed from the request.
RequestClaimCollection claims - A collection of requested claims that are parsed from the request. This will be covered later.

The ReceivedToken class mentioned above parses a received token object, which can be a JAXBElement<?> or a DOM Element. If it is a JAXBElement then it must be either a UsernameToken, SecurityTokenReference, or BinarySecurityToken. If it is a reference to a security token in the security header of the request, then this token is retrieved and set as the ReceivedToken instead.

2.2) KeyRequirements

The KeyRequirements class holds a set of properties that have been extracted and parsed by RequestParser. These properties are anything to do with key handling or creation. The properties that can be set by RequestParser are:

String authenticationType - An optional authentication type URI. This is currently not used in the STS.
String keyType - The desired KeyType URI.
long keySize - The requested KeySize to use when generating symmetric keys.
String signatureAlgorithm - The requested signature algorithm to use when signing an issued token. This is currently not used in the STS.
String encryptionAlgorithm - The requested encryption algorithm to use when encrypting an issued token.
String c14nAlgorithm - The requested canonicalization algorithm to use when signing an issued token. This is currently not used in the STS.
String computedKeyAlgorithm - The computed key algorithm to use when creating a symmetric key.
String keywrapAlgorithm - The requested KeyWrap algorithm to use when encrypting a symmetric key.
X509Certificate certificate - A certificate that has been extracted from a "UseKey" element, for use in the SAML case when a PublicKey KeyType URI is specified.
Entropy entropy - This object holds entropy information extracted from the client request for use in generating a symmetric key. Only BinarySecret elements are currently supported.

2.3) SecondaryParameters

RequestParser also supports parsing a "SecondaryParameters" element that might be in the request. This could be extracted from the WSDL of a service provider that specifies an IssuedToken policy by the client and sent to the STS as part of the RequestSecurityToken request. Only KeySize, TokenType, KeyType and Claims child elements are currently parsed.

Apache CXF STS documentation - part VII

2011-11-07T09:00:00.000-08:00

Previous blog entries have covered TokenProviders and TokenValidators, used by the STS to provide and validate tokens respectively. The STS does not currently have any support for renewing tokens - although this may change in the future. The other STS operation on tokens that is of interest is the ability to cancel tokens that were issued by the STS. In this post I will detail an interface used to cancel tokens, as well as an implementation that ships with the STS.

1) The TokenCanceller interface

SecurityTokens are cancelled in the STS via the TokenCanceller interface. This interface is very similar to the TokenProvider and TokenValidator interfaces. It contains three methods:

void setVerifyProofOfPossession(boolean verifyProofOfPossession) - Whether to enable or disable proof-of-possession verification.
boolean canHandleToken(ReceivedToken cancelTarget) - Whether this TokenCanceller implementation can cancel the given token
TokenCancellerResponse cancelToken(TokenCancellerParameters tokenParameters) - Cancel a token using the given parameters

A client can cancel a security token via the STS by invoking the "cancel" operation. Assuming that the client request is authenticated and well-formed, the STS will iterate through a list of TokenCanceller implementations to see if they can "handle" the received token. If they can, then the implementation is used to cancel the received security token, and the cancellation result is returned to the client. The STS currently ships with a single TokenCanceller implementation, which can cancel SecurityContextTokens that were issued by the STS. Before we look at this implementation, let's look at the "cancelToken" operation in more detail. This method takes a TokenCancellerParameters instance, and returns a TokenCancellerResponse object.

2) TokenCancellerParameters and TokenCancellerResponse

The TokenCancellerParameters class is nothing more than a collection of configuration properties to use in cancelling the token, which are populated by the STS operations using information collated from the request, or static configuration, etc. The properties of the TokenCancellerParameters are:

STSPropertiesMBean stsProperties - A configuration MBean that holds the configuration for the STS as a whole.
Principal principal - The current client Principal object
WebServiceContext webServiceContext - The current web service context object. This allows access to the client request.
KeyRequirements keyRequirements - A set of configuration properties relating to keys. This will be covered later.
TokenRequirements tokenRequirements - A set of configuration properties relating to the token. This will be covered later.
STSTokenStore tokenStore - A cache used to retrieve tokens.

The "cancelToken" method returns an object of type TokenCancellerResponse. Similar to the TokenCancellerParameters object, this just holds a collection of objects that is parsed by the STS operation to construct a response to the client. It currently only has a single property:

boolean tokenCancelled - Whether the token was cancelled or not.

3) The SCTCanceller

The STS ships with a single implementation of the TokenCanceller interface, namely the SCTCanceller. The SCTCanceller is used to cancel a token known as a SecurityContextToken, that is defined in the WS-SecureConversation specification. The SCTProvider and the SCTValidator were covered previously. A SecurityContextToken essentially consists of a String Identifier which is associated with a particular secret key. The SCTCanceller can cancel a SecurityContextToken in either of the following namespaces:

http://schemas.xmlsoap.org/ws/2005/02/sc/sct
http://docs.oasis-open.org/ws-sx/ws-secureconversation/200512

Recall that the SCTValidator validates a received SecurityContextToken by checking to see whether it is stored in the cache. Therefore it is a requirement to configure a cache for the STS if you want to validate SecurityContextTokens. The same applies for the SCTCanceller. A received SecurityContextToken is successfully cancelled only if it is stored in the cache and is removed from the cache without any errors. This generally implies that the STS must have previously issued the SecurityContextToken and stored it in the cache, unless the STS is sharing a distributed cache with other STS instances.

3.1) Enforcing proof-of-possession

Recall that the TokenCanceller interface has a method "setVerifyProofOfPossession" which defines whether proof-of-possession is required or not to cancel a security token. The default value for the SCTCanceller is "true". This means that for the client to successfully cancel a SecurityContextToken it must prove to the STS that it knows the secret key associated with that SecurityContextToken. The client must do this by signing some portion of the request with the same secret key that the SCTCanceller retrieves from the security token stored in the cache.

Apache CXF STS documentation - part VI

2011-11-04T09:45:00.000-07:00

In the previous post, I covered the TokenValidator interface that is used by the CXF STS to validate tokens, and two implementations that ship with the STS to validate SecurityContextTokens and BinarySecurityTokens (X509 Certificates). In this post I will cover the other two TokenValidator implementations that ship with the STS, which can validate UsernameTokens and SAML Tokens (both 1.1 and 2.0).

1) The UsernameTokenValidator

The UsernameTokenValidator is used to validate WS-Security UsernameTokens. Two properties can be set directly on the UsernameTokenValidator:

void setValidator(Validator validator) - Set the WSS4J Validator instance to use to validate the received UsernameToken. The default is the UsernameTokenValidator (note that this is in WSS4J and not the same as the UsernameTokenValidator in the STS!).
void setUsernameTokenRealmCodec(UsernameTokenRealmCodec usernameTokenRealmCodec) - Set the UsernameTokenRealmCodec instance to use to return a realm from a validated token. This will be explained later.

The UsernameToken is first checked to make sure that it is well-formed. If it has no password element then it is rejected. If a cache is configured, then it sees if the UsernameToken has been previously stored in the cache (searching by wsu:Id). If it is, and if the retrieved SecurityToken has an "associated hash" corresponding to the hashcode of the received UsernameToken, then the received UsernameToken has already been validated, and no further validation is required. It is necessary to check the "associated hash" value, in case two different UsernameTokens are being compared that have the same wsu:Id. Note that the CXF STS does not have a UsernameTokenProvider as of yet, so for this use-case perhaps the cache is shared with a custom TokenProvider.

If the token is not stored in the cache, then the WSS4J Validator instance is used to validate the received UsernameToken. As stated above, the default implementation that is used is the UsernameTokenValidator in WSS4J. This implementation uses a CallbackHandler to supply a password to validate the UsernameToken. This CallbackHandler implementation is supplied by the STSPropertiesMBean object. WSS4J also ships with an implementation that validates a UsernameToken via a JAAS LoginModule, which can be plugged in to the STS UsernameTokenValidator. If validation is successful, then a principal is created from the received UsernameToken and set on the response.

2) Realms in the TokenValidators

Recall that the TokenValidator interface has a method that takes a realm parameter:

boolean canHandleToken(ReceivedToken validateTarget, String realm) - Whether this TokenValidator implementation can validate the given token in the given realm

How the STS knows what the desired realm is will be covered in a future post.
Realms are handled in a slightly different way in TokenValidators compared to TokenProviders. Recall that for TokenProviders, the implementation is essentially asked whether it can provide a token in a given realm. For the SCTProvider, the realm is ignored in this method. However, when creating a token, the SCTProvider will store the given realm as a property associated with that token in the cache. The SAMLTokenProvider checks to see if the given realm is null, and if it is not null then the realmMap *must* contain a key which matches the given realm.

There is a subtle distinction between the realm passed to "canHandleToken" for TokenValidators and the realm returned after a token is validated as part of the TokenValidatorResponse object. The realm passed to "canHandleToken" is the realm to validate the token in. So for example, you could have two TokenValidator instances registered to validate the same token, but in different realms. All of the TokenValidator implementations that ship with the STS ignore the realm as part of this method. However, the method signature gives the user the option to validate tokens in different realms in a more flexible manner.

The realm that is returned as part of the TokenValidatorResponse is the realm that the validated token is in (if any). This can be different to the realm the token was validated in. The X509TokenValidator ignores this parameter altogether. The SCTValidator checks to see whether the SecurityToken that was stored in the cache has a realm property, and if so sets this on the TokenValidatorResonse. The UsernameTokenValidator and SAMLTokenValidator handle realms in a more sophisticated manner. I will cover the UsernameTokenValidator here, and the SAMLTokenValidator later. Recall that the UsernameTokenValidator has the following method:

void setUsernameTokenRealmCodec(UsernameTokenRealmCodec usernameTokenRealmCodec) - Set the UsernameTokenRealmCodec instance to use to return a realm from a validated token.

The UsernameTokenRealmCodec has a single method:

String getRealmFromToken(UsernameToken usernameToken) - Get the realm associated with the UsernameToken parameter.

No UsernameTokenRealmCodec implementation is set by default on the UsernameTokenValidator, hence no realm is returned in TokenValidatorResponse. If an implemention is specified, then the UsernameTokenValidator will retrieve a realm from the UsernameTokenRealmCodec implementation corresponding to the validated UsernameToken. If a cache is configured, and the UsernameToken was already stored in the cache, then the realm is compared to the realm of the cached token, stored under the tag "org.apache.cxf.sts.token.realm". If they do not match then validation fails.

3) The SAMLTokenValidator

The SAMLTokenValidator is used to validate SAML (1.1 and 2.0) tokens. The following properties can be set directly on the SAMLTokenValidator:

void setValidator(Validator validator) - Set the WSS4J Validator instance to use to validate the received certificate. The default is SignatureTrustValidator.
void setSamlRealmCodec(SAMLRealmCodec samlRealmCodec) - Set the SAMLRealmCodec instance to use to return a realm from a validated token.
void setSubjectConstraints(List<String> subjectConstraints) - Set a list of Strings corresponding to regular expression constraints on the subject DN of a certificate that was used to sign an Assertion.

These methods are covered in more detail below. The Assertion is first checked to make sure that it is well-formed. If a cache is defined, then the signature value of the received assertion (if it is signed) is hashed and compared against the tokens in the cache (via getTokenByAssociatedHash()). If a match is found in the cache, then the Assertion is taken to be valid. If a match is not found, then the Assertion is validated.

3.1) Validating a received SAML Assertion

If the token is not stored in the cache then it must be validated. Firstly a check is performed to make sure that the Assertion is signed, if it is not then it is rejected. The signature of the Assertion is then validated using the Crypto object retrieved from the STSPropertiesMBean passed in the TokenValidatorParameters. Finally, trust is verified in the certificate/public-key used to sign the Assertion. This is done using the Validator object that can be configured via "setValidator". The default Validator is the WSS4J SignatureTrustValidator, which checks that the received certificate is known (or trusted) by the STS Crypto object.

Recall that a List of Strings can be set on the SAMLTokenValidator via the "setSubjectConstraints" method. These Strings correspond to regular expression constraints on the subject DN of a certificate that was used to sign an Assertion. This provides additional flexibility to validate a received SAML Assertion. For example, the Assertion could be signed by an entity that has a certificate issued by a particular CA, which in turn is trusted by the STS Crypto object. However, one might want to restrict the list of "valid" entities who can sign a SAML Assertion. This can be done by adding a list of regular expressions that match the Subject DN of all acceptable certificates that might be used to sign a valid SAML Assertion. This matching is done by the CertConstraintsParser.

3.2) Realm handling in the SAMLTokenValidator

Recall that the SAMLTokenValidator has the following method:

void setSamlRealmCodec(SAMLRealmCodec samlRealmCodec) - Set the SAMLRealmCodec instance to use to return a realm from a validated token.

The SAMLRealmCodec has a single method:

String getRealmFromToken(AssertionWrapper assertion) - Get the realm associated with the (SAML Assertion) parameter.

No SAMLRealmCodec implementation is set by default on the SAMLTokenValidator, hence no realm is returned in TokenValidatorResponse. If an implemention is specified, then the SAMLTokenValidator will retrieve a realm from theSAMLRealmCodec implementation corresponding to the validated Assertion. If a cache is configured, and the Assertion was already stored in the cache, then the realm is compared to the realm of the cached token, stored under the tag "org.apache.cxf.sts.token.realm". If they do not match then validation fails.

Apache CXF STS documentation - part V

2011-11-02T09:38:00.000-07:00

In the previous couple of posts (here and here) I detailed the TokenProvider interface, which is used to generate tokens in the STS, as well as two implementations that ship with the STS to generate SecurityContextTokens and SAML Tokens. In this post I will describe the interface that is used for validating tokens, as well as two implementations that ship with the STS, which are used to validate SecurityContextTokens, and (X.509) BinarySecurityTokens. In the next post, I will detail implementations which can validate a UsernameToken and a SAML Token.

1) The TokenValidator interface

SecurityTokens are validated in the STS via the TokenValidator interface. It is very similar to the TokenProvider interface (hence some duplication of documentation from previous blog entries on the TokenProvider). It has three methods:

boolean canHandleToken(ReceivedToken validateTarget) - Whether this TokenValidator implementation can validate the given token
boolean canHandleToken(ReceivedToken validateTarget, String realm) - Whether this TokenValidator implementation can validate the given token in the given realm
TokenValidatorResponse validateToken(TokenValidatorParameters tokenParameters) - Validate a token using the given parameters.

A client can validate a security token via the STS by invoking the "validate" operation. Assuming that the client request is authenticated and well-formed, the STS will iterate through a list of TokenValidator implementations to see if they can "handle" the received token. If they can, then the implementation is used to validate the received security token, and the validation result is returned to the client. The second "canHandleToken" method which also takes a "realm" parameter will be covered in a future post.

So to support the validation of a particular token type in an STS deployment, it is necessary to specify a TokenValidator implementation that can handle that token. The STS currently ships with four TokenValidator implementations, to validate SecurityContextTokens, SAML Assertions, UsernameTokens, and BinarySecurityTokens. Before we look at these implementations, let's take a look at the "validateToken" operation in more detail. This method takes a TokenValidatorParameters instance.

2) TokenValidatorParameters

The TokenValidatorParameters class is nothing more than a collection of configuration properties to use in validating the token, which are populated by the STS operations using information collated from the request, or static configuration, etc. The properties of the TokenValidatorParameters are:

STSPropertiesMBean stsProperties - A configuration MBean that holds the configuration for the STS as a whole.
Principal principal - The current client Principal object
WebServiceContext webServiceContext - The current web service context object. This allows access to the client request.
KeyRequirements keyRequirements - A set of configuration properties relating to keys. This will be covered later.
TokenRequirements tokenRequirements - A set of configuration properties relating to the token. This will be covered later.
STSTokenStore tokenStore - A cache used to retrieve tokens.
String realm - The realm to validate the token in (this should be the same as the realm passed to "canHandleToken"). This will be covered later.

If this looks complicated then remember that the STS will take care of populating all of these properties from the request and some additional configuration. You only need to worry about the TokenValidatorParameters object if you are creating your own TokenValidator implementation.

3) TokenValidatorResponse

The "validateToken" method returns an object of type TokenValidatorResponse. Similar to the TokenValidatorParameters object, this just holds a collection of objects that is parsed by the STS operation to construct a response to the client. The properties are:

boolean valid - Whether the token is valid or not.
Principal principal - A principal corresponding to the validated token.
Map<String, Object> additionalProperties - Any additional properties associated with the validated token.
String realm - The realm of the validated token.

4) The SCTValidator

Now that we've covered the TokenValidator interface, let's look at an implementation that is shipped with the STS. The SCTValidator is used to validate a token known as a SecurityContextToken, that is defined in the WS-SecureConversation specification. The SCTProvider was covered in a previous post. A SecurityContextToken essentially consists of a String Identifier which is associated with a particular secret key. If a service provider receives a SOAP message with a digital signature which refers to a SecurityContextToken in the KeyInfo of the signature, then the service provider knows that it must somehow obtain a secret key associated with that particular Identifier to verify the signature.

One way to do this would be if the service provider shares a (secured) distributed cache with an STS instance. An alternative solution would be for the service provider to send the SCT to an STS for validation, and to receive a SAML token in response with the embedded (encrypted) secret key. The SCTValidator can accommodate this latter scenario, albeit indirectly as will be explained shortly.

The SCTValidator can validate a SecurityContextToken in either of the following namespaces:

http://schemas.xmlsoap.org/ws/2005/02/sc/sct
http://docs.oasis-open.org/ws-sx/ws-secureconversation/200512

The SCTValidator validates a received SecurityContextToken by checking to see whether it is stored in the cache. Therefore it is a requirement to configure a cache for the STS if you want to validate SecurityContextTokens. If the SecurityContextToken is stored in the cache (for example, by the SCTProvider), then the received SecurityToken is taken to be valid. The secret associated with the SecurityContextToken is also retrieved from the cache, and set as an "additional property" in the TokenValidatorResponse using the key "sct-validator-secret". If the cached token has a stored principal, then this is also returned in the TokenValidatorResponse.

If you want to support the scenario of returning the secret key associated with the SecurityContextToken to the client (of the STS), then it is possible to do so via token transformation. This is where the client sends an additional Token Type (in this case for a SAML Token). After the token is validated, the SAMLTokenProvider is called with the additional properties map obtained from the SCTValidator. The SAMLTokenProvider then has access to the secret key via the "sct-validator-secret" tag, which it can insert into the Assertion using a custom AttributeProvider. Token Transformation will be covered in more detail in a future post.

5) The X509TokenValidator

Another TokenValidator implementation that ships with the STS is the X509TokenValidator. This class validates an X.509 V.3 certificate (received as a BinarySecurityToken). The BinarySecurityToken must use Base-64 encoding.

The received cert must be known (or trusted) by the STS crypto object, that is set on the STSPropertiesMBean object. The X509TokenValidator has a single property that can be configured:

void setValidator(Validator validator) - Set the WSS4J Validator instance to use to validate the received certificate. The default is SignatureTrustValidator.

No proof-of-possession is done with the received certificate. The subject principal of the certificate is set on the response, if validation is successful. Note that no caching is used in this TokenValidator implementation.

New Apache Santuario and CXF releases

2011-11-02T09:15:00.000-07:00

Apache Santuario 1.4.6 has been released - it is available for download here. This release fixes a thread safety issue with XML Signature, a bug fix for the Canonical XML 1.1 algorithm, as well as a number of other bug fixes. See the release notes for more information.

Also, Apache CXF 2.5.0 has been released. This release features a brand new STS implementation - something I have been blogging extensively about. See Dan Kulp's blog for more thoughts on this release.

Apache CXF STS documentation - part IV

2011-10-27T04:45:00.000-07:00

In the previous post I covered the TokenProvider interface, which is used to generate tokens in the STS, and an implementation that ships with the STS to generate SecurityContextTokens. In this post, I will cover the other TokenProvider implementation that ships with the STS, which issues SAML Tokens (both 1.1 and 2.0).

1) The SAMLTokenProvider

The SAMLTokenProvider can issue SAML 1.1 and SAML 2.0 tokens. To request a SAML 1.1 token, the client must use one of the following Token Types:

http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1
urn:oasis:names:tc:SAML:1.0:assertion

To request a SAML 2.0 token, the client must use one of the following Token Types:

http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0
urn:oasis:names:tc:SAML:2.0:assertion

The following properties can be configured on the SAMLTokenProvider directly:

List<AttributeStatementProvider> attributeStatementProviders - A list of objects that can add attribute statements to the token.
List<AuthenticationStatementProvider> authenticationStatementProviders - A list of objects that can add authentication statements to the token.
List<AuthDecisionStatementProvider> authDecisionStatementProviders - A list of objects that can add authorization decision statements to the token.
SubjectProvider subjectProvider - An object used to add a Subject to the token.
ConditionsProvider conditionsProvider - An object used to add a Conditions statement to the token.
boolean signToken - Whether to sign the token or not. The default is true.
Map<String, SAMLRealm> realmMap - A map of realms to SAMLRealm objects.

We will explain each of these properties in more detail in the next few sections.

2) Realms in the TokenProviders

As explained in the previous post, the TokenProvider interface has a method that takes a realm parameter:

boolean canHandleToken(String tokenType, String realm) - Whether this TokenProvider implementation can provide a token of the given type, in the given realm

In other words, the TokenProvider implementation is being asked whether it can supply a token corresponding to the Token Type in a particular realm. How the STS knows what the desired realm is will be covered in a future post. However, we will explain how the realm is handled by the TokenProviders here. The SCTProvider ignores the realm in the canHandleToken method. In other words, the SCTProvider can issue a SecurityContextToken in *any* realm. If a realm is passed through via the TokenProviderParameters when creating the token, the SCTProvider will cache the token with the associated realm as a property (this was explained in the previous post).

Unlike the SCTProvider, the SAMLTokenProvider does not ignore the realm parameter to the "canHandleToken" method. Recall that the SAMLTokenProvider has a property "Map<String, SAMLRealm> realmMap". The canHandleToken method checks to see if the given realm is null, and if it is not null then the realmMap *must* contain a key which matches the given realm. So if the STS implementation is designed to issue tokens in different realms, then the realmMap of the SAMLTokenProvider must contain the corresponding realms in the key-set of the map.

The realmMap property maps realm Strings to SAMLRealm objects. The SAMLRealm class contains the following properties:

String issuer - the Issuer String to use in this realm
String signatureAlias - the keystore alias to use to retrieve the private key the SAMLTokenProvider uses to sign the generated token

In other words, if the SAMLTokenProvider is "realm aware", then it can issue tokens with an issuer name and signing key specific to a given realm. If no realm is passed to the SAMLTokenProvider, then these properties are obtained from the "system wide" properties defined in the STSPropertiesMBean object passed as part of the TokenProviderParameters, which can be set via the following methods:

void setSignatureUsername(String signatureUsername)
void setIssuer(String issuer)

Two additional properties are required when signing SAML Tokens. A password is required to access the private key in the keystore, which is supplied by a CallbackHandler instance. A WSS4J "Crypto" instance is also required which controls access to the keystore. These are both set on the STSPropertiesMBean object via:

void setCallbackHandler(CallbackHandler callbackHandler)
void setSignatureCrypto(Crypto signatureCrypto)

Note that the signature of generated SAML Tokens can be disabled, by setting the "signToken" property of the SAMLTokenProvider to "false". As per the SCTProvider, the generated SAML tokens are stored in the cache with the associated realm stored as a property.

3) Populating SAML Tokens

In the previous section we covered how a generated SAML token is signed, how to configure the key used to sign the assertion, and how to set the Issuer of the Assertion. In this section we will describe how to populate the SAML Token itself. The SAMLTokenProvider is designed to be able to issue a wide range of SAML Tokens. It does this by re-using the SAML abstraction library that ships with Apache WSS4J, which defines a collection of beans that are configured and then assembled in a CallbackHandler to create a SAML assertion.

3.1) Configure a Conditions statement

The SAMLTokenProvider has a "ConditionsProvider conditionsProvider" property, which can be used to configure the generated Conditions statement which is added to the SAML Assertion. The ConditionsProvider has a method to return a ConditionsBean object, and a method to return a lifetime in seconds. The ConditionsBean holds properties such as the not-before and not-after dates, etc. The SAMLTokenProvider ships with a default ConditionsProvider implementation that is used to insert a Conditions statement in every SAML token that is generated. This implementation uses a default lifetime of 5 minutes, and set the Audience Restriction URI of the Conditions Statement to be the received "AppliesTo" address, which is obtained from the TokenProviderParameters object.

The DefaultConditionsProvider can be configured to change the lifetime of the issued token. If you want to remove the ConditionsProvider altogether from the generation assertion, or implement a custom Conditions statement, then you must implement an instance of the ConditionsProvider interface, and set it on the SAMLTokenProvider.

3.2) Configure a Subject

The SAMLTokenProvider has a "SubjectProvider subjectProvider" property, which can be used to configure the Subject of the generated token, regardless of the version of the token. The SubjectProvider interface defines a single method to return a SubjectBean, given the token provider parameters, the parent Document of the assertion, and a secret key to use (if any). The SubjectBean contains the Subject name, name-qualifier, confirmation method, and KeyInfo element, amongst other properties. The SAMLTokenProvider ships with a default SubjectProvider implementation that is used to insert a Subject into every SAML Token that is generated.

The DefaultSubjectProvider has a single configuration method to set the subject name qualifier. It creates a subject confirmation method by checking the received key type. The subject name is the name of the principal obtained from TokenProviderParameters. Finally, a KeyInfo element is set on the SubjectBean under the following conditions:

If a "SymmetricKey" Key Type algorithm is specified by the client, then the secret key passed through to the SubjectProvider is encrypted with the X509Certificate of the recipient, and added to the KeyInfo element. How the provider knows the public key of the recipient will be covered later.
If a "PublicKey" KeyType algorithm is specified by the client, the X509Certificate that is received as part of the "UseKey" request is inserted into the KeyInfo element of the Subject.

If a "Bearer" KeyType algorithm is specified by the client, then no KeyInfo element is added to the Subject. For the "SymmetricKey" Key Type case, the SAMLTokenProvider creates a secret key using a SymmetricKeyHandler instance. The SymmetricKeyHandler first checks the key size that is supplied as part of the KeyRequirements object, by checking that it fits in between a minimum and maximum key size that can be configured. It also checks any client entropy that is supplied, as well as the computed key algorithm. It then creates some entropy and a secret key.

To add a custom Subject element to an assertion, you must create your own SubjectProvider implementation, and set it on the SAMLTokenProvider.

3.3) Adding Attribute Statements

The SAMLTokenProvider has a "List<AttributeStatementProvider> attributeStatementProviders" property, which can be used to add AttributeStatments to the generated assertion. Each object in the list adds a single Attribute statement. The AttributeStatementProvider contains a single method to return an AttributeStatementBean given the TokenProviderParameters object. This contains a SubjectBean (for SAML 1.1 assertions), and a list of AttributeBeans. The AttributeBean object holds the attribute name/qualified-name/name-format, and a list of attribute values, amongst other properties.

If no statement provider is configured in the SAMLTokenProvider, then the DefaultAttributeStatementProvider is invoked to create an Attribute statement to add to the assertion. It creates a default "authenticated" attribute, and also creates separate Attributes for any "OnBehalfOf" or "ActAs" elements that were received in the request. If the received OnBehalfOf/ActAs element was a UsernameToken, then the username is added as an Attribute. If the received element was a SAML Assertion, then the subject name is added as an Attribute.

3.4) Adding Authentication Statements

The SAMLTokenProvider has a "List<AuthenticationStatementProvider> authenticationStatementProviders" property, which can be used to add AuthenticationStatements to the generated assertion. Each object in the list adds a single Authentication statement. The AuthenticationStatementProvider contains a single method to return an AuthenticationStatementBean given the TokenProviderParameters object. This contains a SubjectBean (for SAML 1.1 assertions), an authentication instant, authentication method, and other properties. No default implementation of the AuthenticationStatementProvider interface is provided in the STS, so if you want to issue Authentication Statements you will have to write your own.

3.5) Adding Authorization Decision Statements

The SAMLTokenProvider has a "List<AuthDecisionStatementProvider> authDecisionStatementProviders" property, which can be used to add AuthzDecisionStatements to the generated assertion. Each object in the list adds a single statement. The AuthDecisionStatementProvider contains a single method to return an AuthDecisionStatementBean given the TokenProviderParameters object. This contains a SubjectBean (for SAML 1.1 assertions), the decision (permit/indeterminate/deny), the resource URI, a list of ActionBeans, amongst other properties. No default implementation of the AuthDecisionStatementProvider interface is provided in the STS.

Note that for SAML 1.1 tokens, the Subject is embedded in one of the Statements. When creating a SAML 1.1 Assertion, if a given Authentication/Attribute/AuthzDecision statement does not have a subject, then the standalone Subject is inserted into the statement. Finally, once a SAML token has been created, it is stored in the cache (if one is configured), with a lifetime corresponding to that of the Conditions statement. A TokenProviderResponse object is created with the DOM representation of the SAML Token, the SAML Token ID, lifetime, entropy bytes, references, etc.

Apache CXF STS documentation - part III

2011-10-25T09:08:00.000-07:00

In the next couple of blog posts I will describe how to generate tokens in the new STS implementation shipped as part of Apache CXF 2.5. In this post I will detail the interface that is used for generating tokens, as well as an implementation to generate SecurityContextTokens that ships with the STS. In the next post, I will describe how to generate SAML tokens.

1) The TokenProvider interface

Security tokens are created in the STS via the TokenProvider interface. It has three methods:

boolean canHandleToken(String tokenType) - Whether this TokenProvider implementation can provide a token of the given type
boolean canHandleToken(String tokenType, String realm) - Whether this TokenProvider implementation can provide a token of the given type, in the given realm
TokenProviderResponse createToken(TokenProviderParameters tokenParameters) - Create a token using the given parameters

A client can request a security token from the STS by either invoking the "issue" operation and supplying a desired token type, or else calling the "validate" operation and passing a (different) token type (token transformation). Assuming that the client request is authenticated and well-formed, the STS will iterate through a list of TokenProvider implementations to see if they can "handle" the received token type. If they can, then the implementation is used to create a security token, which is returned to the client. The second "canHandleToken" method which also takes a "realm" parameter will be covered in a future post.

So to support the issuing of a particular token type in an STS deployment, it is necessary to specify a TokenProvider implementation that can handle that token type. The STS currently ships with two TokenProvider implementations, one for generating SecurityContextTokens, and one for generating SAML Assertions. Before we look at these two implementations, let's take a look at the "createToken" operation in more detail. This method takes a TokenProviderParameters instance.

2) TokenProviderParameters

The TokenProviderParameters class is nothing more than a collection of configuration properties to use in creating the token, which are populated by the STS operations using information collated from the request, or static configuration, etc. The properties of the TokenProviderParameters are:

STSPropertiesMBean stsProperties - A configuration MBean that holds the configuration for the STS as a whole, such as information about the private key to use to sign issued tokens, etc. This will be covered later.
EncryptionProperties encryptionProperties - A properties object that holds encryption information relevant to the intended recipient of the token. This will be covered later.
Principal principal - The current client Principal object. This can be used as the "subject" of the generated token.
WebServiceContext webServiceContext - The current web service context object. This allows access to the client request.
RequestClaimCollection requestedClaims - The requested claims in the token. This will be covered later.
KeyRequirements keyRequirements - A set of configuration properties relating to keys. This will be covered later.
TokenRequirements tokenRequirements - A set of configuration properties relating to the token. This will be covered later.
String appliesToAddress - The URL that corresponds to the intended recipient of the token
ClaimsManager claimsManager - An object that can manage claims. This will be covered later.
Map<String, Object> additionalProperties - Any additional (custom) properties that might be used by a TokenProvider implementation.
STSTokenStore tokenStore - A cache used to store tokens.
String realm - The realm to create the token in (this should be the same as the realm passed to "canHandleToken"). This will be covered later.

If this looks complicated then remember that the STS will take care of populating all of these properties from the request and some additional configuration. You only need to worry about the TokenProviderParameters object if you are creating your own TokenProvider implementation.

3) TokenProviderResponse

The "createToken" method returns an object of type TokenProviderResponse. Similar to the TokenProviderParameters object, this just holds a collection of objects that is parsed by the STS operation to construct a response to the client. The properties are:

Element token - The (DOM) token that was created by the TokenProvider.
String tokenId - The ID of the token
long lifetime - The lifetime of the token
byte[] entropy - Any entropy associated with the token
long keySize - The key size of a secret key associated with the token.
boolean computedKey - Whether a computed key algorithm was used in generating a secret key.
TokenReference attachedReference - An object which gives information how to refer to the token when it is "attached".
TokenReference unAttachedReference" - An object which gives information how to refer to the token when it is "unattached".

Most of these properties are optional as far as the STS operation is concerned, apart from the token and token ID. The TokenReference object contains information about how to refer to the token (direct reference vs. Key Identifier, etc.), that is used by the STS to generate the appropriate reference to return to the client.

4) The SCTProvider

Now that we've covered the TokenProvider interface, let's look at an implementation that is shipped with the STS. The SCTProvider is used to provide a token known as a SecurityContextToken, that is defined in the WS-SecureConversation specification. A SecurityContextToken essentially consists of a String Identifier which is associated with a particular secret key. If a service provider receives a SOAP message with a digital signature which refers to a SecurityContextToken in the KeyInfo of the signature, then the service provider knows that it must somehow obtain a secret key associated with that particular Identifier to verify the signature. How this is done is "out of band" (more on this later).

To request a SecurityContextToken, the client must use one of the following Token Types:

http://schemas.xmlsoap.org/ws/2005/02/sc/sct
http://docs.oasis-open.org/ws-sx/ws-secureconversation/200512

Two properties can be configured on the SCTProvider directly:

long lifetime - The lifetime of the generated SCT. The default is 5 minutes.
boolean returnEntropy - Whether to return any entropy bytes to the client or not. The default is true.

The SCTProvider generates a secret key using the KeyRequirements object that was supplied, and constructs a SecurityContextToken with a random Identifier. It creates a CXF SecurityToken object that wraps this information, and stores it in the supplied cache using the given lifetime. The SecurityContextToken element is then returned, along with the appropriate references, lifetime element, entropy, etc.

When requesting a token from an STS, the client will typically present some entropy along with a computed key algorithm. The STS will generate some entropy of its own, and combine it with the client entropy using the computed key algorithm to generate the secret key. Alternatively, the client will present no entropy, and the STS will supply all of the entropy. Any entropy the STS generates is then returned to the client, who can recreate the secret key using its own entropy, the STS entropy, and the computed key algorithm.

This secret key is then used for the SCT use-case to encrypt/sign some part of a message. The SecurityContextToken is placed in the security header of the message, and referred to in the KeyInfo element of the signed/encrypted structure. As noted earlier, the service provider must obtain somehow the secret key corresponding to the SecurityContextToken identifier. Perhaps the service provider shares a (secured) distributed cache with an STS instance. Or perhaps the service provider sends the SCT to an STS instance to "validate" it, and receives a SAML token in response with the embedded (encrypted) secret key.

5) Token caching in the TokenProvider

Finally, we will cover token caching in a TokenProvider implementation. The SCTProvider is essentially useless without a cache, as otherwise there is no way for a third-party to know the secret key corresponding to a SecurityContextToken. Any TokenProvider implementation can cache a generated token in the STSTokenStore object supplied as part of the TokenProviderParameters. This object simply wraps the TokenStore interface in the CXF WS-Security runtime, which itself contains basic methods for adding/removing/querying CXF SecurityToken objects.

The SCTProvider creates a SecurityToken with the ID of the SCT, the secret key associated with the SCT and the client principal. If a "realm" is passed through, then this is recorded as a property of the SecurityToken (keyed via STSConstants.TOKEN_REALM). Finally, the STS ships with two STSTokenStore implementations, an in-memory implementation based on eh-cache, and an implementation that uses Hazelcast.

Apache CXF STS documentation - part II

2011-10-21T09:22:00.000-07:00

In part I of the series of posts on the new Apache CXF STS implementation, I talked about what a Security Token Service can do, as well as the STS provider framework in CXF since the 2.4.0 release. In this part, I will leave the STS implementation to one side for the moment, and instead focus on how a client interacts with the STS in CXF.

A simple example of how a CXF client can obtain a security token from the STS is shown in the "basic" STS system test "IssueUnitTest". This test starts an instance of the new CXF STS and obtains a number of different security tokens, all done completely programmatically, i.e. with no spring configuration. The STS instance that is used for the test-cases is configured with a number of different endpoints that use different security bindings (defined in the wsdl of the STS). For the purposes of this test, the Transport binding is used:

<wsp:Policy wsu:Id="Transport_policy">
      <wsp:ExactlyOne>
         <wsp:All>
            <sp:TransportBinding
               xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
               <wsp:Policy>
                  <sp:TransportToken>
                     <wsp:Policy>
                        <sp:HttpsToken RequireClientCertificate="false"/>
                     </wsp:Policy>
                  </sp:TransportToken>
                  <sp:AlgorithmSuite>
                     <wsp:Policy>
                        <sp:Basic128 />
                     </wsp:Policy>
                  </sp:AlgorithmSuite>
                  <sp:Layout>
                     <wsp:Policy>
                        <sp:Lax />
                     </wsp:Policy>
                  </sp:Layout>
                  <sp:IncludeTimestamp />
               </wsp:Policy>
            </sp:TransportBinding>
            <sp:SignedSupportingTokens
               xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
               <wsp:Policy>
                  <sp:UsernameToken
                     sp:IncludeToken=".../AlwaysToRecipient">
                     <wsp:Policy>
                        <sp:WssUsernameToken10 />
                     </wsp:Policy>
                  </sp:UsernameToken>
               </wsp:Policy>
            </sp:SignedSupportingTokens>
            ...
         </wsp:All>
      </wsp:ExactlyOne>
   </wsp:Policy>

In other words, this security policy requires that a one-way TLS connection must be used to communicate with the STS, and that authentication is performed via a Username Token in the SOAP header.

The object that communicates with an STS in CXF is the STSClient. Typically, the user constructs an STSClient instance (normally via Spring), sets it with certain properties such as the WSDL location of the STS, what service/port to use, various crypto properties, etc, and then stores this object on the message context using the SecurityConstants tag "ws-security.sts.client". This object is then controlled by the IssuedTokenInterceptorProvider in the ws-security runtime in CXF. This interceptor provider is triggered by the "IssuedToken" policy assertion, which is typically in the WSDL of the service provider. This policy assertion informs the client that it must obtain a particular security token from an STS and include it in the service request. The IssuedTokenInterceptorProvider takes care of using the STSClient to get a Security Token from the STS, and handles how long the security token should be cached, etc.

An example of a simple IssuedToken policy that might appear in the WSDL of a service provider is as follows:

<sp:IssuedToken sp:IncludeToken=".../AlwaysToRecipient">
    <sp:RequestSecurityTokenTemplate>
        <t:TokenType>
            http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0
        </t:TokenType>
      <t:KeyType>
          http://docs.oasis-open.org/ws-sx/ws-trust/200512/Bearer
      </t:KeyType>
    </sp:RequestSecurityTokenTemplate>
...
</sp:IssuedToken>

This policy states that the client should include a SAML 2.0 Assertion of subject confirmation method "Bearer" in the request. The client must know how to communicate with an STS to obtain such a token. This is done by providing the STSClient object with the appropriate information.

We will come back to the IssuedTokenInterceptorProvider at a later date. The IssueUnitTest referred to above uses the STSClient programmatically to obtain a security token. Let's look at the "requestSecurityToken" method called by the tests. An STSClient is instantiated via the CXF bus, and the WSDL location of the STS, plus service and port names are configured:

STSClient stsClient = new STSClient(bus);
stsClient.setWsdlLocation("https://.../SecurityTokenService/Transport?wsdl");
stsClient.setServiceName("{...}SecurityTokenService");
stsClient.setEndpointName("{...}Transport_Port");

A map is then populated with various properties and set on the STSClient. It is keyed with a different number of SecurityConstants tags. A username is supplied for use as the "user" in the UsernameToken. A CallbackHandler class is supplied to get the password to use in the UsernameToken. Compliance of the Basic Security Profile 1.1 is turned off, this is to prevent CXF throwing an exception when receiving a non-spec compliant response from a non-CXF STS:

Map<String, Object> properties = new HashMap<String, Object>();
stsClient.setProperties(properties);
properties.put(SecurityConstants.USERNAME, "alice");
properties.put(
        SecurityConstants.CALLBACK_HANDLER,
        "org.apache.cxf.systest.sts.common.CommonCallbackHandler"
);
properties.put(SecurityConstants.IS_BSP_COMPLIANT, "false");

If the KeyType is a "PublicKey", then an X.509 Certificate is presented to the STS in the request to embed in the generated SAML Assertion. The X.509 Certificate is obtained from the keystore defined in "clientKeystore.properties", with the alias "myclientkey". Finally, the "useCertificateForConfirmationKeyInfo" property of the STSClient means that the entire certificate is to be included in the request, instead of a KeyValue (which is the default):

if (PUBLIC_KEY_KEYTYPE.equals(keyType)) {
        properties.put(SecurityConstants.STS_TOKEN_USERNAME, "myclientkey");
        properties.put(SecurityConstants.STS_TOKEN_PROPERTIES, "clientKeystore.properties");
        stsClient.setUseCertificateForConfirmationKeyInfo(true);
}

Finally, the token type is set on the STSClient (the type of token that is being requested), as well as the KeyType (specific to a SAML Assertion), and a security token is requested, passing the endpoint address which is sent to the STS in the "AppliesTo" element:

        stsClient.setTokenType(tokenType);
        stsClient.setKeyType(keyType);
        return stsClient.requestSecurityToken(endpointAddress);

The returned SecurityToken object contains the received token as a DOM element, the ID of the received token, any reference elements that were returned - which show how to reference the token, any secret associated with the token, and the lifetime of the token.

Apache CXF STS documentation - part I

2011-10-19T09:00:00.000-07:00

The forthcoming Apache CXF 2.5 release will have an STS (Security Token Service) implementation which has been donated by Talend. This is the first in a series of blog posts where I will be going into the STS implementation in detail. In this post I will be explaining what an STS is and talking about the STS provider framework in CXF.

1) What is a Security Token Service?

An informal description of a Security Token Service is that it is a web service that offers some or all of the following services (amongst others):

It can issue a Security Token of some sort based on presented or configured credentials.
It can say whether a given Security Token is valid or not
It can renew (extend the validity of) a given Security Token
It can cancel (remove the validity of) a given Security Token
It can transform a given Security Token into a Security Token of a different sort.

Offloading this functionality to another service greatly simplifies client and service provider functionality, as they can simply call the STS appropriately rather than have to figure out the security requirements themselves. For example, the WSDL of a service provider might state that a particular type of security token is required to access the service. A client of the service can ask an STS for a Security Token of that particular type, which is then sent to the service provider. The service provider could choose to validate the received token locally, or dispatch the token to an STS for validation. These are the two most common use-cases of an STS.

A client can communicate with the STS via a protocol defined in the WS-Trust specification. The SOAP Body of the request contains a "RequestSecurityToken" element that looks like:

<wst:RequestSecurityToken Context="..." xmlns:wst="...">
    <wst:TokenType>...</wst:TokenType>
    <wst:RequestType>...</wst:RequestType>
    <wst:SecondaryParameters>...</wst:SecondaryParameters>
    ...
</wst:RequestSecurityToken>

The Apache CXF STS implementation supports a wide range of parameters that are passed in the RequestSecurityToken element. The SOAP Body of the response from the STS will contain a "RequestSecurityTokenResponse(Collection)" element, e.g.:

<wst:RequestSecurityTokenResponseCollection xmlns:wst="...">
    <wst:RequestSecurityTokenResponse>
    ...
    </wst:RequestSecurityTokenResponse>
</wst:RequestSecurityTokenResponseCollection>

1.1 A sample request/response for issuing a Security Token

A sample client request is given here, where the client wants the STS to issue a SAML 2.0 token for the "http://cxf.apache.org:8080/service" service:

<wst:RequestSecurityToken Context="..." xmlns:wst="...">
    <wst:TokenType>
       http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0
    </wst:TokenType>
    <wst:RequestType>
        http://docs.oasis-open.org/ws-sx/ws-trust/200512/Issue
    </wst:RequestType>
    <wsp:AppliesTo>http://cxf.apache.org:8080/service</wsp:AppliesTo>
</wst:RequestSecurityToken>

The STS responds with:

<wst:RequestSecurityTokenResponseCollection xmlns:wst="...">
    <wst:RequestSecurityTokenResponse>
         <wst:TokenType>
         http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0
   </wst:TokenType>
         <wst:RequestedSecurityToken>
   <saml2:Assertion xmlns:saml2="..." ... />
         </wst:RequestedSecurityToken>
    </wst:RequestSecurityTokenResponse>
</wst:RequestSecurityTokenResponseCollection>

2) The STS provider framework in Apache CXF

The first support for an STS in Apache CXF appeared in the 2.4.0 release with the addition of an STS provider framework in the WS-Security module. This is essentially an API that can be used to create your own STS implementation. As the STS implementation shipped in CXF 2.5 is based on this provider framework, it makes sense to examine it in more detail.

The SEI (Service Endpoint Interface) is available here. It contains the following methods that are relevant to the STS features discussed above:

RequestSecurityTokenResponseCollectionType issue(RequestSecurityTokenType request) - to issue a security token
RequestSecurityTokenResponseType issueSingle( RequestSecurityTokenType request) - to issue a security token that is not contained in a "Collection" wrapper (for legacy applications).
RequestSecurityTokenResponseType cancel(RequestSecurityTokenType request) - to cancel a security token
RequestSecurityTokenResponseType validate(RequestSecurityTokenType request) - to validate a security token
RequestSecurityTokenResponseType renew(RequestSecurityTokenType request) - to renew a security token

The SEI implementation handles each request by delegating it to a particular operation, which is just an interface that must be implemented by the provider framework implementation. Finally, a JAX-WS provider is available, which dispatches a request to the appropriate operation.

Significant updates to the STS Provider framework after the CXF 2.4.0 release include support for SOAP 1.2, a major bug fix to support operations other than issue, better exception propagation, and adding support for the WS-Trust 1.4 schema. These features are all available in the Apache CXF 2.4.3 release onwards.

Using Kerberos with Web Services - part II

2011-10-11T09:03:00.000-07:00

This is the second of a two-part series on using Kerberos with Web Services, with Apache WSS4J and CXF. Part I showed how to set up a KDC distribution, and how to generate client and service principals to use in some CXF system tests. The system tests showed how to obtain a Kerberos token from a KDC, package it in a BinarySecurityToken, and send it to a service endpoint for validation. In other words, part I illustrated how to use Kerberos for client authentication in a web service setting.

This article builds on part I by showing how to use the secret key associated with a Kerberos Token to secure (sign and encrypt) the request. This functionality was added as part of WSS4J 1.6.3, and the related WS-SecurityPolicy functionality was released as part of CXF 2.4.3.

1) Setting up the Kerberos system tests in Apache CXF

If you have not done so already, follow the instructions in part I to install a Kerberos distribution and to generate client and service principals to run the CXF Kerberos system tests. The KerberosTokenTest in Apache CXF contains a number of different Kerberos tests. In this article we will examine the tests that involve obtaining a Kerberos Token, and using the associated secret key to secure some part of the request.

Firstly, make sure that the JDK has unlimited security policies installed, and then checkout the CXF trunk via:

svn co https://svn.apache.org/repos/asf/cxf/trunk/

Go into the "trunk" directory, and compile and install CXF via "mvn -Pfastinstall" (this will avoid running tests). Finally go into the WS-Security system tests in "systests/ws-security"

1.1) Installing a custom KerberosTokenDecoder

Once the client obtains an AP-REQ token from the KDC, the client also has easy access to the session key, which can be used to secure the request in some way. Unfortunately, there appears to be no easy way to obtain the session key on the receiving side. WSS4J does not support extracting a Kerberos session key on the receiving side to decrypt/verify a secured request out-of-the-box. Instead, a KerberosTokenDecoder interface is provided, which defines methods for setting the AP-REQ token and current Subject, and a method to then get a session key. An implementation must be set on the KerberosTokenValidator to obtain a session key to decrypt or verify a signed request.

To run the Kerberos system tests that require a secret key on the receiving side, download an implementation of the KerberosTokenValidator interface here, and copy it to "systests/ws-security/src/test/java/org/apache/cxf/systest/ws/kerberos/server". The implementation is based on code written by the Java Monkey, and uses internal sun APIs, and so can't be shipped in Apache CXF/WSS4J. Once this implementation has been copied into the ws-security module, then you must compile or run any tests with the "-Pnochecks" profile enabled, as otherwise the code fails checkstyle.

Open the server configuration file ("src/test/resources/org/apache/cxf/systest/ws/kerberos/server/server.xml"), and uncomment the "kerberosTicketDecoderImpl" bean, and the property of the "kerberosValidator" bean that refers to it:

<bean id="kerberosTicketDecoderImpl"   class="org.apache.cxf.systest.ws.kerberos.server.KerberosTokenDecoderImpl"/>

<bean id="kerberosValidator"
       class="org.apache.ws.security.validate.KerberosTokenValidator">
        <property name="contextName" value="bob"/>
        <property name="serviceName" value="bob@service.ws.apache.org"/>
        <property name="kerberosTokenDecoder" ref="kerberosTicketDecoderImpl"/>
</bean>

1.2) Running the tests

Open KerberosTokenTest.java and comment out the "@org.junit.Ignore" entries for the last four tests, "testKerberosOverTransportEndorsing", "testKerberosOverAsymmetricEndorsing", "testKerberosOverSymmetricProtection" and "testKerberosOverSymmetricDerivedProtection". Finally, run the tests via:

mvn -Pnochecks test -Dtest=KerberosTokenTest -Djava.security.auth.login.config=src/test/resources/kerberos.jaas

2) The tests in more detail

In this section, we'll look at the tests in more detail.

2.1) WS-SecurityPolicy configuration

The wsdl that defines the service endpoints contains WS-SecurityPolicy expressions that define the security requirements of the endpoints. The following security policies are used for the four tests defined above:

testKerberosOverTransportEndorsing: A (one-way) transport binding is defined, with a KerberosToken required as an EndorsingSupportingToken.
testKerberosOverAsymmetricEndorsing: An asymmetric binding is used, where a KerberosToken is required as an EndorsingSupportingToken.
testKerberosOverSymmetricProtection: A symmetric binding is used, where a KerberosToken is specified as a ProtectionToken of the binding.
testKerberosOverSymmetricDerivedProtection: The same as the previous test-case, except that any secret keys that are used must be derived.

The first two test-cases use an EndorsingSupportingToken, which means that the secret key associated with the KerberosToken is used to sign (endorse) some message part (the timestamp for the Transport binding). This illustrates proof-of-possession. For the latter two test-cases, the KerberosToken is defined as a ProtectionToken, meaning that the secret key is used to sign/encrypt the request (e.g. instead of using an X.509 Token to encrypt a session key).

2.2) Kerberos LoginModule configuration

Both the CXF client and service endpoint use JAAS to authenticate to the KDC. The JAAS file used as part of the system test is passed to the tests via the System property "java.security.auth.login.config". The client (alice) uses the following login module:

alice {
    com.sun.security.auth.module.Krb5LoginModule required
    refreshKrb5Config=true useKeyTab=true keyTab="/etc/alice.keytab"
    principal="alice";
};

and the service endpoint (bob) uses:

bob {
com.sun.security.auth.module.Krb5LoginModule required
refreshKrb5Config=true useKeyTab=true storeKey=true
keyTab="/etc/bob.keytab" principal="bob/service.ws.apache.org";
};

2.3) Service endpoint configuration

The service endpoints are spring-loaded. Each endpoint definition contains the JAX-WS property "ws-security.bst.validator" which is defined in SecurityConstants. WSS4J uses Validator implementations to perform validation on received security tokens. This particular property means that BinarySecurityTokens are to be validated by the given reference, e.g.:

<jaxws:endpoint ...>
    <jaxws:properties>
        <entry key="ws-security.bst.validator" value-ref="kerberosValidator"/>
    </jaxws:properties>
</jaxws:endpoint>

"kerberosValidator" is a KerberosTokenValidator instance given above. It requires a "contextName" property, which corresponds to the JAAS context name, as well as an optional "serviceName" property, and an optional "kerberosTokenDecoder" property to use to obtain a secret key. Combined with the JAAS properties file, this is all that is required for the service endpoint to validate a received Kerberos Token.

2.4 Client configuration

Finally, the client must contact a KDC and obtain a Kerberos Token, once it sees that the service endpoint has a security policy that requires a KerberosToken. The client configuration is available here. A sample configuration for the Kerberos Test case is as follows:

<jaxws:client name="{...}DoubleItKerberosTransportPort"
       createdFromAPI="true">
       <jaxws:properties>
           <entry key="ws-security.kerberos.client">
               <bean class="org.apache.cxf.ws.security.kerberos.KerberosClient">
                   <constructor-arg ref="cxf"/>
                   <property name="contextName" value="alice"/>
                   <property name="serviceName" value="bob@service.ws.apache.org"/>
               </bean>
           </entry>
       </jaxws:properties>
</jaxws:client>

The JAX-WS property "ws-security.kerberos.client" (again, defined in SecurityConstants) corresponds to a KerberosClient object. Similar to the KerberosTokenValidator on the receiving side, this is configured with a JAAS context Name and service Name.

Apache CXF STS articles

2011-10-11T06:21:00.000-07:00

Two of my colleagues have written excellent articles on the forthcoming STS (Security Token Service) implementation in Apache CXF, complete with sample projects. See here for the article from Oliver Wulff, and here for the article from Glen Mazza.

Using Kerberos with Web Services - part I

2011-10-10T09:00:00.000-07:00

This is the first of a two-part series on using Kerberos with Web Services, with Apache WSS4J and CXF. WSS4J 1.6.2 adds support for obtaining a Kerberos ticket from a KDC (Key Distribution Center) and converting it to a BinarySecurityToken to be inserted into the security header of a SOAP request. On the receiving side, support has been added to validate the received Kerberos ticket accordingly. CXF 2.4.2 extends the Kerberos functionality available in WSS4J 1.6.2 to add support for WS-SecurityPolicy. No support is available yet (as of CXF 2.4.2) to use a secret key to sign and encrypt message parts, this will be the subject of part II.

In this post we will talk about installing the MIT Kerberos distribution in Ubuntu, and creating the necessary credentials to run some tests. Then we will go into some system tests in CXF that show how a client can get a Kerberos AP-REQ ticket from a KDC and send it to a service provider, who then authenticates the ticket, all driven by some spring configuration and WS-SecurityPolicy.

1) Installing MIT Kerberos

1.1) Installing the product

In this section we cover how to install the MIT Kerberos distribution in Ubuntu. This is needed to run the CXF Kerberos system tests. See here for more information on using Kerberos on Ubuntu. Open a command prompt and type:

sudo apt-get install krb5-kdc krb5-admin-server

When the product is installing you'll be asked for the default Kerberos Version 5 realm. Enter:

WS.APACHE.ORG

You will then be prompted for the hostnames of Kerberos servers in the WS.APACHE.ORG Kerberos realm. As we are installing the KDC and running the tests on the same machine, we only need to enter "localhost". Similarly, enter "localhost" when prompted for the Administrative server for the Kerberos realm.

1.2) Modifying configuration

Once apt-get has finished, we need to modify the Kerberos configuration file ("sudo vi /etc/krb5.conf"):

Under the "[realms]" section, add a "default_domain" entry for ws.apache.org. The entire entry should look like:
WS.APACHE.ORG = {
             kdc = localhost
             admin_server = localhost
             default_domain = ws.apache.org
}
Under the "[domain_realm]" section, add the following:

ws.apache.org = WS.APACHE.ORG
.ws.apache.org = WS.APACHE.ORG

Finally, add a logging section:

[logging]

        kdc = FILE:/var/log/krb5kdc.log
        admin_server = FILE:/var/log/kadmin.log
        default = FILE:/var/log/krb5lib.log

1.3) Create principals

The next step is to create some principals. Create a master key via:

sudo kdb5_util create -s

The next step is to start kadmin locally via:

sudo kadmin.local

If you run "listprincs" at the prompt you should see the ticket-granting-ticket principal "krbtgt/WS.APACHE.ORG@WS.APACHE.ORG". We will add a client principal and service principal:

addprinc alice
addprinc bob/service.ws.apache.org

"quit" the kadmin prompt, and start the KDC with "sudo krb5kdc". If you see no error messages then everything should be working correctly. To test this try to get a ticket for "alice" via "kinit alice", entering the password given when creating the "alice" principal.

1.4) Create keytabs

To avoid having to enter passwords when running the tests, we will create Keytabs. Start kadmin.local again ("sudo kadmin.local"), and enter:

ktadd -k /etc/alice.keytab alice
ktadd -k /etc/bob.keytab bob/service.ws.apache.org

To check that the keytabs were create correctly, you can inspect them with klist, e.g. "sudo klist -k /etc/alice.keytab". Finally make sure the keytabs are readable via "sudo chmod og+r /etc/*.keytab" - obviously this is not secure, but it is sufficient for this test application.

2) Running the Kerberos system tests in Apache CXF

Now that we have installed Kerberos and created the relevant principals, we can run the Kerberos system tests in Apache CXF. These tests are @Ignore'd by default. The KerberosTokenTest contains a number of different Kerberos tests. In this article we will just examine the tests that involve obtaining a Kerberos Token, and not any of the tests that involve using the secret key associated with a Kerberos Token to secure some part of the request.

Firstly, make sure that the JDK has unlimited security policies installed, and then checkout the CXF trunk via:

svn co https://svn.apache.org/repos/asf/cxf/trunk/

Go into the "trunk" directory, and compile and install CXF via "mvn -Pfastinstall" (this will avoid running tests). Finally go into the WS-Security system tests in "systests/ws-security". Open KerberosTokenTest.java and comment out the "@org.junit.Ignore" entries for the first four tests, "testKerberosOverTransport", "testKerberosOverSymmetric", "testKerberosOverSymmetricSupporting" and "testKerberosOverAsymmetric". Finally, run the tests via:

mvn test -Dtest=KerberosTokenTest -Djava.security.auth.login.config=src/test/resources/kerberos.jaas

2.1) WS-SecurityPolicy configuration

The wsdl that defines the service endpoints contains WS-SecurityPolicy expressions that define the security requirements of the endpoints. The following security policies are used for the four tests defined above:

testKerberosOverTransport: A (one-way) transport binding is defined, with a KerberosToken required as a SupportingToken. Essentially, this means that the communication is secured with TLS, and authentication is handled by a Kerberos token.
testKerberosOverSymmetric: A symmetric binding is used, where a KerberosToken is required as a SignedSupportingToken.
testKerberosOverSymmetricSupporting: A symmetric binding is used, where a KerberosToken is required as a SupportingToken.
testKerberosOverAsymmetric: An asymmetric binding is used, where a Kerberos token is required as a SignedSupportingToken.

The WS-SecurityPolicy expression used for a KerberosToken is:

<sp:KerberosToken sp:IncludeToken=".../Once">
    <wsp:Policy>
        <sp:WssGssKerberosV5ApReqToken11/>
    </wsp:Policy>
</sp:KerberosToken>

This means that a GSS V5 AP-REQ Token is required "once", in other words the initial invocation between the client and service endpoint must contain a token of this type encoded as a BinarySecurityToken in the security header of the request.

2.2) Kerberos LoginModule configuration

Both the CXF client and service endpoint use JAAS to authenticate to the KDC. The JAAS file used as part of the system test is passed to the tests via the System property "java.security.auth.login.config". The client (alice) uses the following login module:

alice {
    com.sun.security.auth.module.Krb5LoginModule required
    refreshKrb5Config=true useKeyTab=true keyTab="/etc/alice.keytab"
    principal="alice";
};

and the service endpoint (bob) uses:

bob {
com.sun.security.auth.module.Krb5LoginModule required
refreshKrb5Config=true useKeyTab=true storeKey=true
keyTab="/etc/bob.keytab" principal="bob/service.ws.apache.org";
};

<jaxws:endpoint ...>
    <jaxws:properties>
        <entry key="ws-security.bst.validator" value-ref="kerberosValidator"/>
    </jaxws:properties>
</jaxws:endpoint>

"kerberosValidator" is defined as:

<bean id="kerberosValidator"
    class="org.apache.ws.security.validate.KerberosTokenValidator">
    <property name="contextName" value="bob"/>
    <property name="serviceName" value="bob@service.ws.apache.org"/>
</bean>

The KerberosTokenValidator class ships with Apache WSS4J. It requires a "contextName" property, which corresponds to the JAAS context name, as well as an optional "serviceName" property. Combined with the JAAS properties file, this is all that is required for the service endpoint to validate a received Kerberos Token.

2.4 Client configuration

Finally, the client must contact a KDC and obtain a Kerberos Token, once it sees that the service endpoint has a security policy that requires a KerberosToken. The client configuration is available here. A sample configuration for the Kerberos Test case is as follows:

<jaxws:client name="{...}DoubleItKerberosTransportPort"
       createdFromAPI="true">
       <jaxws:properties>
           <entry key="ws-security.kerberos.client">
               <bean class="org.apache.cxf.ws.security.kerberos.KerberosClient">
                   <constructor-arg ref="cxf"/>
                   <property name="contextName" value="alice"/>
                   <property name="serviceName" value="bob@service.ws.apache.org"/>
               </bean>
           </entry>
       </jaxws:properties>
</jaxws:client>

Improving decryption performance in Apache Santuario 1.5

2011-10-07T04:10:00.000-07:00

Andreas Veithen alerted me some months back to a performance problem in Apache Santuario when decrypting messages. The issue emerged when some profiling was done on Dennis Sosnoski's test-code for measuring WS-Security performance across different web services stacks (see the original article here).

The test scenario involves deploying an Apache CXF 2.4.2 endpoint in Tomcat and repeatedly testing the "signencr" invocation defined in the article (WS-Security signing of body and headers, with timestamp and encryption of body) using a CXF client. Two types of test-runs were executed, 1000 "large" messages at 0.2 density in one run, and 10000 "small" messages at 0.05 density in another. When doing some profiling using a sampling profiler on the client, it emerged that the time it took to deserialize a decrypted XML String into a DOM element was taking around 20% of the total execution time for all WS-Security processing!

The way the default deserializing algorithm works in Apache Santuario 1.4.x is to parse the decrypted XML String into a new Document object, which is then imported into the existing Document. As Apache Xerces defers the creation of Node objects, the import operation triggers the full expansion of the DOM tree.

There are a number of alternatives to using the DocumentBuilder/importNode approach used in Santuario 1.4.x. The first approach is to use a Transformer object to transform the Source (XML String) into a placeholder Node belonging to the existing Document. This approach avoids having to explicitly import the nodes back to the existing Document. The second approach, is to use the streaming API available in the JDK 1.6 (not an option for Santuario 1.5 which must compile against the JDK 1.5).

Here are some (ad-hoc) test results. The first results show the total time for each test-run using both algorithms:

Large Messages:

Document Serializer: 119.46s
Transform Serializer: 115.68s

Small Messages:

Document Serializer: 222.32s
Transform Serializer: 216.76s

The next results show the time spent in the Serializer.deserialize() operation as a percentage of the total WS-Security processing time:

Large Messages:

Document Serializer: 19.92%
Transform Serializer: 18.04%

Small Messages:

Document Serializer: 24.54%
Transform Serializer: 18.36%

The Serializer interface is now public, and a different implementation can be set on XMLCipher. Two implementations are provided in the code, DocumentSerializer (the default algorithm) and TransformSerializer. If anyone is interested in running experiments of their own, the StreamSerializer algorithm is available here. The TransformSerializer implementation is not the default as it requires Xalan to work properly, and as this library is optional in Santuario 1.5.

Do you have any suggestions on how this could be improved further? Clearly, the time it takes to deserialize a decrypted XML String into a DOM node still takes far longer than it should. A fully StAX approach for XML Security would surely offer much improved performance - this is under development and planned for next year.

Apache WSS4J 1.6.3 released

2011-10-04T05:39:00.000-07:00

Apache WSS4J 1.6.3 has been released. It can be downloaded here and the issues fixed are listed in the WSS4J JIRA.

Probably the most significant part of this release is that WSS4J now fully supports the Kerberos Token Profile 1.1. In the previous release, support was added to retrieve a Kerberos token from a KDC, and insert it into the security header of a request, and then validate it accordingly on the receiving side. In WSS4J 1.6.3, support has been added to use the secret key associated with the Kerberos token to sign and encrypt the request, and to verify and decrypt on the receiving side. I am planning on writing a series of blog posts soon about how to use Kerberos with WSS4J and CXF. The forthcoming Apache CXF 2.4.3 release will have full WS-SecurityPolicy support for working with Kerberos, based on the work done in WSS4J 1.6.3.

In addition to the Kerberos work, WSS4J 1.6.3 features an upgraded Opensaml dependency, as well as several bug fixes.

Talend donates Security Token Service (STS) to Apache CXF

2011-09-23T07:31:00.000-07:00

I am pleased to announce that Talend has donated a Security Token Service (STS) implementation to Apache CXF, which will be part of the forthcoming 2.5 release. Since the 2.4.0 release, CXF ships with an STS framework (in the ws-security module), as well as a simple implementation of the framework in the examples. The STS that Talend has donated to the community is a sophisticated implementation of the STS framework that builds on top of CXF's existing mature security functionality.

In future blog posts I will document the features of the STS and how to configure it, as well as walk through some system tests. Here are some of the features and standards that the new STS supports:

WS-Trust 1.3/1.4
WS-SecurityPolicy1.3
Authentication Mechanisms for a RST:UsernameToken, SAML token (1.1/2.0), KerberosToken, X.509 Token.
Security Binding supported: Symmetric,Asymmetric, Transport
Supports WS-Trust Issue/Validate and Cancel binding
Can issue the following tokens:SAML 1.1/2.0Holder-Of-Key/Bearer, SecurityContextTokens, Custom Tokens.
Issued token can be encrypted
Validate binding supports issuing a new token (token transformation).
Custom Validators can be implemented
Creation of SAML tokens can be customized.
Advanced RST elements:KeyType (Public, Symmetric, Bearer), Entropy (Symmetric, Public) , OnBehalfOf, ActAs, Claims, SecondaryParameters
Pluggable claims handling and management

Specifying custom AlgorithmSuite policies in Apache CXF 2.4.3

2011-09-19T03:01:00.000-07:00

When specifying a security binding via WS-SecurityPolicy, it is possible to define the algorithm suite via the "sp:AlgorithmSuite" policy. WS-SecurityPolicy defines a number of standard AlgorithmSuite policies, which control various security properties like the maximum and minimum Symmetric and Asymmetric key lengths, the encryption/signature/digest algorithms to use, etc. An example policy is given below. For this policy, the minimum symmetric key length is 256 bits, and the encryption algorithm is AES256:

<sp:AlgorithmSuite>
    <wsp:Policy>
        <sp:Basic256 />
    </wsp:Policy>
</sp:AlgorithmSuite>

There are certain scenarios where a user might want to use a non-standard AlgorithmSuite. For example, the minimum Asymmetric Key Length for all standard AlgorithmSuites is 1024 bits. This requires that the JDK has unrestricted security policies installed. If it is not possible to install unresticted security policies, a user might decide that using 512 bits RSA keys is sufficient (this is not recommended).

Apache CXF 2.4.3 provides support for specifying custom algorithm suites. A new interface is defined to create an AlgorithmSuite object given a policy, with a default implementation that supports the standard AlgorithmSuite policies. It is possible to create a new implementation of the AlgorithmSuiteLoader interface, and install it as a bus extension. For an example, there is a CXF system test that allows 512 bit asymmetric keys, with custom AlgorithmSuiteLoader and AlgorithmSuite implementations. The custom AlgorithmSuiteLoader implementation is spring-loaded, and registers itself as a bus extension.

SAML SecurityPolicy enforcement in CXF 2.4.2

2011-09-12T05:44:00.000-07:00

Apache CXF 2.4.2 was released recently. In this blog post I want to delve into how CXF 2.4.2 enforces WS-SecurityPolicy expressions relating to SAML Assertions on the inbound side.

There are two policy expressions relating to SAML Assertions, the SamlToken and IssuedToken policy assertions. On the outbound side, the SamlToken expression will trigger a CallbackHandler to obtain a SAML Assertion to insert into the outbound security header, and the IssuedToken expression will use the STSClient to obtain a SAML Assertion from a Security Token Service (STS).

On the inbound side, any SAML Assertion received as part of the security header will be parsed initially by WSS4J. If the assertion is signed, then the signature is verified. If the confirmation method of the Subject of the Assertion is "holder-of-key", then WSS4J will parse the Subject KeyInfo and extract whatever credentials it can find, i.e. secret key or an X509Certificate. If no credential is found (or understood), then the default behaviour is to throw an exception. If the confirmation method is "holder-of-key", then the default behaviour (which is configurable) is to enforce that the Assertion is signed. Finally, WSS4J verifies trust in a certificate that was used to sign the assertion.

After WSS4J is done with validating a received SAML Assertion, CXF does some additional validation according to the configured security policy. For more information on any of the following terms (holder-of-key, sender-vouches, etc.), please consult the SAML Token Profile 1.1 specification.

1) SamlToken policy

If a SamlToken policy is used, the version of the received Assertion (1.1 or 2.0) is checked against the policy, e.g. if <sp:WssSamlV20Token11 /> is configured in the SAMLToken policy then the received Assertion must be a SAML 2.0 Assertion. Two checks are then done on the received Assertion, depending on what the subject confirmation method is.

Holder-of-key: If the subject confirmation method is "holder-of-key", there must be some proof-of-possession of the key associated with the subject of the assertion. CXF will enforce that either the key was used to sign some portion of the SOAP request, or alternatively the subject credential of the SAML Assertion must match a client certificate credential when 2-way TLS is used.
Sender-Vouches: If the subject confirmation method is "sender-vouches", then CXF will enforce that the SAML Assertion and SOAP Body are signed by the same signature. Alternatively, it will check that 2-way TLS is used.

2) IssuedToken Policy

If an IssuedToken policy is used, then the receiver is expecting to get a SAML Assertion that is issued by a third-party security service. If the subject confirmation method of the Assertion is "holder-of-key", then it does the same check as described above for a SamlToken policy. Additionally, if a "<sp:RequestSecurityTokenTemplate..../>" policy is configured, it will attempt to match the received Assertion against the RSTTemplate parameters:

TokenType: If a TokenType parameter is specified in the template, it will match this against the version of the received Assertion. For example, if the TokenType is "http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1", then the Assertion must be a SAML 1.1 Assertion.
KeyType: If a KeyType parameter is specified in the template which ends with "SymmetricKey", then the subject of the Assertion must contain a secret key. If the KeyType parameter ends with "PublicKey", then the Subject must contain a Certificate or PublicKey.

Here is an example of a RequestSecurityTokenTemplate:

<sp:RequestSecurityTokenTemplate>
    <t:TokenType>
      http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile1.1#SAMLV1.1
   </t:TokenType>
   <t:KeyType>
     http://docs.oasis-open.org/ws-sx/ws-trust/200512/PublicKey
   </t:KeyType>
</sp:RequestSecurityTokenTemplate>

Issuer or IssuerName policies are not yet enforced, this will probably be done in a future version of CXF.

Apache WSS4J 1.5.12 and 1.6.2 released

2011-08-18T06:21:00.000-07:00

Apache WSS4J 1.5.12 and 1.6.2 have been released.

WSS4J 1.5.12 is a bug-fix release, which fixes some problems relating to future-dated Timestamps, fixes a bug with deriving keys from UsernameTokens, and fixes a concurrency issue with EnvelopeIdResolver, amongst other things.

WSS4J 1.6.2 contains some enhancements for SAML Token creation, fixes a bug with deriving keys from UsernameTokens, adds initial support for the Kerberos Token Profile 1.1, and fixes some problems relating to signature verification in certain containers.

SAML token creation in Apache WSS4J 1.6

2011-08-16T11:10:00.000-07:00

WSS4J 1.6 uses Opensaml2 to create and parse SAML Assertions. WSS4J ships with a library that wraps the Opensaml API to greatly simplify the process of creating a SAML Assertion. The user implements a CallbackHandler instance which must be able to handle a WSS4J SAMLCallback object. and set certain properties on this object. WSS4J then parses the properties that were set on the object and creates a SAML Assertion accordingly. In this blog post we will examine the process of creating a SAML Assertion by populating a SAMLCallback object in more detail.

1) Obtain a SAMLCallback object

First off, a SAMLCallback object must be obtained in the CallbackHandler implementation, e.g.:

if (callbacks[i] instanceof SAMLCallback) {
SAMLCallback callback = (SAMLCallback) callbacks[i];
....
}

2) Set the SAML Version

The first thing to do is to set the desired SAML Version of the Assertion you want to create on the SAMLCallback object, e.g.:

callback.setSamlVersion(SAMLVersion.VERSION_11);

This method takes an org.opensaml.common.SAMLVersion object. For normal purposes, it will be one of the following:

SAMLVersion.VERSION_11
SAMLVersion.VERSION_20

The default value in SAMLCallback is VERSION_11.

3) Set the Issuer

The next thing to do is to set the issuer (String) name of the token, e.g.:

callback.setIssuer("sts");

4) Set the Subject

The next thing to do is to set the Subject of the Assertion. WSS4J defines a SubjectBean which encapsulates a SAML Subject. The Subject Name, NameQualifier, NameIDFormat and ConfirmationMethod Strings can be set on the SubjectBean instance. The NameIDFormat and ConfirmationMethod values that can be set are largely defined in the SAML1Constants and SAML2Constants classes. The default value for the SubjectBean NameIDFormat is SAML1Constants.NAMEID_FORMAT_UNSPECIFIED. Both constants classes contain the following values that can be used for the ConfirmationMethod value:

SAML[1|2]Constants.CONF_BEARER
SAML[1|2]Constants.CONF_HOLDER_KEY
SAML[1|2]Constants.CONF_SENDER_VOUCHES

In addition to this, WSS4J defines a KeyInfoBean that can be set on the SubjectBean, which represents a KeyInfo structure that will be embedded in a SAML Subject. There are a number of different ways to set the KeyInfo value:

A DOM element can be defined for a pre-existing KeyInfo element
A PublicKey object can be used
An X.509 Certificate can be used

For the latter two cases, the KeyInfoBean contains a CERT_IDENTIFIER enum which defines how the PublicKey or X.509 Certificate will be output. The following values can be configured:

X509_CERT: An X509Certificate element will be output
X509_ISSUER_SERIAL: An X509 IssuerSerial element will be output
KEY_VALUE: A KeyValue element will be output

The default value in the KeyInfoBean is X509_CERT. Here is a sample that shows how to create a SubjectBean:

SubjectBean subjectBean = new SubjectBean();
subjectBean.setSubjectName("uid=joe");
subjectBean.setSubjectNameQualifier("apache.org");
subjectBean.setSubjectConfirmationMethod(
SAML1Constants.CONF_SENDER_VOUCHES
);
KeyInfoBean keyInfo = new KeyInfoBean();
keyInfo.setCertificate(cert);
subjectBean.setKeyInfo(keyInfo);

Finally, it remains to store the SubjectBean instance in the SAMLCallback object. A SAML 2.0 Assertion contains a single Subject, and so for this case the SubjectBean instance can be set directly on the SAMLCallback, e.g.:

callback.setSubject(subjectBean);

For a SAML 1.1 Assertion, the Subject can be in a SubjectStatement (in which case it can be set directly on the SAMLCallback), or it can be embedded in one of the other statements which we will cover next.

5) Create and set a Statement

WSS4J contains a number of beans to create Statements for SAML Assertions, that can be set on a SAMLCallback object. They can be used in either SAML 1.1 or SAML 2.0 Assertions, with the caveat that SubjectBean instances are not used with statements in SAML 2.0.

a) Attribute Statements

WSS4J contains an AttributeStatementBean for creating Attribute statements. This contains a SubjectBean (for the SAML 1.1 case), and a list of AttributeBean objects. An attribute simple name, qualified name, and name format Strings can be set on the AttributeBean, as well as a list of attribute value Strings. Here is an example of creating and adding an AttributeStatement to a SAMLCallback object:

AttributeStatementBean attrBean = new AttributeStatementBean();
attrBean.setSubject(subjectBean);
AttributeBean attributeBean = new AttributeBean();
attributeBean.setSimpleName("role");
attributeBean.setAttributeValues(Collections.singletonList("user"));
attrBean.setSamlAttributes(Collections.singletonList(attributeBean));
callback.setAttributeStatementData(Collections.singletonList(attrBean));

b) Authentication Statements

WSS4J contains an AuthenticationStatementBean for creating Authentication statements. For SAML 1.1 a SubjectBean instance can be set on this object. In addition to this, an authentication instant and authentication method can be set, as well as a SubjectLocalityBean object and a session index String. Various authentication method Strings are defined in the SAML1Constants and SAML2Constants given above. Here is an example:

AuthenticationStatementBean authBean = new AuthenticationStatementBean();
authBean.setSubject(subjectBean);
SubjectLocalityBean subjectLocality = new SubjectLocalityBean();
subjectLocality.setIpAddress(subjectLocalityIpAddress);
subjectLocality.setDnsAddress(subjectLocalityDnsAddress);
authBean.setSubjectLocality(subjectLocality);
authBean.setAuthenticationMethod("Password"); callback.setAuthenticationStatementData(Collections.singletonList(authBean));

c) Authorization Decision Statements

WSS4J contains an AuthDecisionStatementBean for creating Authorization Decision Statements. For SAML 1.1 a SubjectBean instance can be set on this object. A Decision enum can be set (PERMIT, INDETERMINATE, DENY), as well as a resource String, evidence Object, and a list of ActionBeans, which in turn contain an action namespace and action contents. Here is an example:

AuthDecisionStatementBean authzBean = new AuthDecisionStatementBean();
authzBean.setSubject(subjectBean);
ActionBean actionBean = new ActionBean();
actionBean.setContents("Read");
authzBean.setActions(Collections.singletonList(actionBean));
authzBean.setResource("endpoint");
authzBean.setDecision(AuthDecisionStatementBean.Decision.PERMIT);
authzBean.setResource(resource); callback.setAuthDecisionStatementData(Collections.singletonList(authzBean));

6) Create a Conditions object

Finally, a ConditionsBean object can be used to specify a set of Conditions on the SAML Assertion. This is optional, as by default a Conditions element will be generated with a NotBefore value of the present instant and a NotOnOrAfter value corresponding to 5 minutes into the future. This can be changed by creating a ConditionsBean and specifying either "notBefore" and "notAfter" dates, or else a token period in minutes in which the token is valid. It is also possible to specify an audience restriction URI on the ConditionsBean object. Here is an example:

ConditionsBean conditions = new ConditionsBean();
conditions.setTokenPeriodMinutes(10);
conditions.setAudienceURI("http://ws.apache.org/wss4j");
callback.setConditions(conditionsBean);

For some examples of CallbackHandlers used to create SAML Assertions, check out the following CallbackHandlers used in the WSS4J unit tests - SAML1AuthnHOKHandler, SAML1CallbackHandler and SAML2CallbackHandler.

WS-Trust 1.4 support in CXF

2011-08-15T08:43:00.000-07:00

Apache CXF has had support for sending a WS-Trust 1.4 ActAs element as part of a RequestSecurityToken call to a Security Token Service (STS) since the 2.2.10 release. To quote from the WS-Trust 1.4 specification:

/wst:RequestSecurityToken/wst:ActAs

This OTPIONAL (sic) element indicates that the requested token is expected to contain information about the identity represented by the content of this element and the token requestor intends to use the returned token to act as this identity. The identity that the requestor wants to act-as is specified by placing a security token or <wsse:SecurityTokenReference> element within the <wst:ActAs> element.

The object to be placed in an ActAs element can be set by the SecurityConstants tag "STS_TOKEN_ACT_AS" on the Message properties. Prior to Apache CXF 2.4.1 the ActAs object could either be an XML String or else a DOM Element. See the following CXF wiki page for more information.

Several enhancements were made in CXF 2.4.1 as part of this JIRA. First of all, support was added for OnBehalfOf. To quote from the spec again:

/wst:RequestSecurityToken/wst:OnBehalfOf

This OPTIONAL element indicates that the requestor is making the request on behalf of another. The identity on whose behalf the request is being made is specified by placing a security token, <wsse:SecurityTokenReference> element, or <wsa:EndpointReference> element within the <wst:OnBehalfOf> element. The requestor MAY provide proof of possession of the key associated with the OnBehalfOf identity by including a signature in the RST security header generated using the OnBehalfOf token that signs the primary signature of the RST (i.e. endorsing supporting token concept from WS-SecurityPolicy). Additional signed supporting tokens describing the OnBehalfOf context MAY also be included within the RST security header.

The object to be placed in an OnBehalfOf element can be set by the SecurityConstants tag "STS_TOKEN_ON_BEHALF_OF" on the Message properties. Similar to ActAs, this object can be an XML String or a DOM Element. In addition to this, the object for both ActAs and OnBehalfOf can now be a CallbackHandler instance. The CallbackHandler implementation must be able to process a DelegationCallback object, which has access to the current CXF Message, and returns a DOM Element to the STSClient for insertion into either ActAs or OnBehalfOf.

Two sample CallbackHandler implementations are shipped with CXF 2.4.1 that can be used for either OnBehalfOf or ActAs. The ReceivedTokenCallbackHandler obtains the previously received message from the current message property of the DelegationCallback object, and extracts a token that has been received in that message (SAML Token/UsernameToken/BinarySecurityToken). This token is then used as the delegation token. This CallbackHandler implementation is useful as part of an WS-Trust intermediary scenario. Secondly, the WSSUsernameCallbackHandler obtains a username via the jax-ws property "ws-security.username" (SecurityConstants.USERNAME), and creates a wsse:UsernameToken (with no password) to be used as the delegation token.

Custom token validation in Apache CXF 2.4

2011-06-28T06:37:00.000-07:00

A previous blog post has covered validators in Apache WSS4J 1.6, why they were introduced, what default implementations ship with WSS4J, etc. It ends with a paragraph on how to use a custom Validator implementation with Apache CXF 2.4. This post expands further on this topic.

1) Use-cases for custom Token Validation

Let's consider first of all the use-cases for specifying a custom Validator implementation in CXF. When a security header is being processed by WSS4J, it delegates each security token to a Processor implementation, depending on the QName of the token. In WSS4J 1.6, Processors do not do any validation of extracted credentials from a token, they merely process it, make sure it meets basic requirements, etc. Validation is delegated to a Validator interface which is associated with that Processor implementation.

However, there are many possible use-cases where a user may wish to replace or remove or extend the default validation behaviour associated with a particular security token. Some examples include:

Validating a UsernameToken, where the CallbackHandler implementation does not have access to the password.
Validating a BinarySecurityToken of some custom type.
Validating the attributes of a received SAML Assertion
Validating a Timestamp in a more tolerant manner than the default.
Dispatching a received security token to a third-party security service for validation/authentication.

2) Configuring custom Validators in CXF

The CXF SecurityConstants class (javadoc) defines some configuration items to override the default validators used to validate a received security token. The values associated with each configuration option must correspond to an implementation of the Validator interface. The configuration tags are:

"ws-security.ut.validator" - Override UsernameToken validation.
"ws-security.saml1.validator" - Override SAML1 token validation.
"ws-security.saml2.validator" - Override SAML2 token validation.
"ws-security.timestamp.validator" - Override Timestamp validation.
"ws-security.signature.validator" - Override trust verification on a signature
"ws-security.bst.validator" - Override BinarySecurityToken validation.

To disable the validation of a particular token, specify the NoOpValidator as the value of the configuration tag corresponding to that token.

3) Using Validators with WS-Trust

To see the power and flexibility of the approach of separating processing from validation, consider the STSTokenValidator that ships with CXF 2.4. This validator implementation has the ability to dispatch a received BinarySecurityToken, UsernameToken, or SAML Assertion to an STS (Security Token Service) for validation via WS-Trust. On invocation, it delegates the credential to another validator (STSSamlAssertionValidator). This validator essentially catches an exception caused by a signature validation failure of the SAML Assertion and sets a flag. Only if signature validation is unsuccessful does the STSTokenValidator dispatch the token to the STS for validation.

An example of how to configure the STSTokenValidator to validate a SAML1 Assertion against an STS in spring is as follows:

<jaxws:endpoint ...>
<jaxws:properties>
    <entry key="ws-security.saml1.validator">
      <bean class="org.apache.cxf.ws.security.trust.STSTokenValidator"/>
    </entry>
    <entry key="ws-security.sts.client">
      <bean class="org.apache.cxf.ws.security.trust.STSClient">
        <constructor-arg ref="cxf"/>
        <property name="wsdlLocation" value="..."/>
        <property name="serviceName" value=".../>
        <property name="endpointName" value="..."/>
         ...
       </bean>
     </entry>
   </jaxws:properties>
</jaxws:endpoint>

The STSTokenValidator also has the ability to obtain a transformed token from the STS and store it in the credential, where it is available as part of the WSSecurityEngineResult under the TAG_TRANSFORMED_TOKEN tag.

WS-SecurityPolicy/SAML sample in Talend Service Factory 2.4.0

2011-06-10T14:05:00.000-07:00

In this post I will walk through the WS-SecurityPolicy sample that ships with Talend Service Factory 2.4.0. This sample shows how to secure a web service provider using both a UsernameToken and a SAML Assertion. For this post I will concentrate exclusively on the SAML case.

1) Download the artifacts

Go here and download Talend Service Factory 2.4.0. When this is done, go here and download the Talend Service Factory 2.4.0 examples (registration required). Extract the examples into the Talend Service Factory (TSF) install directory ($TSF_HOME). Finally, this sample requires that unlimited strength security policies be installed in the JDK.

2) Build and run the sample

Go to $TSF_HOME/examples/jaxws-ws-secpol and start with the README.txt. Run "mvn eclipse:eclipse" to generate eclipse projects, and "mvn install" to build and install the various modules. There are two options to run the sample.

2.1) Run the sample using maven

To start the service go to the service folder, and run "mvn exec:java". To run the test then go to the client folder and also run "mvn exec:java".

2.2) Run the sample in Karaf

To deploy the service and run the client in an OSGi environment, we can take advantage of the Karaf distribution that ships with TSF. Go to $TSF_HOME/container/bin and run the "karaf" binary. Install the three bundles in Karaf with:

install mvn:com.talend.sf.examples.jaxws-ws-secpol/ws-secpol-common/1.0
install mvn:com.talend.sf.examples.jaxws-ws-secpol/ws-secpol-server/1.0
install mvn:com.talend.sf.examples.jaxws-ws-secpol/ws-secpol-client/1.0

Each of these commands will print out a bundle id. Run the sample by invoking "start <id>" for each of the three bundle ids in turn.

3) The Service Provider

3.1) The Security Policy

The Service endpoint is secured via the following security policy fragment, which is defined in the WSDL ("ws-secpol-wsdl/greeter.wsdl" in the common folder):

<wsp:All>
<sp:AsymmetricBinding xmlns:sp=".../ws-securitypolicy/200702">
    <wsp:Policy>
      <sp:InitiatorToken>
        <wsp:Policy>
          <sp:X509Token sp:IncludeToken=".../AlwaysToRecipient">
            <wsp:Policy>
              <sp:RequireThumbprintReference />
              <sp:WssX509V3Token10 />
            </wsp:Policy>
          </sp:X509Token>
        </wsp:Policy>
      </sp:InitiatorToken>
      <sp:RecipientToken>
        <wsp:Policy>
          <sp:X509Token sp:IncludeToken=".../Never">
            <wsp:Policy>
              <sp:RequireThumbprintReference />
              <sp:WssX509V3Token10 />
            </wsp:Policy>
          </sp:X509Token>
        </wsp:Policy>
      </sp:RecipientToken>
      ...
    </wsp:Policy>
</sp:AsymmetricBinding>
...
<sp:SignedSupportingTokens xmlns:sp=".../ws-securitypolicy/200702">
    <wsp:Policy>
      <sp:SamlToken sp:IncludeToken=".../AlwaysToRecipient">
        <wsp:Policy>
          <sp:WssSamlV20Token11/>
        </wsp:Policy>
      </sp:SamlToken>
    </wsp:Policy>
</sp:SignedSupportingTokens>
</wsp:All>

This Security Policy defines that the Asymmetric Binding is to be used in communication with the service provider, i.e. that the client must sign the request using its private key, and include the corresponding X509 Certificate in the security header of the request, and encrypt the request using the public key of the service provider. Authentication is performed on the basis of trust verification of the client's certificate, as the client illustrates proof-of-possession by signing some part of the request.

In addition to the Asymmetric Binding, the policy requires that a SAML 2.0 Assertion must be included in the service request, and it must be signed by the signature defined by the Asymmetric Binding policy. The (policy-driven) ability to add a SAML Assertion to a SOAP Request is new to Apache CXF 2.4.

Finally, the WSDL defines input and output policies (not included here), which specify that the SOAP Body must be signed and encrypted, and that all of the addressing headers must be signed if present.

3.2) The configuration

The standalone (maven-driven) case is configured entirely in code. The various security configuration items are added as properties to the JAX-WS Endpoint object. The same security configuration items are also used for the case of deploying the service provider in Karaf, except that it is all driven through spring, e.g.:

<jaxws:server id="SAMLGreeter" xmlns:ns1="..."
endpointName="ns1:SAMLGreeterPort"
serviceClass="demo.secure_greeter.server.GreeterImpl">
<jaxws:properties>
    <entry key="ws-security.callback-handler" value="..."/>
    <entry key="ws-security.encryption.properties" value="..."/>
    <entry key="ws-security.signature.properties" value="..."/>
    <entry key="ws-security.saml2.validator" value="..."/>
</jaxws:properties>
</jaxws:server>

Four security-related configuration options are used for the service provider. "ws-security.callback-handler" points to a CallbackHandler implementation that is used to supply a password for extracting a private key from a keystore to decrypt the request and sign the response. "ws-security.encryption.properties" refers to a properties file which contains configuration options for loading the keystore used for encryption. Similarly, "ws-security.signature.properties" refers to a properties file for signature creation (and decryption).

"ws-security.saml2.validator" is a configuration tag new to CXF 2.4, and refers to an instance of the WSS4J Validator interface. The Validator interface is used in WSS4J to validate received security tokens. In this case, we are extending the default SAML2 Token Validation with a custom Validator. This Validator does some additional verification on the received token, namely checking who the issuer is, checking that the confirmation method is "sender-vouches", and checking that the Assertion contains an AttributeStatement, with an Attribute "attribute-role" containing a value "authenticated-client".

All of these configuration tags are defined in the SecurityConstants class in CXF.

4) The client

When the client wants to invoke on the service provider, it parses the security policy described above in the WSDL. As with the service provider, the client standalone case is configured entirely in code. For the case of deploying the client in Karaf, it is configured in spring as follows:

<jaxws:client id="samlgreeter" wsdlLocation="..." serviceClass="..."
xmlns:ns1="" serviceName="ns1:SecureGreeterService"
endpointName="ns1:SAMLGreeterPort">
<jaxws:properties>
    <entry key="ws-security.signature.username" value="..."/>
    <entry key="ws-security.encryption.username" value="..."/>
    <entry key="ws-security.callback-handler"><bean class="..."/></entry>
    <entry key="ws-security.signature.properties" value="..."/>
    <entry key="ws-security.encryption.properties" value="..."/>
    <entry key="ws-security.saml-callback-handler" value="..."/>
</jaxws:properties>
</jaxws:client>

"ws-security.callback-handler", "ws-security.signature.properties" and "ws-security.encryption.properties" have been covered in the section on configuring the service provider. "ws-security.signature.username" refers to the keystore alias of the private key to use to sign the request, and "ws-security.encryption.username" refers to the keystore alias to use to encrypt the request.

"ws-security.saml-callback-handler" is a configuration tag new to CXF 2.4, and refers to a CallbackHandler which will supply WSS4J with the information to create a SAML Assertion. This sample ships with a CallbackHandler that creates a simple SAML 2.0 Assertion with a subject confirmation method of "sender-vouches". It adds an Attribute to the Assertion that conveys to the Web Service Provider that the client has authenticated an external user in some way (not shown as part of this sample), and has assigned the attribute role of "authenticated-client" to the external user. The assertion that will be generated from this CallbackHandler instance will be signed by the client, as per the policy definition ("SignedSupportingTokens").

5) The Client Request

The security header of the client request contains a BinarySecurityToken which contains the certificate to use to verify the signature. It also contains a Timestamp, an EncryptedKey which is used to encrypt the SOAP Body, a SAML2 Assertion, and a Signature which signs the Timestamp, Assertion and encrypted SOAP Body. The Assertion looks like this:

<saml2:Assertion xmlns:saml2="..." xmlns:xsi="..." ID="..." IssueInstant="..."
Version="2.0" xsi:type="saml2:AssertionType">
<saml2:Issuer>...</saml2:Issuer>
<saml2:Subject>
   <saml2:NameID Format=...:unspecified">uid=auth_client</saml2:NameID>
   <saml2:SubjectConfirmation Method="...:sender-vouches">
     <saml2:SubjectConfirmationData/>
   </saml2:SubjectConfirmation>
</saml2:Subject>
<saml2:Conditions NotBefore="..." NotOnOrAfter="..."/>
<saml2:AttributeStatement>
   <saml2:Attribute FriendlyName="attribute-role" NameFormat="...">
     <saml2:AttributeValue xsi:type="xs:string">
       authenticated-client
     </saml2:AttributeValue>
   </saml2:Attribute>
</saml2:AttributeStatement>
</saml2:Assertion>

The service provider processes the received security header as follows:

It checks that the Timestamp is valid
It uses its private key to decrypt the EncryptedKey, and then uses the decrypted key to decrypt the SOAP Body.
It verifies that the Assertion is valid, and passes the Assertion to the custom Validator defined above to validate the contents of the Assertion.
It verifies that the certificate defined in the BinarySecurityToken can validate the signature, verifies trust in the certificate, and checks that each of the References of the signature produce the correct digest.

At this point security processing is complete, and the service provider constructs a secured response to the client.

WSS4J 1.6.1 released

2011-06-08T06:11:00.000-07:00

Apache WSS4J 1.6.1 has been released. The distribution can be downloaded here, and the list of issues that have been fixed is here. There are a number of bug fixes to the new functionality introduced in the 1.6.0 release, including some fixes to the SAML Assertion creation code, and a fix to get WSS4J 1.6 working with the IBM JDK. A noteworthy new feature is support for CRLs, as documented by a previous blog post.

In other news, my employer has published a short questionnaire to find out what topics users of open-source integration software are interested in learning about. So for example if you are interested in hearing more from me on enabling security in Apache CXF, navigate to the CXF part of the survey and select the appropriate checkbox for "WS-Security in Apache CXF".

CRL support in WSS4J 1.6.1

2011-05-30T07:12:00.000-07:00

Support for Certificate Revocation Lists (CRLs) has been a long sought feature in WSS4J, and will arrive in the imminent release of WSS4J 1.6.1. This will ensure that the certificate used to validate a signature is not revoked by the issuing Certificate Authority.

Support for CRLs is covered by the task WSS-278. The default behaviour is that certificate revocation is not enabled for backwards compatibility reasons. Two parameters must be configured to enable certificate revocation. The first is that the WSHandlerConstants property "enableRevocation" must be set to "true", if WSS4J is being used in the context of WSHandler. If the handler architecture is not being used, then a new method has been added to the Crypto interface for signature trust validation which explicitly enables certificate revocation:

public boolean verifyTrust(X509Certificate[] certs, boolean enableRevocation) throws WSSecurityException;

The previous verifyTrust(certs) method has been deprecated. Please bear in mind that any custom Crypto implementation must be updated with the new method, or else you will face a compilation error on upgrading to WSS4J 1.6.1.

The second is that the Crypto instance that is used must be supplied with CRL information. This can be done in a number of different ways. The default Crypto instance that ships with WSS4J (Merlin), has a new configuration property:

org.apache.ws.security.crypto.merlin.x509crl.file: The location of an (X509) CRL file to be loaded via CertificateFactory.generateCRL(...).

Merlin also has two new accessor methods to set/get a CertStore object to be used for CRL checking (i.e. setCRLCertStore(CertStore crlCertStore)), if you wish to supply CRL information programatically to the Crypto instance.

Update: You can see a test for this feature here.

Apache XML Security for Java 1.4.5 released

2011-05-27T06:53:00.000-07:00

Apache XML Security for Java 1.4.5 has been released:

The Apache Santuario team are pleased to announce the release of
version 1.4.5 of the Apache XML Security for Java library. This
release fixes a thread safety issue in the ResourceResolver, and a
regression in signature generation for the Canonical XML 1.1
algorithm, as well as a number of other bug fixes.

Please see the release notes for more information:

https://issues.apache.org/jira/browse/SANTUARIO/fixforversion/12315957

You can download the library here:

http://santuario.apache.org/download.html

Talend ESB Standard Edition released

2011-05-18T10:36:00.000-07:00

Last week the Talend ESB Standard Edition was released:

A core component of the unified platform for data services, Talend ESB includes messaging, Web services, mediation and adapters in an open and standards-based offering used to integrate distributed systems across functional, enterprise and/or geographic boundaries. Powered by leading Apache open source integration projects Apache CXF, Apache Camel and Apache ActiveMQ, Talend ESB is a versatile and flexible ESB that allows organizations to address any integration challenge, from simple departmental projects to complex, heterogeneous IT environments.

Of particular interest to readers of this blog might be the Security Token Service (STS) framework which ships as part of Talend ESB. More on this in a future blog post.

To download Talend ESB Standard Edition go here. For more information, see the datasheet here.

In other Talend-related news, Talend is now a sponsor of the Apache Software Foundation.

WS-Trust sample in Talend Service Factory 2.4.0

2011-05-11T09:18:00.000-07:00

In this post I will walk through the WS-Trust sample that ships with Talend Service Factory 2.4.0.

1) Download the artifacts

Go here and download Talend Service Factory 2.4.0. When this is done, go here and download the Talend Service Factory 2.4.0 examples (registration required). Extract the examples into the Talend Service Factory (TSF) install directory ($TSF_HOME).

2) Build and run the sample

Go to $TSF_HOME/examples/jaxws-ws-trust and start with the README.txt. Run "mvn eclipse:eclipse" to generate eclipse projects, and "mvn install" to build and install the various modules.

Both the CXF service provider and Metro STS used in this sample are deployed in Tomcat. To see how to configure Maven to install/uninstall these artifacts in Tomcat follow the instructions here. Finally, you need to make sure that the path to the keystores is correct for the Metro STS - follow the instructions in the README.txt for this.

Start Tomcat, and from the sts-war folder run "mvn install tomcat:deploy". Run the same command from the service-war folder to deploy the CXF service provider in Tomcat.

Finally to run the test, go to the client folder and run "mvn install exec:exec". You also have the option of running the client in Karaf (follow the instructions in the README.txt).

3) The sample

Three service invocations take place as part of this sample. For simplicity, I'll just concentrate on the third one, which shows how a SAML2 Assertion is used in a WS-Trust scenario.

3.1) The Service Provider

We'll start with the Service Provider, as the client will use the security policies defined in the WSDL of the Service Provider to access the STS. The Service is spring-loaded via the following configuration:

<jaxws:endpoint id="doubleitsaml2"
      implementor="service.DoubleItPortTypeImpl"
      address="/doubleitsaml2"
      endpointName="DoubleItPortSAML2"
      wsdlLocation="WEB-INF/wsdl/DoubleIt.wsdl">

      <jaxws:properties>
         <entry key="ws-security.callback-handler" value="..."/>
         <entry key="ws-security.signature.properties" value="..."/>
         <entry key="ws-security.is-bsp-compliant" value="false"/>
      </jaxws:properties>
</jaxws:endpoint>

Three properties are required for the endpoint. The CallbackHandler implementation is required to provider the password used to access the private key in the Keystore, which is in turn configured in the "ws-security.signature.properties" file. The "ws-security.is-bsp-compliant" configuration turns off Basic Security Profile 1.1 compliance enforcement. This is required as the Metro STS generates a non BSP-compliant SAML Assertion (try removing this line, redeploying the service provider in tomcat and see what happens when the test is re-run).

The WSDL (DoubleIt.wsdl) contains the security policies for the service provider. It requires that the input and output SOAP Body elements must be signed and encrypted, and that all of the addressing headers must be signed in both directions. It also contains the following policy snippet:

<sp:SymmetricBinding>
<wsp:Policy>
    <sp:ProtectionToken>
      <wsp:Policy>
        <sp:IssuedToken sp:IncludeToken="...AlwaysToRecipient">
          <sp:RequestSecurityTokenTemplate>
            <t:TokenType>...#SAMLV2.0</t:TokenType>
            <t:KeyType>.../SymmetricKey</t:KeyType>
            <t:KeySize>256</t:KeySize>
          </sp:RequestSecurityTokenTemplate>
          ...
          <sp:Issuer>
            <wsaw:Address>http://.../DoubleItSTSServiceUT</wsaw:Address>
            <wsaw:Metadata>
              ...
            </wsaw:Metadata>
          </sp:Issuer>
        </sp:IssuedToken>
      </wsp:Policy>
    </sp:ProtectionToken>
    ...
</wsp:Policy>
</sp:SymmetricBinding>

This SecurityPolicy snippet defines that the communication with the service provider is secured via the SymmetricBinding, i.e. that it is secured via a secret key. The ProtectionToken policy describes how the secret key in turn is conveyed to the service provider in a secure way. In this example, it defines an IssuedToken policy, which is always sent to the recipient (service provider). Once the client sees this policy, it will know that it must contact a Security Token Service (STS) via the WS-Trust protocol to obtain a (issued) token that will convey the symmetric key to the service provider.

The IssuedToken policy has a RequestSecurityTokenTemplate policy, which the client will copy verbatim when contacting the STS for a security token. It describes the token type that is required (a SAML2 Assertion), the KeyType conveyed in the Assertion (Symmetric Key), and the size of the symmetric key (256 bits). It also contains an Issuer policy which describes how the STS may be contacted via a wsa EndpointReferenceType.

3.2) The Security Token Service (STS)

The STS used in this sample is the Metro STS. The port is secured with the following security policy binding:

<sp:AsymmetricBinding>
<wsp:Policy>
   <sp:InitiatorToken>
       <wsp:Policy>
         <sp:X509Token sp:IncludeToken=".../AlwaysToRecipient">
           <wsp:Policy>
             <sp:WssX509V3Token10 />
           </wsp:Policy>
         </sp:X509Token>
       </wsp:Policy>
       </sp:InitiatorToken>
     <sp:RecipientToken>
       <wsp:Policy>
         <sp:X509Token sp:IncludeToken=".../Never">
           <wsp:Policy>
             <sp:WssX509V3Token10 />
             <sp:RequireIssuerSerialReference />
           </wsp:Policy>
         </sp:X509Token>
       </wsp:Policy>
     </sp:RecipientToken>
      ...
</wsp:Policy>
</sp:AsymmetricBinding>

This Security Policy defines that the Asymmetric Binding is to be used in communication with the STS, i.e. that the client must sign the request using its private key, and include the corresponding X509 Certificate in the security header of the request, and encrypt the request using the public key of the STS. Authentication is performed on the basis of trust verification of the client's certificate, as the client illustrates proof-of-possession by signing some part of the request.

The WSDL of the STS also contains a "STSConfiguration" policy fragment, which defines that the issued key is encrypted, and lists the service provider endpoints, including the corresponding public keys.

3.3) The client

When the client wants to invoke on the service provider, it parses the security policy described above in the WSDL, and sees that it must first obtain an IssuedToken from a STS before it can construct the service request. The client is configured in spring as follows:

<jaxws:client name="{...}DoubleItPortSAML2" createdFromAPI="true">
<jaxws:properties>
    <entry key="ws-security.sts.client">
      <bean class="org.apache.cxf.ws.security.trust.STSClient">
        <constructor-arg ref="cxf"/>
        <property name="wsdlLocation" value="DoubleItSTSService.wsdl"/>
        <property name="serviceName" value="{...}DoubleItSTSService"/>
        <property name="endpointName" value="{...}IDoubleItSTS..Port"/>
        <property name="properties">
          <map>
            <entry key="ws-security.signature.username" value="..."/>
            <entry key="ws-security.callback-handler" value="..."/>
            <entry key="ws-security.signature.properties" value="..."/>
            <entry key="ws-security.encryption.properties" value="..."/>
            <entry key="ws-security.encryption.username" value="..."/>
          </map>
        </property>
      </bean>
</entry>
</jaxws:properties>
</jaxws:client>

The STSClient bean contains the configuration required to contact the STS. The client parses the WSDL of the STS, and uses the supplied configuration parameters to construct a request that is secured by the Asymmetric Binding, as discussed above. This request is done via the WS-Trust protocol.

3.4) The STS request

In the SOAP Body of the request is the following information (decrypted):

<wst:RequestSecurityToken>
<wst:SecondaryParameters>
    <t:TokenType>...#SAMLV2.0</t:TokenType>
    <t:KeyType>.../SymmetricKey</t:KeyType>
    <t:KeySize>256</t:KeySize>
</wst:SecondaryParameters>
<wst:RequestType>.../Issue</wst:RequestType>
<wsp:AppliesTo>
    <wsa:EndpointReference>
...
    </wsa:EndpointReference>
</wsp:AppliesTo>
...
<wst:Entropy>
    <wst:BinarySecret Type=".../Nonce">...</wst:BinarySecret>
</wst:Entropy>
<wst:ComputedKeyAlgorithm>.../CK/PSHA1</wst:ComputedKeyAlgorithm></wst:RequestSecurityToken>

The SecondaryParameters element is copied verbatim from the RequestSecurityTokenTemplate defined in the policy of the service provider. The RequestType element defines an "Issue" URI. AppliesTo refers to the address of the service provider. Entropy contains some client-generated entropy (which the STS will combine with its own Entropy to form a symmetric key), using the ComputedKeyAlgorithm URI.

3.5) The STS response

The response from the STS contains the following (decrypted) SOAP Body. It contains the token type of the requested token, the token itself, different ways of referring to the requested token, some entropy that the client can use to recreate the symmetric key, the lifetime of the requested token, etc:

<trust:RequestSecurityTokenResponseCollection>
<trust:RequestSecurityTokenResponse>
    <trust:TokenType>...#SAMLV2.0</trust:TokenType>
    <trust:RequestedSecurityToken>
      <saml2:Assertion>
      ...
      </saml2:Assertion>
    </trust:RequestedSecurityToken>
    <trust:RequestedAttachedReference>...</trust:RequestedAttachedReference>
    <trust:RequestedUnattachedReference>
    ...
    </trust:RequestedUnattachedReference>
    <wsp:AppliesTo...>...</wsp:AppliesTo>
    <trust:RequestedProofToken>
        <trust:ComputedKey>.../CK/PSHA1</trust:ComputedKey>
    </trust:RequestedProofToken>
    <trust:Entropy>
      <trust:BinarySecret Type=".../Nonce">...</trust:BinarySecret>
    </trust:Entropy>
    <trust:Lifetime>
      <wsu:Created...>...</wsu:Created>
      <wsu:Expires...>...</wsu:Expires>
    </trust:Lifetime>
    <trust:KeySize>256</trust:KeySize>
</trust:RequestSecurityTokenResponse>
</trust:RequestSecurityTokenResponseCollection>

The requested security token that is returned above is reproduced here. Note that the SubjectConfirmation Method is "holder-of-key", meaning that the client must illustrate proof of possession of the key contained in the EncryptedKey element of the Assertion. The EncryptedKey element is encrypted using the service provider's public key.

<saml2:Assertion ID="..." IssueInstant="..." Version="2.0">
<saml2:Issuer>DoubleItSTSIssuer</saml2:Issuer>
<ds:Signature>...</ds:Signature>
<saml2:Subject>
    <saml2:NameID NameQualifier="...">...</saml2:NameID>
    <saml2:SubjectConfirmation Method="...:cm:holder-of-key">
      <saml2:SubjectConfirmationData>
...
      <xenc:EncryptedKey
    ...
      </xenc:EncryptedKey>
...
      </saml2:SubjectConfirmationData>
   </saml2:SubjectConfirmation>
</saml2:Subject>
<saml2:Conditions NotBefore="..." NotOnOrAfter="..."></saml2:Conditions>
<saml2:AttributeStatement>
   <saml2:Attribute...>
     <saml2:AttributeValue>authenticated</saml2:AttributeValue>
   </saml2:Attribute>
</saml2:AttributeStatement>
</saml2:Assertion>

3.5) The Service Provider request

Once the client receives the Issued Token from the STS, it recreates the symmetric key needed to communicate with the service provider, by combining the entropy received from the STS with its own entropy to form the session key. The (decrypted) SAML2 Assertion is inserted into the security header "as is". The symmetric key is referenced in the request via the following structure:

<ds:KeyInfo Id="...">
<wsse:SecurityTokenReference wsse11:TokenType="...#SAMLV2.0" >
    <wsse:KeyIdentifier ValueType="...#SAMLID">...</wsse:KeyIdentifier>
</wsse:SecurityTokenReference>
</ds:KeyInfo>

The Service Provider verifies the signature of the STS on the SAML Assertion, and then decrypts the EncryptedKey fragment using its private key, to obtain the symmetric key used to decrypt/verify the client request. As the confirmation method is "holder-of-key", the Service Provider ensures that the same key was used to sign some portion of the request, thus proving that the client is in possession of the key.

Talend Service Factory 2.4.0 released

2011-04-29T07:36:00.000-07:00

Talend Service Factory 2.4.0 has been released. It's based on Apache CXF 2.4.0, and so contains all of the security features in WSS4J 1.6.0, as well as the extensive support for SAML Assertions in CXF 2.4.0, that I have been blogging about for the last while.

In addition to this, some examples are available for download, which illustrate how to get these (security) features working in an OSGi container. A lot of work has gone into making sure that security libraries such as Apache Santuario, Apache WSS4J and Opensaml can be used in an OSGi environment, so I recommend checking the examples out to see how it can be done.

See Glen's blog for more information on the security examples. Also, see Sergey's blog for a discussion on some other examples based around transforming XML.

SAML support in CXF 2.4.0

2011-04-21T04:28:00.000-07:00

The recent Apache CXF 2.4.0 release contains support for creating, securing, processing and validating SAML Assertions according to the WS-Security 1.1 SAML Token Profile. As there is no documentation available as yet on this new feature, in this blog post I will go through a SAML system test in CXF 2.4.0 in detail.

1) Running the Test

To run the SAML system test you can do the following:

svn co https://svn.apache.org/repos/asf/cxf/tags/cxf-2.4.0/systests/ws-security

cd ws-security
mvn compile

mvn test -Dtest=SamlTokenTest

2) The Client

2.1) The Client code

You can view the source of the tests here. There are a number of tests involving creating SAML 1.1 and 2.0 assertions, and sending them to a service provider over various security bindings (Transport/Symmetric/Asymmetric). To simplify things, we will focus on the fourth test named "testSaml2OverAsymmetric". Minus some negative tests, the basic test client invocation code is as simple as:

SpringBusFactory bf = new SpringBusFactory();

URL busFile = SamlTokenTest.class.getResource("client/client.xml");

Bus bus = bf.createBus(busFile.toString());

SpringBusFactory.setDefaultBus(bus);

SpringBusFactory.setThreadDefaultBus(bus);

DoubleItService service = new DoubleItService();

DoubleItPortType saml2Port = service.getDoubleItSaml2AsymmetricPort();

((BindingProvider)saml2Port).getRequestContext().put(

"ws-security.saml-callback-handler", new SamlCallbackHandler()

);

BigInteger result = saml2Port.doubleIt(BigInteger.valueOf(25));

assert result.equals(BigInteger.valueOf(50));

2.2) The WSDL

The service is described in the WSDL here. Take a look at the WS-SecurityPolicy called "DoubleItSaml2AsymmetricPolicy", which defines the security requirements for the "DoubleItSaml2AsymmetricPort". It defines an Asymmetric Binding, where the InitiatorToken (which defines the credential used to sign the request) is always sent to the recipient, and the RecipientToken (which defines the credential used to encrypt the request) is never sent to the recipient. Both Initiator and Recipient tokens are defined as X509 tokens. The input and output policies in the WSDL enforce that the SOAP Body must be signed using the Initiator credential, and encrypted using the Recipient credential.

In addition to specifying an asymmetric binding, the policy also defines a SignedSupportingToken, which contains a SAML (2.0) Token which is always sent to the recipient. In order to successfully invoke on the service, the client must include a SAML 2.0 token in the security header of the request. This policy looks like:

<sp:SignedSupportingTokens>
    <wsp:Policy>
        <sp:SamlToken sp:IncludeToken="...AlwaysToRecipient">
            <wsp:Policy>
                <sp:WssSamlV20Token11/>
            </wsp:Policy>
        </sp:SamlToken>
    </wsp:Policy>

</sp:SignedSupportingTokens>

2.3) The Client configuration

The client.xml referenced in the code block above contains a jaxws:client configuration for the DoubleItSaml2AsymmetricPort. It sets the following relevant jaxws:properties:

ws-security.encryption.properties - The Crypto properties file which describes where to find the service provider's public key.
ws-security.encryption.username - The alias to use to obtain the service provider's public key from the keystore reference in the Crypto properties file above.
ws-security.callback-handler - A CallbackHandler object which is expected to supply the password used to access the private key for signature creation, or decryption.
ws-security.signature.properties - The Crypto properties file which describes where to find the client's public/private key.
ws-security.signature.username - The alias to use to obtain the client's private key from the keystore reference in the Crypto properties file above.

2.3) Creating a SAML token

CXF 2.4.0 defines a new jaxws:property ("ws-security-saml-callback-handler") which specifies a CallbackHandler instance used to create SAML Assertions. This object is added to the outbound request context above dynamically, however it could also have been configured in the spring bean along with the other ws-security parameters. The CallbackHandler object used in this test can be seen here. The CallbackHandler implementation is expected to obtain a SAMLCallback object, and to set the appropriate values on this object, e.g. SAML version, Subject, issuer, Authentication/Authorization/Attribute Statements, etc. In the example provided in this test, it creates a SAML 2.0 assertion (by default), sets a mock issuer, subject and attribute statement, and sets a subject confirmation method of sender-vouches. Some code in WSS4J then constructs a SAML Assertion by processing this SAMLCallback object. It's easy to construct a SAML Assertion in this way, as the following (edited) code shows:

SAMLCallback callback = (SAMLCallback) callbacks[i];

callback.setSamlVersion(SAMLVersion.VERSION_20);

callback.setIssuer("sts");

String subjectName = "uid=sts-client,o=mock-sts.com";

String subjectQualifier = "www.mock-sts.com";

SubjectBean subjectBean = new SubjectBean(subjectName, subjectQualifier, SAML2Constants.CONF_SENDER_VOUCHES);

callback.setSubject(subjectBean);

AttributeStatementBean attrBean = new AttributeStatementBean();

attrBean.setSubject(subjectBean);

AttributeBean attributeBean = new AttributeBean();

attributeBean.setSimpleName("subject-role");

attributeBean.setAttributeValues(Collections.singletonList("system-user"));

attrBean.setSamlAttributes(Collections.singletonList(attributeBean));

callback.setAttributeStatementData(Collections.singletonList(attrBean));

2.4) The service request

The service request has a security header that contains the following elements:

A BinarySecurityToken which consists of the X509Certificate of the client.
A Timestamp.
An EncryptedKey which consists of a symmetric key encrypted with the public key of the service provider, which is used to encrypt the SOAP Body.
A SAML2 Assertion.
A SecurityTokenReference to the SAML Assertion.
A signature which signs the Timestamp, the SAML Assertion (via the SecurityTokenReference) and the (decrypted) SOAP body. The signing credential is the BinarySecurityToken element described above.

The SAML 2.0 assertion looks like (edited):

<saml2:Assertion ... Version="2.0">

<saml2:Issuer>sts</saml2:Issuer>

<saml2:Subject>

<saml2:NameID ...>uid=sts-client,o=mocksts.com</saml2:NameID>

<saml2:SubjectConfirmation Method="...:sender-vouches">

</saml2:SubjectConfirmation>

</saml2:Subject>

<saml2:Conditions NotBefore="..." NotOnOrAfter="..."/>

<saml2:AttributeStatement>

<saml2:Attribute FriendlyName="subject-role" ...>

<saml2:AttributeValue...>system-user</saml2:AttributeValue>

</saml2:Attribute>

</saml2:AttributeStatement>

</saml2:Assertion>

One thing to note is that as the SAML Assertion has a subject confirmation method of "sender-vouches", the client will automatically add the quality-of-service requirement that the signature which covers the SOAP Body will also cover the SAML Assertion.

3) The Server

3.1) The Server code

The SEI implementation is here, and the Server code itself is here. The configuration is entirely driven through the WSDL and spring configuration, and so the code is as trivial as (edited):

URL busFile = Server.class.getResource("server.xml");
Bus busLocal = new SpringBusFactory().createBus(busFile);
BusFactory.setDefaultBus(busLocal);
setBus(busLocal);
new Server();

3.2) The Server configuration

The server.xml configuration file referenced above can be seen here. The jaxws:Endpoint configuration for this port should be self-explanatory (edited):

<jaxws:endpoint
       id="Saml2TokenOverAsymmetric"
       address="http://localhost:9001/DoubleItSaml2Asymmetric"
       serviceName="s:DoubleItService"
       endpointName="s:DoubleItSaml2AsymmetricPort"
       xmlns:s="http://WSSec/saml"
       implementor="org.apache.cxf.systest.ws.saml.server.DoubleItImpl"
       wsdlLocation="wsdl_systest_wssec/saml/DoubleItSaml.wsdl">

       <jaxws:properties>
           <entry key="ws-security.username" value="bob"/>
           <entry key="ws-security.callback-handler"
                  value="....KeystorePasswordCallback"/>
           <entry key="ws-security.signature.properties"
                  value="...bob.properties"/>
           <entry key="ws-security.encryption.properties"
                  value="...alice.properties"/>
           <entry key="ws-security.encryption.username" value="alice"/>
       </jaxws:properties>
</jaxws:endpoint>

The server will process the request as per the security policy in the WSDL, checking that there is a signature in the security header, that covers the SOAP Body and SAML Assertion, that the SOAP Body is Encrypted, that a Timestamp is present and valid, and that the SAML Assertion is present, and is the correct version, etc. Authentication is done on the basis of trust verification of the client's X509Certificate, which was used to verify the signature element.

The SAML Assertion is ignored beyond this point for this system test. It is saved in the security processing results, so that a custom interceptor can do some additional validation or processing on it. In a future blog post, I will describe how to validate the Assertion that has been received in some custom manner.

CXF 2.4.0 released

2011-04-20T07:27:00.000-07:00

Apache CXF 2.4.0 has been released. CXF 2.4.0 contains a number of new and improved features in the security space. From the release statement:

WS-Security improvements including support for SAML2 tokens, improved 
validation of security tokens, better performance, increased WS-I Basic 
Security Profile compliance, and much more.

If those new features seem familiar, it's because most of the new functionality is driven by WSS4J 1.6.0, which I've blogged extensively about over the last few months. Probably the most significant new security functionality in CXF 2.4.0 is greatly enhanced support for SAML Assertions. CXF 2.4.0 supports the ability to create, secure, process and validate SAML Assertions in accordance with the WS-Security 1.1 SAML Token Profile. I intend to blog in more detail how to use these new features in CXF 2.4.0 over the next while.

See Dan Kulp's blog for more in-depth thoughts on the new release.

WSS4J 1.6.0 released

2011-04-15T04:28:00.000-07:00

WSS4J 1.6.0 has been released:

The Apache Web Services team is pleased to announce the release of WSS4J 1.6.0. WSS4J 1.6.0 features support for SAML2 assertions, JSR-105 support, better spec compliance, performance work, support for trust-stores and a lot more besides. It is not API-compatible with the 1.5.x series of releases.

For more information on the new features and changes in WSS4J 1.6.0 go to:

http://ws.apache.org/wss4j/wss4j16.html

To download WSS4J 1.6.0 go to:

http://ws.apache.org/wss4j/download.html

-- The Apache Web Services Team

[WSS4J 1.6] Introducing Validators

2011-04-05T05:18:00.000-07:00

WSS4J 1.6 introduces the concept of a Validator, for validating credentials that have been processed by a Processor instance. This task was covered by the JIRA WSS-266.

An inbound security header is processed by WSS4J by iterating through each child element of the header, and by calling the appropriate Processor implementation to deal with each element. In WSS4J 1.5.x, some processors perform validation on the received token (e.g. UsernameTokens), whereas others store the processing results for later verification by third-party WS-Handler implementations (e.g. Timestamp verification, Certificate trust verification). There are some problems with this approach:

It is not consistent, some processors perform validation, others do not.
There is a potential security hole, in that it is assumed third-party code will know to validate the credentials that the WSS4J processors do not validate.
WSS4J will continue to process the rest of the security header even if the Timestamp is invalid, or the certificate non-trusted, which could lead to denial-of-service attacks.
There is no separation of concerns between processing the token and validating the token. If you want to change how the token is validated, you must replace the processor instance.

WSS4J 1.6 has moved Timestamp verification and certificate trust validation back into the processing of the security header, thus solving the first three points above. The fourth point is met by the new concept of Validators, as well as some changes to the way Processors and CallbackHandler implementations are used in WSS4J 1.6.

In WSS4J 1.5.x, CallbackHandler implementations are used in different ways by different processors, sometimes they are expected to verify a password (as for processing UsernameTokens), and other times they are expected to supply a password (as for decryption). In WSS4J 1.6, CallbackHandler implementations are only expected to supply a password (if it exists) to the processors. The Processor implementations do not perform any validation of the security token, instead they package up the processed token, along with any (password) information extracted from the CallbackHandler, and hand it off to a Validator implementation for Validation.

The Processor implementations get the specific Validator implementation to use via the RequestData parameter, which in turn asks a WSSConfig object for the Validator implementation. If the Validator is null, then no Validation is performed on the received token. The Processor then stores the received token as normal. WSS4J 1.6 comes with several default Validators, which are:

NoOpValidator: Does no processing of the credential
TimestampValidator: Validates a Timestamp
UsernameTokenValidator: Validates a UsernameToken
SignatureTrustValidator: Verifies trust in a signature
SamlAssertionValidator: Checks some HOK requirements on a SAML Assertion, and verifies trust on the (enveloped) signature.

There are some additional WSSecurityEngineResult constants that pertain to the Validator implementations:

TAG_VALIDATED_TOKEN: Indicates that the token corresponding to this result has been validated by a Validator implementation. Some of the processors do not have a default Validator implementation.
TAG_TRANSFORMED_TOKEN: A Validator implementation may transform a credential (into a SAML Assertion) as a result of Validation. This tag holds a reference to an AssertionWrapper instance, that represents a transformed version of the validated credential.

To validate an inbound UsernameToken in some custom way, simply associate the NoOpValidator with the UsernameToken QName in the WSSConfig of the RequestData object used to supply context information to the processors. After WSS4J has finished processing the security header, then extract the WSSecurityEngineResult instance corresponding to the WSConstants.UT action, and perform some custom validation on the token.

An example of how to add a custom Validator implementation is the STSTokenValidator in CXF 2.4.0. The STSTokenValidator tries to validate a received SAML Assertion locally, and if that fails, it dispatches it to a Security Token Service (STS) via the WS-Trust interface for validation. It also supports validating a UsernameToken and BinarySecurityToken in the same manner. The SecurityConstants class defines some configuration tags for specifying a custom validator for inbound SAML1, SAML2, UsernameToken, BinarySecurityToken, Signature and Timestamps. The STSTokenValidator can be configured by associating it with the appropriate configuration tag.

[WSS4J 1.6] SAML property changes

2011-03-13T08:02:00.000-07:00

A previous blog entry described how WSS4J 1.6 will have support for creating, parsing, signing, verifying, etc. SAML 2 assertions. WSS4J 1.5.x had limited support for creating and signing SAML 1.1 assertions via the default SAMLIssuer implementation, combined with a properties file. These configuration values consisted of:

org.apache.ws.security.saml.issuerClass - The SAML Issuer implementation (defaults to "org.apache.ws.security.saml.SAMLIssuerImpl").
org.apache.ws.security.saml.issuer.cryptoProp.file - The crypto properties file corresponding to the issuer crypto instance, if the assertion is to be signed.
org.apache.ws.security.saml.issuer.key.name - The KeyStore alias for the issuer key.
org.apache.ws.security.saml.issuer.key.password - The KeyStore password for the issuer key.
org.apache.ws.security.saml.issuer - The issuer name
org.apache.ws.security.saml.issuer.sendKeyValue - Whether to send the key value or the X509Certificate. Defaults to: "false".
org.apache.ws.security.saml.subjectNameId.name - The Subject DN.
org.apache.ws.security.saml.subjectNameId.qualifier - The Subject qualifier.
org.apache.ws.security.saml.authenticationMethod - The authentication method (e.g. "password").
org.apache.ws.security.saml.confirmationMethod - The confirmation method, either "senderVouches" or "keyHolder".

The configuration tags for WSS4J 1.5.x completely controlled the creation and signing of a SAML 1.1 Assertion, and hence produced only a very limited set of possible assertions. WSS4J 1.6 takes a different approach, where the configuration tags correspond to the configuration of the issuer, i.e. whether to sign the assertion or not, the issuer name, crypto instance, etc. All instructions about how to create the SAML Assertion itself, are left to a CallbackHandler implementation.

The following configuration tags in WSS4J 1.6 are exactly the same as in WSS4J 1.5.x:

org.apache.ws.security.saml.issuerClass - The SAML Issuer implementation (defaults to "org.apache.ws.security.saml.SAMLIssuerImpl").
org.apache.ws.security.saml.issuer.cryptoProp.file - The crypto properties file corresponding to the issuer crypto instance, if the assertion is to be signed.
org.apache.ws.security.saml.issuer.key.name - The KeyStore alias for the issuer key.
org.apache.ws.security.saml.issuer.key.password - The KeyStore password for the issuer key.
org.apache.ws.security.saml.issuer - The issuer name
org.apache.ws.security.saml.issuer.sendKeyValue - Whether to send the key value or the X509Certificate. Defaults to: "false".

The following configuration tags are new to WSS4J 1.6:

org.apache.ws.security.saml.issuer.signAssertion - Whether the SAMLIssuer implementation will sign the assertion or not. Defaults to: "false".
org.apache.ws.security.saml.callback - The name of the SAML CallbackHandler implementation used to populate the SAML Assertion.

[WSS4J 1.6] Basic Security Profile 1.1 compliance

2011-03-08T05:44:00.000-08:00

The Basic Security Profile (BSP) 1.1 specification provides an industry-standard way of making sure that different WS-Security stacks can communicate with each other, by clarifying and narrowing the scope of the various WS-Security standards. WSS4J 1.5.x does not implement the BSP in any meaningful way. The WSSConfig class supports a "isWsiBSPCompliant" method (default is false), which will enable the generation of an InclusivePrefix list for signature generation, something that is mandated by the BSP spec.

WSS4J 1.6 provides support for the BSP 1.1 specification, in so far as it pertains to the core WS-Security specifications that WSS4J supports. The enforcing of BSP compliance for inbound messages is controlled by the WSSConfig class, as per WSS4J 1.5.x. An important change is that BSP compliance is now turned on by default. In addition, a new WSHandlerConstants configuration parameter has been added so that BSP compliance can be controlled via a WSHandler implementation.

[WSS4J 1.6] JSR-105 support

2011-03-07T09:30:00.000-08:00

The soon-to-be released WSS4J 1.6 has been ported to use the JSR 105 API for XML Digital Signature. Previously, WSS4J 1.5.x used the custom API of the Apache Santuario XML Security for Java library to create and process XML Digital Signatures.

WSS4J 1.6 has a minimum requirement of JDK 1.5 (note that WSS4J 1.5.x supports JDK 1.4). As JDK 1.5 does not contain an implementation of JSR 105, this means that XML Digital Signature is done via the JSR 105 implementation of Apache Santuario. However, when JDK 1.6+ is used, WSS4J 1.6 uses the JDK implementation of JSR 105 for signature creation and verification. You can override this by endorsing the Santuario jar.

The Apache Santuario XML Security jar is still required for the JDK 1.6 case, as there are compile-time dependencies in WSS4J for encryption/decryption, as well as for some algorithm parsing, and resource resolver stuff. One downside to the Santuario jar, is its dependence on Xalan for a small subset of operations. This dependency will be removed for the 1.5 release of that library (in a few months).

It is worth noting some changes to the main class used in WSS4J for signature creation as a result of the JSR-105 port. In WSS4J 1.5.x, after the signature certs and list of references to sign had been configured, the "computeSignature" method was called to compute the signature. The DOM element corresponding to the signature was independent of the pre-existing security header, and could be extracted later and inserted into the security header.

In WSS4J 1.6, you must tell "computeSignature" where to insert the signature element. A boolean "prepend" argument allows you to configure whether to prepend the generated Signature element to the security header, or whether to append it. If prepend is true, then an optional siblingElement argument can be used to prepend the signature element before this sibling element. Once computeSignature has been called, you have no control over where the signature element is inserted into the security header.

[WSS4J 1.6] Beta release

2011-03-01T03:28:00.000-08:00

Following the announcement of an (unofficial) alpha release of WSS4J 1.6 a few weeks back, I'm pleased to announce that a beta release of WSS4J 1.6 has been created:

I have created an "unofficial" WSS4J 1.6-beta release. Please download
and play around with it etc. As it is a beta release, it is *not*
suitable for production in any way, and the APIs are subject to
change. The distribution is available here:

http://people.apache.org/~coheigea/stage/wss4j/1.6.0-beta/dist/

and the Maven artifacts are available here:

http://people.apache.org/~coheigea/stage/wss4j/1.6.0-beta/maven/

Only three JIRAs are currently open against 1.6.0:

https://issues.apache.org/jira/browse/WSS-268
https://issues.apache.org/jira/browse/WSS-257
https://issues.apache.org/jira/browse/WSS-256

WSS-268 involves getting Opensaml2 into Maven central, WSS-257 is
partially complete, and WSS-256 is mostly complete. I plan on creating
a Release Candidate in about a week, and calling a vote in about 2
weeks.

CXF trunk has already been upgraded to use a WSS4J 1.6-SNAPSHOT dependency.

Talend Integration Factory released

2011-02-28T07:56:00.000-08:00

Following in the footsteps of the first Talend Service Factory release last year, the first release of the Talend Integration Factory has been announced:

Talend Integration Factory, based on Apache Camel, uses well known Enterprise Integration Patterns to make message-based system integration easier to implement, yet more powerful and scalable.

For an in-depth analysis of what the Talend Integration Factory offers, see Christian Schneider's blog entry here. For some other comments on this release, see here and here.

[WSS4J 1.6] Changes to the Crypto interface

2011-02-23T08:53:00.000-08:00

WSS4J uses the Crypto interface to provide a pluggable way of retrieving and converting certificates, verifying trust on certificates etc. A previous blog post described how verifying trust on PublicKeys was also moved into the Crypto interface for WSS4J 1.6.

WSS4J 1.5.x shipped with a Crypto implementation based around a KeyStore, which was configured via a properties file. A previous blog post describes some changes that were made to the property config names, as well as describing the separation between a keystore and a truststore. The code was also modified as part of this work so that the Crypto instance can be instantiated as normal, and not just via a properties file.

A big issue with the Crypto interface is that it was too closely tied in to the Java KeyStore objects which back the Merlin implementation. This makes it difficult to subclass the interface, for example to write a Crypto implementation that just stores an array of X509Certificates for signature verification, or to write a client to obtain the X509Certificates from a remote store (e.g. XKMS).

The fix for WSS-269 attempts to address these shortcomings. All of the KeyStore specific method names and arguments have been abstracted. All of the methods which locate X509Certificates have been consolidated into a single method, which takes an argument a new class which supplies the data (e.g. a SHA1 thumbprint of the certificate) used to retrieve the certificates. The abstract functionality (i.e. KeyStore independent) has been moved into the CryptoBase class, so implementation can just subclass this to avoid having to re-implement all of the generic methods in the Crypto interface.

WSS4J now ships with another Crypto implementation. CertificateStore holds an array of X509Certificates that can be used out of the box, for signature verification, or encryption. The PrivateKey methods are not implemented, so it cannot be used for decryption, or signature creation. However, CertificateStore could easily be subclassed.

[WSS4J 1.6] Change to PublicKey validation

2011-02-21T04:27:00.000-08:00

This entry describes a relatively minor change to how trust validation is performed on PublicKeys in WSS4J 1.6.

When the KeyInfo element of a Signature does not have a SecurityTokenReference child, WSS4J tries to extract a PublicKey via a KeyValue child. In WSS4J 1.5.x, it then constructed a PublicKeyCallback instance, passing it the PublicKey object, and invoked the CallbackHandler. It then called a "isVerified" method on the Callback to check to see whether the CallbackHandler had verified the PublicKey or not. The CallbackHandler implementation needed to call the "verifyTrust" method on the PublicKeyCallback, passing in a KeyStore object. This method iterates through each Certificate in the KeyStore, and checks to see whether the PublicKeys match.

There are a number of problems with this approach:

It is inconsistent with how Certificate validation is done (i.e. via a Crypto object).
It relies on the CallbackHandler implementation calling "verifyTrust" on the Callback object, thus putting the onus on the end-user to write the CallbackHandler implementation properly.

As part of the fix for WSS-266, the PublicKeyCallback class was removed from WSS4J. Instead, the "verifyTrust" method was moved to the Crypto interface, whether the argument is now a PublicKey object, rather than a KeyStore. In this way, validation is done in the same way as for Certificates, and the end-user has no need to consider the special-case of verifying public keys in the CallbackHandler, it is taken care of internally by WSS4J.

[WSS4J 1.6] Specifying elements to sign or encrypt

2011-02-18T08:16:00.000-08:00

The signature and encryption creation code in WSS4J uses the WSEncryptionPart class to find DOM elements to sign and encrypt. There are a number of minor changes to how elements are located from a WSEncryptionPart in WSS4J 1.6:

WSEncryptionPart now stores an optional DOM element, which will be used as the element to sign/encrypt if it is non-null.
Failing this, it finds the SOAP body and compares the wsu:Id with the stored Id, or if there is no stored Id in WSEncryptionPart, it checks the stored localname/namespace.
Failing this, if the stored Id in WSEncryptionPart is not null, it tries to find the first element in the SOAP envelope that has a matching wsu:Id.
If the stored Id is null, it tries to find *all* DOM Elements that match the stored localname/namespace.

WSEncryptionPart is intended to refer to a single Element for encryption/signature. However, as a localname/namespace is not necessarily unique, point 4 will return all matching Elements. An important implication of the order of the steps given above, is that client code should set the DOM element on the WSEncryptionPart if it is accessible, and if not, it should set the wsu:Id. Otherwise, a localname/namespace (which is not referring to the SOAP Body) will result in a traversal of the DOM tree.

The DOM element(s) that is(are) found are stored for retrieval, so that we don't need to traverse the SOAP envelope multiple times, when e.g. doing an STR Transform, or for element location in the XML Security code.

WSPasswordCallback changes in WSS4J 1.6

2011-02-08T05:22:00.000-08:00

Following the previous post on Username Token processing changes in WSS4J 1.6, this post gives some additional details on related changes that have been made to the WSPasswordCallback class in WSS4J.

WSPasswordCallback defines a set of integers which correspond to usage instructions for the CallbackHandler. In WSS4J 1.5.x they were often used in an inconsistent or ad hoc manner, leading to confusion for users. The following integers have been deprecated in WSS4J 1.6 and are no longer used internally by WSS4J:

WSPasswordCallback.KEY_NAME
WSPasswordCallback.USERNAME_TOKEN_UNKNOWN
WSPasswordCallback.ENCRYPTED_KEY_TOKEN

In WSS4J 1.6, the following WSPasswordCallback identifiers are used:

WSPasswordCallback.DECRYPT - DECRYPT usage is used when the calling code needs a password to get the private key of this identifier (alias) from a keystore. This is only used for the inbound case of decrypting a session (symmetric) key, and not for the case of getting a private key to sign the message. The CallbackHandler must set the password via the setPassword(String) method.
WSPasswordCallback.USERNAME_TOKEN - USERNAME_TOKEN usage is used to obtain a password for either creating a Username Token, or for validating it. It is also used for the case of deriving a key from a Username Token. The CallbackHandler must set the password via the setPassword(String) method.
WSPasswordCallback.SIGNATURE - SIGNATURE usage is used on the outbound side only, to get a password to get the private key of this identifier (alias) from a keystore. The CallbackHandler must set the password via the setPassword(String) method.
WSPasswordCallback.SECURITY_CONTEXT_TOKEN - SECURITY_CONTEXT_TOKEN usage is for the case of when we want the CallbackHandler to supply the key associated with a SecurityContextToken. The CallbackHandler must set the key via the setKey(byte[]) method.
WSPasswordCallback.CUSTOM_TOKEN - CUSTOM_TOKEN usage is used for the case that we want the CallbackHandler to supply a token as a DOM Element. For example, this is used for the case of a reference to a SAML Assertion or Security Context Token that is not in the message. The CallbackHandler must set the token via the setCustomToken(Element) method.
WSPasswordCallback.SECRET_KEY - SECRET_KEY usage is used for the case that we want to obtain a secret key for encryption or signature on the outbound side, or for decryption or verification on the inbound side. The CallbackHandler must set the key via the setKey(byte[]) method.

The DECRYPT, SIGNATURE and SECURITY_CONTEXT_TOKEN identifiers are used more or less the same as they were used in WSS4J 1.5.x. The CUSTOM_TOKEN identifier is also used in a similar way, apart from the fact that some of the processors incorrectly used it to obtain a secret key. The changes to USERNAME_TOKEN were covered in a previous blog post.

SECRET_KEY is a new identifier for finding secret keys. It replaces the occasionally incorrect use of CUSTOM_TOKEN, as well as KEY_NAME and ENCRYPTED_KEY_TOKEN.

UsernameToken processing changes in WSS4J 1.6

2011-02-04T06:09:00.000-08:00

The forthcoming WSS4J 1.6 release contains some significant changes relating to how wsse UsernameTokens are processed. In WSS4J 1.5.x, the following processing rules applied:

For a digest password, the CallbackHandler implementation was given the username and an identifier of WSPasswordCallback.USERNAME_TOKEN. It was then expected to set the password on the callback, and the processor did the comparison.
For a plaintext password, the CallbackHandler implementation was given the username, password, and an identifier of WSPasswordCallback.USERNAME_TOKEN_UNKNOWN, and was expected to do all validation of the plaintext password itself, throwing an exception if validation failed.
For a password of some unspecified non-standard type, WSS4J would throw an exception by default. However, if wssConfig.getHandleCustomPasswordTypes() returned true, then it would again dispatch the username, password, and an identifier of WSPasswordCallback.USERNAME_TOKEN_UNKNOWN to the CallbackHandler implementation for validation.
For the case of a UsernameToken with no password element, it would again dispatch the username, password, and an identifier of WSPasswordCallback.USERNAME_TOKEN_UNKNOWN to the CallbackHandler implementation for validation.

The reason that the processor does not validate the plaintext password, as per the digest case, is to accommodate dispatching the username/password to (for example) a directory store for authentication. The custom password type is treated as a separate case namely for WCF interoperability (see here).

There are ~~a couple of~~ several obvious problems with this set-up:

The standard plaintext password case is treated exactly the same as a non-standard password type, or the case of no password at all, by sending the callback handler a type of WSPasswordCallback.USERNAME_TOKEN_UNKNOWN.
The treatment of passwords for both the standard digest and plaintext cases are inconsistent.
A potential security hole exists where the user may not be aware that the CallbackHandler implementation *must* throw an exception on WSPasswordCallback.USERNAME_TOKEN_UNKNOWN when the password is not recognised.
The CallbackHandler interface is being used in a non-standard way - it is only meant to supply a password, not do the validation.
UsernameTokens with no password (i.e. used for key derivation) are stored using the same result (WSConstants.UT) as UsernameTokens that have been validated. This could lead to a security hole where a user assumes that because a UsernameToken has been processed, password validation has taken place.

WSS4J 1.6 fixes these issues, at the cost of breaking backwards compatibility in terms of the semantics of the CallbackHandler implementation. The UsernameTokenProcessor now does no validation of the password, beyond making sure it is well formed. A new Validator implementation (more on this at a later date) does the validation of the token. The default behaviour is as follows:

For the digest case, the CallbackHandler is given the username, password type and an identifier of WSPasswordCallback.USERNAME_TOKEN. It must set the password on the callback, and the validator does the comparison. This is the same as the old behaviour.
The plaintext case has exactly the same behaviour as the digest case. The identifier is now WSPasswordCallback.USERNAME_TOKEN and not WSPasswordCallback.USERNAME_TOKEN_UNKNOWN, and the CallbackHandler does not do any authentication, but must set the password on the callback.
The custom password type case defaults to the same behaviour as the plaintext case, assuming wssConfig.getHandleCustomPasswordTypes() returns true.
For the case of a username token with no password element, the default behaviour is simply to ignore it, and to store it as a new result of type WSConstants.UT_NOPASSWORD.

So we now have the correct use of the CallbackHandler interface - it does no authentication, and is only used to retrieve password for validation. The plaintext and digest cases are treated the same way by default. There is no security hole in that the user does not need to throw exceptions in the CallbackHandler implementation for various cases. Also, the case of no password at all is not validated, but is stored as a separate type, for use by other processors to derive keys for decryption or signature verification.

So what if you want to validate the plaintext password against a directory store, rather than have the CallbackHandler set the password? Instead of implementing this behaviour in your CallbackHandler implementation, you can simply @Override the verifyPlaintextPassword(UsernameToken usernameToken) method in the validator instead. By simply plugging in a validator on the UsernameTokenProcessor (such as the NoOpValidator), it is possible to do any kind of custom validation (or none at all) on the token. This is a much better solution than having to write a custom processor, and replace the existing UsernameTokenProcessor.

Support for SAML2 assertions in WSS4J 1.6

2011-02-02T06:43:00.000-08:00

Support for SAML2 assertions has finally arrived in WSS4J, via the forthcoming 1.6 release. This has been a long-standing feature request (see here). WSS4J 1.5.x only supports SAML 1.1 assertions via the deprecated Opensaml1, and it supports them in a very limited manner, namely:

It only supports the creation of Authentication statements.
Processing essentially involves saving the assertions, it did not support validating enveloped signatures, or trust on the signatures, etc.

Several patches were submitted to WSS-146 to upgrade WSS4J to use Opensaml2. I took a patch from Todd Michael Dunst as a starting point for the port, as his patch had the nice idea of using a CallbackHandler implementation to construct outbound SAML assertions. About a months work later (mainly in testing, refactoring, and porting the patch to trunk) the SAML2 port is more or less ready on trunk. SAML2 support in WSS4J 1.6 consists of:

Support for creating signed/unsigned SAML 1.1/2.0 assertions, containing authentication, authorization, attribute statements etc.
This extensibility is achieved by letting the user implement a CallbackHandler instance.
The SAMLTokenProcessor can now process any type of assertion, verify an enveloped signature on it, and verify trust on the signature. It also verifies some holder-of-key requirements, e.g. that the Subject contains a KeyInfo element, and that the assertion is signed and trusted etc.

WSS4J 1.6 contains an extensive set of tests for both creating and processing different type of assertions, you can browse them here. To illustrate the flexibility and simplicity of the CallbackHandler approach for constructing assertions, take a look at an abstract CallbackHandler here, as well as the concrete implementations (SAML 1.1 and SAML 2). As you can see, a fairly small amount of code can create a large variety of assertions.

Opensaml2 has a very large set of dependencies, but through some judicious pom exclusions, as well replacing the Opensaml DefaultBootstrap code to avoid loading velocity, the following dependencies are introduced in WSS4J via Opensaml (snippet from mvn dependency):

+- org.opensaml:opensaml:jar:2.4.1:compile
| \- org.opensaml:openws:jar:1.4.1:compile
|     \- org.opensaml:xmltooling:jar:1.3.1:compile
|        +- org.slf4j:slf4j-api:jar:1.6.1:compile
|        \- joda-time:joda-time:jar:1.6.2:compile

The WSS4J 1.6 pom currently has a dependency on the Shibboleth repo, where the Opensaml2 artifacts live. I plan on getting the Opensaml2 artifacts into Maven central in time for the 1.6 release - this is slightly complicated by the fact that some of the Opensaml2 dependencies are themselves not in Maven Central.

One known issue is that WSS4J cannot create an Assertion which has an EncryptedKey element in the Subject. This is due to a bug in Opensaml2 which has been fixed, but not released yet.

The Opensaml2 port has a large impact on existing code for *creating* assertions, however I suspect that very few people used that code. It has a minimal impact on existing code for processing assertions, with several caveats:

WSS4J 1.5.x ignored (enveloped) signatures on SAML (1.1) assertions - this is no longer the case, so deployments which do not set the correct keystore/truststore config for dealing with signature verification will fail
The SAMLTokenProcessor no longer saves all tokens as an "WSConstants.ST_UNSIGNED" action. It saves tokens that do not have an enveloped signature as this action, and token which *do* have an enveloped signature are saved as a "WSConstants.ST_SIGNED" action.
The object that is saved as part of the action above has changed, from an Opensaml1 specific Assertion object, to an AssertionWrapper instance, which is a WSS4J specific object which encapsulates an Assertion, as well as some information corresponding to signature verification, etc.

[WSS4J 1.6] Action/Processor loading change

2011-01-07T04:02:00.000-08:00

Following on from yesterday's post about changes to crypto property files in WSS4J 1.6, this post details some changes that have been made to how Actions and Processors are loaded in WSS4J. These changes do not affect the end user per se, apart from the case of adding custom Actions or Processors, but are probably important enough to take note of.

In WSS4J 1.5.x, WSSConfig stores a <QName, String> map of default Processors. On processing a security header, it tries to match the QName of the child elements with the Map keys, and then uses the corresponding Map value to load the Processor class and then create a new instance of it.

The problem with this approach is that every time a message is received, each processor that is required gets class loaded again, which is highly inefficient. See this JIRA for more details. The same problem also exists for Action classes that are also loaded by WSSConfig.

The simple solution is to change the default Action/Processor maps in WSSConfig to store Class instances rather than Strings. Each time an Action/Processor object is required, it is simply created with <Class>.newInstance(). It is still possible to add custom Action/Processor objects to the custom Action/Processor maps. It is claimed in the JIRA above that:

The patch brings a massive performance enhancement, at least in the jetty-environment (I didn't test other application server) due to not looking up the classes on every invocation. The CPU-time of the wss4j library went from ~50% down to 2%.

[WSS4J 1.6] Crypto property change

2011-01-06T07:51:00.000-08:00

One of my goals for this blog is to document ongoing changes to the forthcoming WSS4J 1.6 release. This way I will be able to collate all of the entries into a single resource to put on the WSS4J website. I'm mainly going to focus on changes that affect the end-user, as the internal changes are too numerous to mention. Note that these blog posts are not intended to be definitive, as certain things may change before the release goes out.

This entry focuses on some changes to the Crypto property files. These files are used to load keys and certificates for various WS-Security operations, and are loaded by the CryptoFactory class. CryptoFactory parses a single property in the file:

org.apache.ws.security.crypto.provider - WSS4J specific provider used to create Crypto instances (default value is "org.apache.ws.security.components.crypto.Merlin").

WSS4J 1.6 will only ship with this provider, WSS4J 1.5.x ships with a (largely redundant) BouncyCastle provider as well. The rest of the crypto property file is parsed by AbstractCrypto. The old configuration tags that were available in WSS4J 1.5.x are:

org.apache.ws.security.crypto.merlin.file - location of keystore
org.apache.ws.security.crypto.merlin.keystore.provider - provider of keystore
org.apache.ws.security.crypto.merlin.keystore.password - password used to load keystore
org.apache.ws.security.crypto.merlin.keystore.type - type of keystore (defaults to java.security.KeyStore.getDefaultType())
org.apache.ws.security.crypto.merlin.load.cacerts - whether to load the CA certs in ${java.home}/lib/security/cacerts or not (default is true)
org.apache.ws.security.crypto.merlin.cacerts.password - the password to use to load the CA certs (default is "changeit")
org.apache.ws.security.crypto.merlin.cert.provider - the provider to use to load certificates
org.apache.ws.security.crypto.merlin.keystore.alias - the default keystore alias to use, if none is specified

There are a number of issues with the old configuration values. The Java CA certs were loaded by default (for backwards compatiblity reasons), which slows things down if they're not needed. Secondly, there is no clean separation of the keystore used to obtain private/secret keys, and that used to verify trust on received credentials. Thirdly, some of the config tag names are inconsistent. The new crypto property tags for WSS4J 1.6 are as follows:

Provider tags:

org.apache.ws.security.crypto.merlin.keystore.provider - the provider used to load keystores (including the truststore)
org.apache.ws.security.crypto.merlin.cert.provider - the provider used to load certificates

These are identical to the 1.5.x provider tags.

KeyStore tags:

org.apache.ws.security.crypto.merlin.keystore.file - location of keystore
org.apache.ws.security.crypto.merlin.keystore.password - password used to load keystore
org.apache.ws.security.crypto.merlin.keystore.type - type of keystore (defaults to java.security.KeyStore.getDefaultType())
org.apache.ws.security.crypto.merlin.keystore.alias - the default keystore alias to use, if none is specified

Note that this is identical to the 1.5.x tags, apart from the location of the keystore file. This value falls back to the old value of "org.apache.ws.security.crypto.merlin.file" if it is not specified.

Truststore Tags:

org.apache.ws.security.crypto.merlin.load.cacerts - whether to load the CA certs in ${java.home}/lib/security/cacerts or not (default is false)
org.apache.ws.security.crypto.merlin.truststore.file - location of truststore
org.apache.ws.security.crypto.merlin.truststore.password - truststore password (default value is "changeit")
org.apache.ws.security.crypto.merlin.truststore.type - truststore type (defaults to java.security.KeyStore.getDefaultType())

Note that the Java CA certs are not now loaded by default. It is now possible to specify the keystore to be used as the truststore, as well as the password used to load the truststore, and the truststore type. It is not possible to both load a truststore and use the JDK CA Certs.

One final note - when building a validation chain to validate a received credential, WSS4J uses both the truststore and the keystore. This is for backwards compatibility reasons, where the user does not specify a truststore using the new config. The previous sentence applies to WSS4J 1.6.0, but does not apply from WSS4J 1.6.1 onwards. From WSS4J 1.6.1, WSS4J only uses the truststore when building a validation chain if it is specified. If it is not specified, then it falls back to using the keystore. See this issue for more details.

CXF/Metro WS-Trust interop

2010-12-22T04:03:00.000-08:00

Glen Mazza has done some excellent work on creating and documenting an example of how to use CXF to obtain a SAML token from a Metro STS and use it to invoke on a Metro endpoint. Unfortunately, it didn't work for a number of reasons:

The Metro endpoint objected to the fact that the CXF client was using a wsse:Reference to the SAML Assertion instead of a wsse:KeyIdentifier. This was a bug in WSS4J, and was fixed as part of WSS-238.
The CXF client could not decrypt the response from the Metro endpoint. As part of the fix for WSS-238, support was added for processing an EncryptedKey that points to a SAML Assertion containing an X509Certificate, and an EncryptedData token that points to a SAML Assertion containing an EncryptedKey.
The CXF client could not handle a reference to a SAML Assertion which was not in the SOAP request. This scenario occurred as the endpoint had the "AlwaysToRecipient" policy configured. This was fixed as part of WSS-260.

The good news is that using the latest WSS4J 1.5.11-SNAPSHOT the interop test-case works. This is an important initial milestone in the improving interoperability with third party WS-Trust implementations.

This kind of interop testing is vital and we have a lot of work planned in this regard.

New Santuario / XML Security releases

2010-12-21T03:02:00.000-08:00

There have been two new releases in the last month or so in Santuario / XML Security.

XML Security (Java) 1.4.4 was released in November. This release contains some enhancements to the resolver API's. It also fixes some longstanding issues with interned Strings, as well as a number of bug fixes.

XML Security (C++) 1.6.0 was released in December. This release provides many bug fixes and a partial implementation of XML Signature 1.1 features, including ECDSA signatures.

You can download both releases here.

Talend Service Factory CE released

2010-12-21T02:55:00.000-08:00

The first release of the Talend Service Factory CE has been announced. For more information see here:

Talend Service Factory Community Edition provides users with an easy-to-use solution for service enablement. Based on the leading Apache projects for web services and OSGi, Talend Service Factory provides a fully certified and tested solution with support from the same key Apache developers that build the software. Service Factory embodies the key benefits of OSGi namely modular software development and Service Lifecycle management.
Talend Service Factory Community Edition is an open, lightweight and flexible architecture based on Apache CXF and Apache Karaf, and is provided as a single, pre-configured package that enables developers to quickly build and deploy SOAP and REST Web Services, be it on Tomcat, Jetty, Equinox, Felix or your favorite JEE Web Server.

Check out the comments of Dan Kulp, Sergey Beryozkin and Glen Mazza on this release. As Dan says, we have big plans for 2011, particularly some exciting things in the security area, so stay tuned.

First post...

2010-12-09T03:37:00.000-08:00

I'm planning to use this blog to detail the security-related work I'm doing and planning to do on various open source projects.

I am the lead-developer on the forthcoming WSS4J 1.6 release, which has a (very) tentative release date of the end of Q1 2011. WSS4J 1.5.x has successfully provided the Web Service Security layer that underpins several Web Services Stacks, such as CXF and AXIS. However, WSS4J 1.5.x is showing its age, both in terms of functionality and performance, both problems which will be addressed in the forthcoming 1.6 release. Although WSS4J 1.6 will not be 100% backwards compatible with 1.5.x, a general goal for the release is to restrict the API changes to those that are strictly necessary. The WS-Security module in CXF has already been ported to use WSS4J 1.6-SNAPSHOT, you can see this code here.

The best way to keep track of what has already been done for WSS4J 1.6, and what remains to be done, is to take a look at the JIRA. There are three main areas of improvement. Firstly, WSS4J has been ported to use the JSR 105 API for XML Digital Signature. This task is more or less complete, although WSS4J retains some compile-time dependencies on XML Security for some of the trickier manipulations (such as Security Token Reference transforms), as well as for encryption/decryption. Secondly, WSS4J 1.6 will include the port to Opensaml 2, thus giving WSS4J the ability to create, parse and manipulate SAML 2 assertions. Thirdly, a huge amount of work has gone into a general code-rewrite with a focus on performance. The JDK 1.4 requirement has been dropped as part of this work, along with the old Axis1 dependencies.

As part of the JSR-105 port for WSS4J 1.6, it is possible to use the implementation in the JDK 1.6 with WSS4J to provide signature creation/verification functionality. However, WSS4J still relies on the Santuario (aka XML Security) project for some of the more advanced signature functionality, as well as in other areas (outlined above). Santuario 1.4.4 was recently released, and a 1.5 release is scheduled for next year (possibly Q2). There is ongoing debate among the Santuario team as to what features 1.5 will provide. A main focus will definitely be a code rewrite to improve performance.