[WSS4J 1.6] SAML property changes

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

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

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

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.