On the service side, the framework allows developers to configure a chain of authorization mechanisms either programmatically or declaratively using security descriptors. It also allows for plugging in new authorization schemes (in addition to using those that are provided with the framework). Moreover, the framework allows for this configuration to be done at resource, service or container level, each taking precedence in the order specified and scoped as the name suggests.

On the client side, a pluggable framework for authorization of service is provided.

2. Before you begin

2.1. Feature summary

Features new in GT 4.1.1:

Enhanced server-side attributed-based authorization framework: The server-side authorization framework has been reworked to support attribute based authorization with delegation of rights. The framework allows for configuring a chain of Policy Information Points(PIPs) and Policy Decision Points(PDPs) and a combining alogorithm that processes the individual decisions returned by the PDPs. Some of the key changes from the previous versions are:
- Authorization framework uses a set of attributes to identify entities
- The authorization engine uses Java Security provider framework to allow different combining algorithms to be plugged in.
- A default implementation of permit override combining algorithm, which looks for a permit decision chain, to allow for fine grained delegation of rights.
Refer Section 3, “Architecture and design overview” for detailed information on the architecture.
Host or Self Authoriation: Support for a pluggable PDP that does host authorization, and if that fails, tries self authorization.
The security descriptor framework, used to configure security properties for the security framework has been enhanced. Detailed information about the framework is provided Java WS Security Descriptor Framework

Other Supported Features

Authorization based on grid-mapfile and other access control lists.
Ability to implement custom authorization modules.
A SAML callout authorization module enables outsourcing of authorization decisions to an authorization service (e.g. PERMIS).

Deprecated Features

None

2.2. Tested platforms

Tested Platforms for WS Authorization Framework:

Linux (Red Hat 7.3)
Windows 2000
Solaris 9

2.3. Backward compatibility summary

This section is not applicable for development releases.

2.4. Technology dependencies

The WS Authentication and Authorization component depends on the following GT components:

WS Authentication and Authorization Message-Level Security

The WS Authentication and Authorization component depends on the following 3rd party software:

OpenSAML

2.5. Security considerations

2.5.1. Client side authorization

Client authorization of the server is done after the completion of the operation when GSI Secure Message authentication is used. If you require client authorization to be done prior, use GSI Secure Conversation or GSI Transport security.

2.5.2. Host authorization

During host authorization, the toolkit treats DNs "hostname-*.edu" as equivalent to "hostname.edu". This means that if a service was setup to do host authorization and hence accept the certificate "hostname.edu", it would also accept certificates with DNs "hostname-*.edu".

The feature is in place to allow a multi-homed host folowing a "hostname-interface" naming convention, to have a single host certificate. For example, host "grid.test.edu" would also accept likes of "grid-1.test.edu" or "grid-foo.test.edu".

	Note
	The wildcard character "*" matches only name of the hostand not domain components. This means that "hostname.edu" will not match "hostname-foo.sub.edu", but will match "host-foo.edu".

	Note
	If a host was set up to accept "hostname-1.edu", it will not accept any of "hostname-*.edu".

A bug has been opened to see if this feature needs to be modfiied.

3. Architecture and design overview

3.1. Server-side authorization

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.

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.

3.1.1. Authorization Policy Configuration

A chain of PDPs and PIPs, with relevant configuration information, can be configured at resource, service or container level. These chain use Permit Override with Delegation as default combining algorithm. Additionally an administrative policy can be configured at the container level. The administrative chain uses First Applicable combining algorithm by default. Note that comining algorithms can be configured to over-ride the deafult. The following describes the precedence in which configured policy is used:

If container level administrative policy is specified, it is evaluated.
1. If (1) returns a deny, the request is denied.
2. If (1) returns a permit, step (2) is done.
If resource level policy is specified, it is evaluated.
1. If (2) returns a deny, the request is denied.
2. If (2) returns a permit, the request is permitted.
If (2) is not specified and service level policy is specified, it is evaluated.
1. If (3) returns a deny, the request is denied.
2. If (3) returns a permit, the request is permitted.
If (3) is not specified and container level policy configuration is specified, it is evalauted.
1. If (4) returns a deny, the request is denied.
2. If (4) returns a permit, the request is permitted.

