GT 4.2.1 Java WS A&A Developer's Guide

Features new in GT 4.2.1

None.

Other Supported Features

Deprecated Features

Features new in GT 4.2.1:

Other Supported Features

Deprecated Features

Since GT 4.0.x release, some incompatible changes have been made:

The authorization framework has been reworked as described in Change Summary. The configuration and authorization interfaces have since changed and a Migration Guide is provided.

The toolkit by default is deployed with our implementation of transport security, which is based on HTTP over SSL, also known as HTTPS, with modifications to path validation to enable X.509 Proxy Certificate support. In contrast to the GT3 version of the toolkit, the default transport security enabled in the toolkit does not support delegation of proxy certificates as part of the security handshake.

However, the underlying security libraries and handlers required for secure transport with delegation, also known as HTTPG, is still supported and shipped as part of the CoG library. The GT4 Java WS code base and configuration can be modified to use the HTTPG protocol as required.

Transport security is implemented by layering on top of the GSISocket class provided in JGlobus. This class deals with the security-related aspects of connection establishment as well as message protection. The socket interface serves as an abstraction layer that allows the HTTP protocol handling code to be unaware of the underlying security properties of the connection.

Container-level credentials are required and, irrespective of security settings on the service being accessed, these credentials are used for the handshake.

The Java WS Authorization framework leverages the generic GT Java Authorization Framework. The framework consists of an engine that evaluates a chain of configured authorization schemes, also known as Policy Decision Points (PDPs), to determine if the client making the invocation can access the resource/service. The chain can also be configured with Policy Information Points (PIPs), which can be used to glean information that would be useful in the decision making process.

A subset of PIPs that collect information only about the request i.e. the peer subject, requested action and resource, are called Bootstrap PIP. Typically these PIPs are run first in the authorization evaluation process, to build the request context.

The framework enables attribute-based authorization. PIPs can be used to collect attributes about resource/operations/subjects and used in the decision making process. While the toolkit provides some implementations of PIPs/PDPs, the framework is pluggable and custom mechanisms can be written and configured.

An authorization engine consists of PIPs, PDPs and a combining algorithm. The configured authorization engine is invoked as part of a handler chain, immediately after authentication of the invocation (java:org.globus.wsrf.impl.security.authorization.AuthorizationHandler). If no security mechanism is used for an operation, authorization is not done for that operation.

The architecture of Generic Java Authorization Engine is described in detail in this document. It also describes interfaces and writing custom PDPs/PIPs.

Any PDP has to implement the interface org.globus.security.authorization.PDP and contain the logic to return a permit or deny based on information such as the subject DN, the service being accessed and the operation being performed. To manage configuration information, each PDP can be bootstrapped with an object implementing the org.globus.security.authorization.ChainConfig interface. The interface has get and set methods which can be used to retrieve and set scoped parameters for the PDP.

PIPs have to implement the interface org.globus.security.authorization.PIP with the functionality to collect attributes from the invocation context that are relevant to making the authorization decision.

Client side authorization is done as a part of the authentication handler. GSI Secure Message authentication does client-side authorization only after the operation is completed. This is done as a part of the web services client handler. The other two authentication schemes supported, GSI Secure Conversation and GSI Transport, authorize the server during the handshake, prior to the operation invocation.

The Transport Level Security protocol allows for authorization (an expected DN comparison) during the handshake. This is disabled by default in the toolkit, unless delegation of credential is requested. If no delegation is requested, the configured authorization mechanism is invoked afer the handshake is complete, prior to the operation invocation. If delegation is requested, authorization (expected DN comparison) is done during key exchange as a part of the protocol.

The toolkit supports self, gridmap, host and identity authorization on the client side. The authorization to be used is set programmatically on the Stub and the handler enforces it.

This service provides a mechanism for generating a security session, i.e the negotiation of a shared secret which may be used to secure a set of subsequent messages. It is based on the WS-Trust and WS-SecureConversation specifications.

<xs:element name='RequestSecurityToken'>
   <xs:complexType name='RequestSecurityTokenType'>
      <xs:sequence>
         <xs:element ref='wst:TokenType'/>
         <xs:element ref='wst:RequestType'/>
         <xs:element ref='wst:BinaryExchange'/>
      </xs:sequence>
      <xs:attribute name='Context' type='xs:anyURI'/>
   </xs:complexType>
</xs:element>

<xs:element name='RequestSecurityTokenResponse'>
   <xs:complexType name='RequestSecurityTokenResponseType'>
      <xs:sequence>
         <xs:element ref='wst:TokenType'/>
         <xs:element ref='wst:RequestType'/>
         <xs:element ref='wst:BinaryExchange'/>
      </xs:sequence>
      <xs:attribute name='Context' type='xs:anyURI'/>
   </xs:complexType>
</xs:element>

<xs:element name='RequestSecurityTokenResponse'>
   <xs:complexType name='RequestSecurityTokenResponseType'>
      <xs:sequence>
         <xs:element ref='wst:TokenType'/>
         <xs:element ref='wst:RequestType'/>
         <xs:element ref='wst:BinaryExchange'/>
      </xs:sequence>
      <xs:attribute name='Context' type='xs:anyURI'/>
   </xs:complexType>
</xs:element>
 
