GT 4.2.0 Java WS A&A Public Interfaces

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.

org.globus.wsrf.impl.security.authorization.AccessControlListPDP

The PDP uses configured access contol lists to ascertain if a subject can access an operation.

The PDP looks for the files in the following order:

The configured files should have the following format:

subjectName=serviceName#method1,method2;testService2#method1,method2

No interceptors are related other than the default bootstrap interceptor (X509 Bootstrap PIP), which is required to be used with this PDP.

org.globus.wsrf.impl.security.authorization.GridMapPDP

This scheme checks the presence of a user's DN in a configured gridmap file. The grid map file contains a list of mappings from a user's DN to set of local user names that the user is mapped to. The DN and the list of comma-separated mappings are separated by a space. Each mapping is a separate new line by itself.

If the user is present in the configured gridmap file, the mappings are populated in the peer subject object as principals and the user is allowed access to the resource. Absence of DN in gridmap file yields a deny.

The gridmap file location or an instance of GridMap object needs to be configured as a parameter to this PDP. The parameter names are:

The PDP looks for the gridmap file in the following order:

A default grid map file can be configured as described in Section 1, “Configuring Default GridMap File”.

No interceptors are related other than the default bootstrap interceptor (X509 Bootstrap PIP), which is required to be used with this PDP.

org.globus.wsrf.impl.security.authorization.HostAuthzPDP

PDP performs host-based authorization of the client, i.e expects the client to be running with host credential.

No interceptors are related other than the default bootstrap interceptor (X509 Bootstrap PIP), which is required to be used with this PDP.

org.globus.wsrf.impl.security.authorization.IdentityAuthzPDP

Compares the peer subject with a specific configured subject DN.

No interceptors are related other than the default bootstrap interceptor (X509 Bootstrap PIP), which is required to be used with this PDP.

org.globus.wsrf.impl.security.authorization.NoAuthorization

This PDP always returns a permit.

None.

No interceptors are related

org.globus.wsrf.impl.security.authorization.ResourcePropertiesPDP

The PDP enforces a parameter based authorization policy on GetResourceProperty, GetMultipleResourceProperties and SetResourceProperties. QueryResourceProperties is not protected by this PDP and to prevent malicious access of RPs through that method, access to that method must be protected using other schemes. GetMultipleResourceProperies access is allowed only if policy allows user access to all the RPs qeuried.

The format of the configuration files should be as follows:

subjectDN=qName1;qName2;qName3

All equal to signs and space in Subject DN should be escaped using backslash.

For example, if the set resource properties policy is defined as follows:

/C\=US/O\=Globus\ Alliance/OU\=User/CN\=101497d3dcd.3dcd5aef=\
{http://www.globus.org/tests/security}booleanVal;{http://www.globus.org\
/tests/security}intVal1

