Background

The implementation of the facade for Axis uses WSS4J to check signatures on incoming messages. The check is made with a certificate chain contained in the message header and a set of trust-anchor certificates configured into the service. The service provider knows and trusts the certificate authorities represented by the trust anchors but need not know a priori the names of individual users.

The signatures are checked by an Axis handler, and a special sub-class of SecurityGuard, AxisClientSecurityGuard is provided by which the authenticated identity can be extracted from that handler. Axis requires that the security handler be created when its 'Axis engine' in the service is first created.

Setting the trust anchors

The service must be provided with a set of trust-anchor certificates written in PEM format. Each certificate is stored in a .pem file. There is a naming convention: the name of each file must be the hash value of the certificate it contains, suffixed with .0. In the unlikely event of certificates having the same has value, one should instead be given the suffix .1, .2, etc. as necessary to produce unique names.

The certificates should be grouped in directories. Ideally, just one directory contains all the trust anchors. Grid conventions, set by the Globus toolkit, say that the directory should be /etc/grid-security/certificates.

Configuring the Axis handler

The handler should be declared in the WSDD deployment-descriptor for the service. This is an example of a service configured with the handler.

  			
<service name="SamplePort" provider="java:RPC">
  <parameter name="className" value="org.astrogrid.security.sample.SampleImpl"/>
  	<requestFlow>
  		<handler type="java:org.astrogrid.security.AxisServiceCredentialHandler"/>
  	</requestFlow>
  </service>
  			

The type (class) of the handler must be exactly as shown above.

Supporting jars

Your service will need a number of additional jars in order to operate the security handlers.

astrogrid-security.jar

Contains the security facade including the handler org.astrogrid.security.AxisServiceCredentialHandler which you declared in the WSDD file.

xmlsec.jar (version 1.2.1 or later)

Contains the code for digital signature on XML.

bcprov.jar ("the bouncy-castle jar"; version jdk13-128)

Contains the cryptographic algorithms used in digital signature.

cog-jglobus.jar (version 1.2)

Contains the code from the Java CoG kit for checking certificate chains.

cog-puretls.jar (version 1.2)

Supports cog-jglobus.jar.

Authentication semantics

Once configured as above, the service attempts to authenticate the sender of each incoming message. It is not possible to apply authentication to a sub-set of operations on the service.

If a request is authenticated, then the authenticated identity is logged and stored for the use of authorization code. If authentication fails, or if the request is anonymous, then the situation is logged and no fault is thrown. I.e. the handler does not reject requests because of failed authentication.

Retrieving the authenticated identity

Authorization code can retrieve the results of authentication by asking for a service security-guard.

 import javax.security.auth.x500.X500Principal;
 import org.astrogrid.security.AxisServiceSecurityGuard;
 AxisServiceSecurityGuard guard = AxisServiceSecurityGuard.getInstanceFromContext();
 if (guard.isAnonymous()) {
   ...
 }
 else {
   X500Principal p = guard.getX500Principal();
   ...
 }