GT 4.1.2 WS AA Public Interfaces

1. Semantics and syntax of APIs

1.1. Programming Model Overview

Independent authorization settings can be configured on the server and client side. The security programming model on the server side is declarative and all configuration is done by setting a security descriptor. The descriptor can be a resource, service or container descriptor, depending on the required scope for the authorization. Alternatively the security settings can be done using programmatic security descriptor constructs. The client side the configuration is done by setting required properties on the stub used to make the method invocation. The security properties, and hence the authorization settings, can be set directly as properties on the stub, or a client security descriptor that encapsulates the individual properties may be written and in turn passed to the framework via a property on the stub object.

1.2. Component API

  • Generic Java Authorization Engine API

    • org.globus.security.authorization.PDP
    • org.globus.security.authorization.PIP
    • org.globus.security.authorization.ChainConfig
    • org.globus.security.authorization.Interceptor

  • Stable API

    • org.globus.wsrf.security.Constants
    • org.globus.wsrf.security.SecureResource
    • org.globus.wsrf.security.SecurityManager
    • org.globus.wsrf.security.authorization.Constants
    • org.globus.wsrf.security.impl.authorization.Authorization
  • Less stable API

    • org.globus.wsrf.impl.security.descriptor.ClientSecurityDescriptor
    • org.globus.wsrf.impl.security.descriptor.ServiceSecurityDescriptor
    • org.globus.wsrf.impl.security.descriptor.ResourceSecurityDescriptor

Documentation for these interfaces can be found here FIX ME.

2. Semantics and syntax of the WSDL

2.1. SAML Authorization Callout

The authorization framework as such does not have a WSDL interface. On the other hand one of the authorization scheme in the toolkit, a callout to an authorization service compliant with the specification published by the OGSA Authorization Working Group (OGSA-AuthZ) requires a WSDL interface for the service. The callout makes a query on the configured authorization service, which returns an authorization decision.

2.2. Protocol overview

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.

2.3. Operations

  • SAMLRequest: Used to send queries to the authorization service, which after processing returns an authorization decision. All faults are embedded as part of the decision that is returned, i.e. no fault is declared at the WSDL level.
  • GetResourceProperty: Gets the value of a specific resource property. This operation throws the following faults:

    • ResourceUnknownFault
    • InvalidResourcePropertyQNameFault
  • SetResourceProperties: Sets the value for resource properties. This operation throws the following faults:

    • ResourceUnknownFault
    • InvalidSetResourcePropertiesRequestContentFault
    • UnableToModifyResourcePropertyFault
    • InvalidResourcePropertyQNameFault
    • SetResourcePropertyRequestFailedFault
  • QueryResourceProperties: Used for the querying of resource properties using a query expression. This operation throws the following faults:

    • ResourceUnknownFault
    • InvalidResourcePropertyQNameFault
    • UnknownQueryExpressionDialectFault
    • InvalidQueryExpressionFault
    • QueryEvaluationErrorFault

2.4. Resource properties

  • supportedPolicies: Contains identifiers for any or all access control policies that the authorization service is capable of rendering decisions regarding.
  • supportsIndeterminate: Indicates whether the authorization service may return an "indeterminate" authorization decision. If set to flase, only permit or deny is returned.
  • signatureCapable: Indicates if the authorization service is capable of signing the decision returned. If not, only unsigned decisions are returned.

2.6. WSDL and Schema Definition

3. Semantics and syntax of non-WSDL protocols

[describe non-WSDL protocols. if none, state so.]

4. Command-line tools

There is no support for this type of interface.

5. Overview of Graphical User Interfaces

This component has no graphical user interfaces.

6. Semantics and syntax of domain-specific interface

6.1. Interface introduction

Configuration on the server side is done using Section 1, “Security Descriptors Introduction”. Custom authorization mechanisms can be written and used as a part of the GT frameework. The next section describes the steps involved.

On the client side, in addition to security descriptor, properties on the stub can be sed to configure security properties. Properties and values are described in detail in the next section.

6.2. Syntax of the interface

6.2.1. Configuring client-side authorization on the stub