[Above should be a single line without any spaces. Spaces provided here for document formatting] This implies that subject DN "/C=US/O=Globus Alliance/OU=User/CN=101497d3dcd.3dcd5aef" can set value of the RPs {http://www.globus.org/tests/security}booleanVal and {http://www.globus.org/tests/security}intVal1

org.globus.wsrf.impl.security.authorization.SAMLAuthorizationCallout

This PDP can be used to talk to any authorization service that implements the OGSA AuthZ interface. The steps involved include:

No interceptors are related other than the default bootstrap interceptor (X509 Bootstrap PIP), which is required to be used with this PDP.

org.globus.wsrf.impl.security.authorization.SAMLAuthzAssertionPDP

This PDP parses and enforces any SAML Authorization Decision Statements that are a part of the requester's attribute bag. Typically SAMLAuthzAssertionPIP is used in tandem with this PDP to collect those attributes.

The PDP expects the service name as SAML Resource and the operation name as action.

No configuration is required.

org.globus.wsrf.impl.security.authorization.SelfAuthzPDP

This PDP does self authorization and expects the peer subject to match the local subject, which is the current JAAS Subject associated with the service/resource. The current JAAS subject is determined by the value of the run-as element in the service security descriptor (see Configuring run-as mode).

No configuration is required

No interceptors are related other than the default bootstrap interceptor (X509 Bootstrap PIP), which is required to be used with this PDP.

org.globus.wsrf.impl.security.authorization.UsernameAuthzPDP

Uses Java Login module to authorize based on user name and password used on the method call. The username and password are passed to the Login module using javax.security.auth.callback.NameCallback and javax.security.auth.callback.PasswordCallback.

Username authorization as part of the authorization framework for a service involves setting up a Configuration class that reads in the Login Module to be using. It is also possible to specify the login modules to be used by altering some parameters in the java.security file located at $JAVA_HOME/jre/lib/security which has been discussed under the general configuration section. Steps for username authorization using Login Modules configured via custom Configuration classes is described under the custom configuration section.

Login modules can be setup for use by our application in two different ways. One, by adding the login module to the list of login modules used by the JVM. This method has been explained under the JVM Configuration. Second, by creating a custom configuration class to dynamically pick up the login module.

login.configuration.provider=com.sun.security.auth.login.ConfigFile 
login.config.url.1=file:${java.home}/lib/security/jaas.config

Login {
	com.sun.security.auth.module.NTLoginModule required;
};

11.3.2. Custom Configuration

A configuration class is used to setup a specified login module for executing authorization. The class details are provided to the Toolkit through the security descriptor for the service that enforces username auhorization. In order for the username authorization handler to use a custom Login Configuration, a parameter with name "login-config" and a value containing the custom Configuration classname has to be specified along with the PDP in the security descriptor. The PDP in this case is "Username Authorization". The relevant snippet from the service security descriptor is shown below:

    <authzChain>
	<pdps>
        <interceptor name="prefix:org.globus.wsrf.impl.security.authorization.UsernameAuthzPDP">
	  <parameter>
	     <param:nameValueParam>
	     <param:parameter name="login-config" value="org.globus.wsrf.impl.security.authorization.LoginConfiguration"/>
	     </param:nameValueParam>
	  </parameter>
	</interceptor>			
	</pdps>
    </authzChain>

Internal Details

The usernameAuthorization PDP loads the Configuration specified in the parameter "login-config" and sets that as the current configuration.(These are internal details which may be disregarded safely for the purposes of writing up a custom configuration) org.globus.wsrf.impl.security.authorization.UsernameAuthzPDP String className = (String) this.chainConfig.getProperty(this.prefix, "login-config"); Class config = ClassLoaderUtils.forName(className); Object loginConfig = config.newInstance(); if(loginConfig instanceof Configuration ){ Configuration.setConfiguration((Configuration) loginConfig); }

The custom Configuration class has to be a subclass of javax.security.auth.login.Configuration. An example custom Configuration class is available in the unit tests directory at org.globus.wsrf.impl.security.authorization.LoginConfiguration. The login module that has to be used is specified using a login.config file that the configuration class uses. The configuration class loads the appropriate properties from this file. A sample entry for this file is:

	Login {
	   org.globus.wsrf.impl.security.authorization.UsernameLoginModule required;
	};
	

More details regarding Login Configuration files can be found here. The next section focuses on the setup and usage of login modules.

The login modules can be used to handle the authorization of users. The details regarding writing login modules is beyond the scope of this document and can be found at in the Login Module Developers' guide

The unit tests have an example of a login module org.globus.impl.security.authorization.UsernameLoginModule. The username and password to authorize the client have to be passed via the client security descriptor similar to the one listed below. If the password type is not provided then it defaults to PasswordText. In that case, the passwords are sent unencrypted over the wire.

     <clientSecurityConfig xmlns="http://www.globus.org/security/descriptor/client">
       <GSISecureTransport>
      	 <integrity/>
       </GSISecureTransport> 

       <usernameType>
      	 <username value="globus"/>
      	   <passwordType>
              <password value="unittesting"/>
              <type value="http://docs.oasis open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordDigest"/>
           </passwordType>
       </usernameType> 

       <authz value="none"/>

        </clientSecurityConfig>

This login module handles the authorization of usernames and passwords supplied either as Text (unencrypted format) or as a Digest (encrypted format.) by comparing them to the username and password stored on the server in a file. The format of the parameters in the password file used by our example Login Module is illustrated in the following example. ~/tests/unit/etc/Test-authz-pwd

name=globus
password=unittesting
usernames=globus

In summary, Login Modules can be used to implement username authorization. This can be done by either changing the java environment to invoke your login module or by programmatically setting the authorization framework to use your login module. The unit tests provide a good example of how this can be done programmatically which in most cases would prove beneficial.

None.

org.globus.wsrf.impl.security.authorization.ContainerPIP

This implements the BootstrapPIP interface [fixme link to PIP in glossary] and is used with in the toolkit to initialize the request entities. It collects information about the service and operation invoked. It is always invoked prior to any authorization processing.

No configuration is required.

This PIP collects three attributes described in the following tables:

This PIP also sets up the container issuer entity, which is used as the default issuer for attributes collected in the container. The entity has the following attributes:

The container entity is created with the same attributes as above with the above entity as the issuer.

None.

org.globus.wsrf.impl.security.authorization.X509BootstrapPIP

This implements the BootstrapPIP interface [fixme PIP-glossary] which is used when X509 Certificates are used during authentication scheme. It collects peer entities' attributes obtained from the certificates presented by the peer.

No configuration is required.

This PIP collects two attributes described in the following tables:

If X509 Certificates are used for authentication, this bootstrap is used by the Authorization Framework by default.

org.globus.wsrf.impl.security.authorization.SAMLAuthzAssertionPIP

The PIP extracts SAML Authorization Assertion from the request and adds it to the bag of attributes. The message context and the proxy certificate are checked to see if SAML Authorization Assertions are presents.

If the subject DN in the decision statement matches with the requestor's then the attribute is merged with the requestor's bag of attributes.

No configuration information is required.

This PIP collects attributes described in the following tables:

This PIP can be used in tandem with SAMLAuthzAssertionPDP.

org.globus.wsrf.impl.security.authorization.ParameterPIP

This PIP extracts configured parameter element from the SOAPMessage. The parameter is added as an action attributes in the associated RequestAttribute.

This PIP collects two attributes described in the following tables:

This PIP can be used in tandem with ResourcePropertiesPDP to parameter-based authorization for resource property access.

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 Configuring

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