<xs:element name='RequestSecurityTokenResponse'>
   <xs:complexType name='RequestSecurityTokenResponseType'>
      <xs:sequence>
         <xs:element ref='wst:TokenType'/>
         <xs:element ref='wst:RequestType'/>
         <xs:element ref='wst:BinaryExchange'
                     minOccurs="0"/>
         <xs:element ref='wsc:SecurityContextToken'/>
      </xs:sequence>
      <xs:attribute name='Context' type='xs:anyURI'/>
   </xs:complexType>
</xs:element>  

In the above schema, the second RequestSecurityTokenResponse element refers to the final message in the exchange.

This service has no associated resource properties.

Both RequestSecurityToken and RequestSecurityTokenResponse throw the following faults:

The authorization service takes a query as input and returns an authorization decision. The Security Assertion Markup Language (SAML) is used for expressing the query and the decision. If any fault occurs, it is embedded as a part of the decision. The decision can be a permit, deny or indeterminate.

The property to use depends on the authentication scheme:

Other than the distributed client authorization scheme, custom client-side authorization schemes can be written and can be set as the value for the appropriate property on the stub.

	Note
	Security descriptors cannot be used to configure custom authorization schemes on the client side.

The server side authorization framework can be configured to use custom authorization interceptors, bootstrap PIP, PIP and PDP. Detailed information on writing custom PDPs can be found in GT Java Authorization Framework. Also, the section Section 1, “Migrating Java WS Authorization Framework from GT 4.0” describes migrating from older PDP/PIP implementations.

For example, a custom PDP must implement the interface org.globus.security.authorization.PDP.

Example:

package org.foobar;

import ....;

public class FooPDP implements PDP
{
    private Principal authorizedIdentity;


    public Decision canAccess(RequestEntity requestEntity,
                              NonRequestEntity nonRequestEntity)
        throws AuthorizationException {
        
        // process and return decision
    }

    public Decision canAdminister(RequestEntity requestEntity,
                                  NonRequestEntity nonRequestEntity)
        throws AuthorizationException {

        // process and return decision
    }

}

To use the above PDP one would configure a service security descriptor with the following authorization settings:

<securityConfig xmlns="http://www.globus.org">
   ...
   <authz value="foo1:org.foobar.FooPDP"/>
   ...
<securityConfig/>

This security descriptor (identified as /.../foo-pdp-security-config.xml below) can then be used by a service. The association is created by adding a couple of parameters to the service's WSDD entry:

...
<service name="MyDummyService" 
             provider="Handler" 
             style="document">
   ...
   <parameter name="securityDescriptor" 
                     value="/.../foo-pdp-security-config.xml"/>
   <parameter name="foo1-authorizedIdentity" 
                     value="/DC=org/DC=doe/OU=People/CN=John D"/>
   ...
</service>

Note that the parameter <parameter>foo1-authorizedIdentity</parameter> in the above configures the identity the PDP uses for authorizing incoming requests. The parameter name is derived by composing the prefix (<parameter>foo1</parameter>) used when specifying the PDP in the security descriptor with the property (<parameter>authorizedIdentity</parameter>) used in the PDP code.

Security descriptors are mechanisms used to configure authorization mechanism and policy. The authorization on the server side can be configured at the container, service or resource level.

On the client side, authorization can be configured using security descriptors or as a property on the stub. This configuration can be done on a per invocation granularity

The server side authorization can be configured at the container, service or resource level using

To write and configure a server-side custom authorization mechanism refer to Section 2.3, “Writing a custom server-side authorization mechanism”.

The client side authorization can be configured for each invocation.

To write and configure custom authorization mechanism refer to Section 2.2, “Writing custom client-side authorization scheme”.

If no authorization mechanism has been specified, HostOrSelf authorization is used. In this scheme host authorization is tried first, if it fails, self authorization is attempted

Configuration of service-side security settings can be achieved by using container or service security descriptor. Some of the security configuration, like the credential to use and trusted certificates location, can also be configured using CoG properties or rely on default location. The preferred way is to provide these settings in a security descriptor.

The next section provides details on the relevant properties. An overview of the syntax of security descriptors can be found in Java WS A&A Security Descriptor Framework. Available CoG security properties can be found in Chapter 2, Configuring

The following properties are relevant to authentication and message/transport security:

The following information applies to Java WS Core and those services built on it.

Logging in the Java WS Core is based on the Jakarta Commons Logging API. Commons Logging provides a consistent interface for instrumenting source code while at the same time allowing the user to plug-in a different logging implementation. Currently we use Log4j as a logging implementation. Log4j uses a separate configuration file to configure itself. Please see Log4j documentation for details on the configuration file format.

   #for debug level logging from org.globus.package.FooClass 
   log4j.category.org.globus.package.name.FooClass=DEBUG
   #for warnings from org.some.warn.package
   log4j.category.org.some.warn.package=WARN
   

As described in the above section, configuration files need to be edited to enable logging at different levels. For example, to see all logging for server side authorization, the following lines need to be added to container logging configuration file. To see client-side authorization framework logging, the same line needs to be added to $GLOBUS_LOCATION/log4j.properties.

log4j.category.org.globus.wsrf.impl.security.authorization=DEBUG 

The authorization module uses Java CoG Kit for some of the functionality. To turn on logging for that functionality, the following can be added to the relevant logging file, depending on whether it is the client or the server side logging.

log4j.category.org.globus.gsi.jaas=DEBUG
log4j.category.org.globus.gsi.gssapi=DEBUG
log4j.category.org.globus.security.gridmap=DEBUG