The property to use depends on the authentication scheme:

  • If GSI Secure Transport or GSI Secure Conversation is used, the org.globus.axis.gsi.GSIConstants.GSI_AUTHORIZATION property must be set on the stub. The value of this property must be an instance of an object that extends from org.globus.gsi.gssapi.auth.GSSAuthorization. All distributed authorization schemes have implementation in org.globus.gsi.gssapi.auth package.

  • For all other authentication schemes, the org.globus.wsrf.impl.security.Constants.AUTHORIZATION property must be set on the stub. The value of this property must be an instance of an object that implements the org.globus.wsrf.impl.security.authorization.Authorization interface.

  • Example:

          // Create endpoint reference EndpointReferenceType
          endpoint = new EndpointReferenceType(); 
          // Set address of service
          String counterAddr = 
             "http://localhost:8080/wsrf/services/CounterService";
          // Get handle to stub object
          CounterPortType port = 
               locator.getCounterPortTypePort(endpoint);
          // set client authorization to self 
          ((Stub)port)._setProperty(Constants.AUTHORIZATION, 
                       SelfAuthorization.getInstance());
                

6.2.2. Writing custom client-side authorization scheme

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

[Note]Note

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

  • If the authentication scheme to be used is GSI Secure Transport or GSI Secure Conversation, the custom authorization scheme should extend from extends from org.globus.gsi.gssapi.auth.GSSAuthorization.

          public class TestAuthorization extends GSSAuthorization {
          
            // Provide some way to instantiate this class. Can use constructor
            // with arguments to pass in parameters.
             public TestAuthorization() {
    
             }
    
             public GSSName getExpectedName(GSSCredential cred, String host) 
                throws GSSException {
    
                // Return the expected GSSName of the remote entity.
             }
    
    
              public void authorize(GSSContext context, String host)
    	     throws AuthorizationException {      
    
                 // Perform the authorization steps.
                 // context.getSrcName() provides the local GSSName
                 // context.getTargName() provides the remote GSSName
    
                 // if authorization fails, throw AuthorizationException
             }
          }
          

    The following describes the steps done for client side authorization during context establishment:

    • Prior to initialization of context establishment the relevant handler (HTTPSSender in case of GSI Secure Transport or SecContextHandler in case of GSI Secure Conversation), invokes getExpectedName on the instance of GSSAuthorization set on the Stub.

    • During context establishment, if the expected target name from previous step is not null, it is compared with the remote peer's GSSName. If it is not a match, context establishment is abandoned and an error is thrown.

      If the expected target name is null, then a match is not done, unless the option of delegation is used. That is, if GSI Secure Conversation with delegation is used, then the expected target name cannot be null and must match the remote peer's identity.

    • Once the context has been established, the authorize method is invoked.

    [Note]Note

    Client authorization is done prior to invocation.

    To configure the custom authorization scheme:

          ((Stub)port)._setProperty(GSIConstants.GSI_AUTHORIZATION, 
                       new TestAuthorization());
          

    Various authorization scheme implementations in package org.globus.gsi.gssapi.auth would serve as examples. View CVS Link

  • For all authentication schemes other than those in previous step the org.globus.wsrf.impl.security.Constants.AUTHORIZATION property must be set on the stub. The value of this property must be an instance of an object that implements the org.globus.wsrf.impl.security.authorization.Authorization interface.

          public class TestAuthorization implements Authorization {
          
            // Provide some way to instantiate this class. Can use constructor
            // with arguments to pass in parameters.
             public TestAuthorization() {
    
             }
    
             public GSSName getName(MessageContext ctx) 
                throws GSSException {
    
                // Return the expected GSSName of the remote entity.
             }
    
    
              void authorize(Subject peerSubject, MessageContext context)
                                     throws AuthorizationException {
    
                 // Perform the authorization steps.
                 // peerSubject provides the remote Subject
                 // Use SecurityManager API to get local Subject
    
                 // if authorization fails, throw AuthorizationException
             }
          }
          

    The following describes the steps done for client side authorization:

    • The client side handler WSSecurityClientHandler, invokes authorize method on the authorization instance.

    [Note]Note

    Client authorization is done after the invocation.

    To configure the custom authorization scheme:

          ((Stub)port)._setProperty(Constants.AUTHORIZATION, 
                       new TestAuthorization());
          

    Various authorization scheme implementations in package org.globus.wsrf.impl.security.authorization would serve as examples. View CVS Link.

6.2.3. Writing a custom server-side authorization mechanism

The server side authorization framework can be configured to use a 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 3, “Migrating from GT 4.1.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.

7. Configuration interface

7.1. Configuration overview

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

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

7.2. Syntax of the interface

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

To write and configure server-side custom authorization mechanism refer to Section 4.6.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 4.6.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

8. Environment variable interface

There is no support for this type of interface.

9. PIPs and PDPs

This section describes a list of PIPs and PDPs that are distributed with the toolokit. Each of these modules can be plugged into the authorization framework using configuration.