A client should use the ClientSecurityGuard class to do authentication: this is the client-side facade. The client may also need to use the classes representing credentials: Password, AccountName and NonceToken. The client should not call directly the other classes of the security package; they are only for internal use.
The ClientSecurityGuard holds credentials for the application and makes them available in SOAP messages. A client should create a ClientSecurityGuard and populate it with credentials, as described in the following sections. The client may use one ClientSecurityGuard for any number of messages, or may use a different guard for each message. The former case is the most common; the latter case applies if the application wishes to use different credentials (possibly a different identity) in each message.
The security guard distinguishes "single-sign-on" (SSO) credentials from "grid" credentials. The SSO credentials are used to sign on to the entire system (viewed as a grid of services) and thereby to obtain grid credentials. The grid credentials are used to authenticate messages to services. The guard keeps the two sets of credentials separately.
A client creates a ClientSecurityGuard using the static, abstract-factory method ClientSecurityGuard.getInstance(). The constructor is protected and thus not available to the client application. The abstract factory allows the facade to return a subclass of ClientSecurityGuard that is suited to the system of the day, as determined from some system configuration hidden from the application. Thus, the security system can evolve without disturbing the application code. After construction, the guard is empty, holding no identities and no credentials.
The client must add identities and credentials to the guard before using it to secure messages. This is normally done by setting a single-sign-on username and password, as described in the following section. The guard can then sign on to the grid and acquire other credentials for itself.
Alternatively, the client may set credentials and identities directly. The convenience methods getSsoSubject and getGridSubject return the JAAS subjects in which the guard stores all identities and credentials. Changing the SSO Subject changes the way in which the guard signs on to the grid chaging the grid Subject changes the guard secures messages to services. Please refer to the JAAS documentation for details of the Subject class. The current implemenation of the security facade uses AccountNames as JAAS Principals and NonceTokens as private credentials. No public credentials are used. The textual value of an AccountName must match the standard for an IVORN.
The client may use the same ClientSecurityGuard from multiple threads.
To sign on to the grid, a client should set the account name and password on the ClientSecurityGuard, using the setSsoUsername and setSsoPassword methods, and then call the signOn method on the guard. The username must be an IVORN referring to a user in a Community, as understood by the AstroGrid community service.
Calling signOn() contacts the community service for the named account; the security system works out for itself which service must be contacted. The community service is located with the help of a registry service. The registry service must be identified in the system configuration. The configuration, which is managed by the org.astrogrid.config package, consists in a set of porperties given as name-value pairs; it is based on the Java properties system. The property org.astrogrid.registry.query.endpoint must be set to the URL of the web-service endpoint for the registry.
If the user is known to the community, and if the password is correct, a NonceToken is returned and retained in the ClientSecurityGuard as a credential. The application may retrieve this security token, but in general it does not need to do so. The token need not be extracted from the guard for it to be used in messaging.
To apply the credentials to messages, an application calls mountGuard() on the ClientSecurityGuard, passing a JAX-RPC Service object as an argument and the qualified name of the web-service endpoint (or "port") as a second argument. All messages sent to that endpoint will then will then be annotated with the credentials in the ClientSecurityGuard, provided that the application accesses the endpoint via the given Service object.
Once a guard is mounted on an endpoint via a Service object, all Call objects generated by the Service object are also guarded. This means that requests to the endpoint made from those Calls are annotated with credentials upon transmission.
Stubs generated by WSDL2Java implements the Service interface, so can be used with the ClientSecurityGuard. To make this work, the application must set the name of the WSDL port on the stub before calling mountGuard() on the ClientSecurityGuard. If this is not done, the handlers for the credentials are not triggered. To do this, the application should type-cast the Stub to org.apache.axis.client.Stub and call the setPortName method. Alternatively, the author of the stub can change its code to set the port name internally. Ultimately, we might hope for WSDL2Java to set the port name in all generated stubs.