3.1.2. Authorization Handler Steps

Invoke Container PIP to collect attributes inherent to the framework. The PIP creates an instance of RequestEntities class to use as parameter with PIPs. It also creates an instance of ResourceChainConfig class to push the current message context as a parameter to ContianerPIP.
Evaluate the administrator authorization engine, if one is configured
1. If bootstrap overwrite is configured, then only BootstrapPIPs in administrator engine is invoked. Else the X509 Bootstrap PIP is invoked prior to any other Bootstrap PIPs configured.
2. The authorization engine is run and if a deny decision is returned, the operation is denied. If a permit decision is returned, the operation is permitted. If a not applicable or indeterminate is returned, further authorization engines are evaluated.
Evaluate the authorization engine configured in the resource, service, container, in that order depending on which is configured
1. If bootstrap overwrite is configured, then only BootstrapPIPs in administrator engine is invoked. Else the X509 Bootstrap PIP is invoked prior to any other Bootstrap PIPs configured.
2. If any decision other than a Permit is returned, the operation is denied. If a permit is returned the operation is allowed.
If no authorization engine was configured, then default authorization engine is created, which checks whether the caller has same credentials as service (self authorization)

3.2. Client-side authorization

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.

4. Public interface

4.1. Semantics and syntax of APIs

4.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.

4.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.

4.2. Semantics and syntax of the WSDL

4.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.

4.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.

4.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

4.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.

4.2.5. Faults

4.2.6. WSDL and Schema Definition

OGSA-AuthZ Authorization Service WSDL

4.3. Semantics and syntax of non-WSDL protocols

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

4.4. Command-line tools

There is no support for this type of interface.

4.5. Overview of Graphical User Interfaces

This component has no graphical user interfaces.

4.6. Semantics and syntax of domain-specific interface

4.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.

4.6.2. Syntax of the interface

4.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());

4.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
	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
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
	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.

4.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.

4.7. Configuration interface

4.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

4.7.2. Syntax of the interface

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

Security descriptors using files. Refer to Section 3.1, “Configuring Using Files”
Security descriptors programmatically. Refer to Section 3.2, “Configuring Programmatically ”

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.

Security descriptors using files. Refer to Section 4.1, “Configuring Using Files”, specifically Section 4.1.2.2, “Configuring authorization mechanism ”.
Security descriptors programmatically. Refer to Section 4.2, “Configuring Programmatically ”
Properties on the Stub. Refer to Section 4.6.2.1, “Configuring client-side authorization on the stub”

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

4.8. Environment variable interface

There is no support for this type of interface.

4.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.

5. Usage scenarios

5.1. Using SAML Authorization Assertions

Please see Section 5.4, “ Using SAML Authorization Assertions ” in the Message-/Transport-level Security documentation.

6. Tutorials

There are no tutorials available at this time.

7. Debugging

Log output from the authorization framework is a useful tool for debugging issues. Logging in the code is based on the Jakarta Commons Logging API and is described in more detail in Section 7, “Debugging”. 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

8. Troubleshooting

8.1. No grid map file

Check to ensure that a grid map file name is configured as shown in Section 5.1, “Configuring Default GridMap Files” and that the security descriptor with grid map file information is configured correctly.

8.2. Authorization failed. Peer is anonymous

If an anonymous client is used, only some authorization schemes can authorize them. Self authorization, identity authorization, gridmap authorization and host authorization will fail if anonymous clients are used. Ensure that an appropriate authorization scheme is used if anonymous clients are allowed.

8.3. "org.globus.ogsa.security.authorization" property must be of "org.globus.ogsa.impl.security.authorization.Authorization" type

This error can occur on the client side if the authorization instance set on the stub does not implement interface org.globus.ogsa.impl.security.authorization.Authorization. A common error is importing authorization classes from org.globus.gsi.gssapi.auth rather than from org.globus.ogsa.impl.security.authorization. It is recommended that client security descriptors be used to set these properties, so the right classes and properties are setup by the framework.

9. Related Documentation

Associated standards for WS Authentication and Authorization Framework:

Prev	Up	Next
GT4 WS AA User's Guide	Home	GT 4.1.1 WS AA Public Interfaces