GT 3.9.5 Authorization Framework: Security Descriptor

  1. Introduction
  2. Writing security descriptor file
  3. Programmatic altering of security descriptors
  4. Resource Security Descriptor
  5. Container-only Security Configuration
  6. Other Configuration

1. Introduction

Security descriptors contain various security properties like credentials, gridmap, required authentication and authorization mechanisms and so on. There are three kinds of security descriptors in the code base for setting container, service and resource security properties, respectively:

  • the service security descriptor
  • the container security descriptor
  • the resource security descriptor

Each of these is represented as a object in the code base and can be altered programmatically. Service and container security descriptors can be configured as an XML file in the deployment descriptor as shown below. Resource security descriptors can only be created dynamically either programmatically or from a descriptor file. If the security descriptor file is altered at runtime, it will not be reloaded

1.1 Configuring security descriptors

The following shows how the service and container security descriptor files are configured:

 <globalConfiguration>
  ...
  <parameter name="containerSecDesc" value="etc/container-security-config.xml">
  ...
 <globalConfiguration>
 ...
 <service name="MyDummyService" provider="Handler" style="document">
  ...
  <parameter name="securityDescriptor" value="org/globus/wsrf/impl/security/descriptor/security-config.xml"/>
  ...
 </service>

If the security descriptor is configured to be read from a file, it is loaded as follows:

  1. As a file if absolute file path is specified
  2. As a resource (can be included as part of jar file)
  3. As a file, using the specified path to be relative to the installation root, typically pointed to by environment variable GLOBUS_LOCATION

The security descriptor files need to comply with the service security descriptor schema or container security descriptor schema as appropriate. The resource security descriptor file uses the same schema as the service security descriptor. In all cases, the security descriptor is contained within the <securityConfig xmlns="http://www.globus.org"> element.

2. Writing security descriptor files

The next few sections deal with writing security descriptor files to set various properties. Please note that not all parameters are applicable for all three types of descriptors and are appropriately noted in the relevant sections. The few parameters relevant only for container security descriptor are described in Section 5.

2.1 Configuring credentials

The container and each service can also be configured with a separate set of credentials. The credentials can be set using either the a) path to a proxy file or b) path to a certificate and key file. If the configured credential file is modified/updated at runtime, the credentials will be automatically reloaded. This is done by adding the following block to the container or service security descriptor.

Example for option (a): 
<securityConfig xmlns="http://www.globus.org">
 ...
 <credential>
  <key-file value="keyFile"/>
  <cert-file value="certFile"/>
 </credential>
 ...
</securityConfig>
Example for option (b): 
<securityConfig xmlns="http://www.globus.org">
 ...
 <proxy-file value="proxyFile"/>
 ...
</securityConfig>

The service will look for credentials in this order:

  1. Resource credentials
  2. Service credentials
  3. Container credentials
  4. Default credentials (uses the underlying security library to acquire the credentials, which will be the proxy certificate of the user that is running the container)

2.2 Configuring gridmap

The container and each service can be configured with a separate gridmap in its security descriptor as shown below:

 <securityConfig xmlns="http://www.globus.org">
 ...
 <gridmap value="gridMapFile"/>
 ...
 </securityConfig>

The service will look for gridmap configured first in resource, then service and then container. For services configured to perform gridmap file authorization, the gridmap file can be updated dynamically using the SecurityManager API. Also, if the gridmap file changes at runtime it will be automatically reloaded.

2.3 Configuring Authentication Methods

This can only be done at service or resource level.

The authentication methods a service requires are specified using the <auth-method> element. The authentication methods can also be configured on a per method basis. This is done by specifying the <auth-method> element within a <method name="qname"> element. The name attribute of the element can just be the operation name (preferred) or the operation name with a given namespace.

Currently, the following authentication methods are supported:

<none/>

Indicates that no authentication is required.

This method cannot be specified with any other authentication method.
<GSISecureMessage/>

Indicates the GSI Secure Message authentication method.

The <protection-level> sub element can be used to specify a protection level that must be applied to the message:
<integrity/> Indicates that the message must be integrity protected (signed)
<privacy/> Indicates that the message must be privacy protected (encrypted & signed)
<GSISecureConversation/>

Indicates the GSI Secure Conversation authentication method (with integrity or privacy protection)

The <protection-level> sub element can be used to indicate a specific protection level that must be applied to the message:
<integrity/> Indicates that the message must be integrity protected (signed)
<privacy/> Indicates that the message must be privacy protected (signed & encrypted)
<GSITransport/>

Indicates the GSI Secure Transport authentication method

The <protection-level> sub element can be used to specify a specific protection level that must be applied to the message:
<integrity/> Indicates that the message must be integrity protected (signed) This is always true in this mechanism
<privacy/> Indicates that the message must be privacy protected (encrypted & signed)

Notes:

  • Multiple authentication methods can be specified under the <auth-method> element (expect for the <none/> method, see above) As long as one of the authentication methods is performed, the access to the service is allowed.
  • If no <protection-level> sub element is specified, then all protection levels are available to clients. However, if the <protection-level> sub element is specified, then the service will only accept the protection levels listed under said element.
  • The org.globus.wsrf.impl.security.authentication.SecurityPolicyHandler handler must be installed properly in order for this to work. This handler is installed by default.
  • If a security descriptor is not specified, authentication method enforcement is not performed.

Example:

<securityConfig xmlns="http://www.globus.org">

 <method name="findServiceData">
   <auth-method>
     <none/>
   </auth-method>
 </method>

 
 <method name="destroy">
   <auth-method>
     <GSISecureMessage/>
     <GSISecureConversation>
       <protection-level>
          <integrity/>
       </protection-level>
     </GSISecureConversation>
   </auth-method>
 </method>


 <!-- default auth-method for any other method -->
 <auth-method>
  <GSISecureConversation/>
 </auth-method>

</securityConfig>

In the above example:

  • the findServiceData() operation does not require any authentication
  • the destroy() operation requires either GSI Secure Message authentication with either level of protection or GSI Secure Conversation authentication with integrity protection.
  • all other operations must be authenticated with GSI Secure Conversation with either level of protection.

2.4 Configuring run-as mode

The <run-as> element is used to configure the JAAS run-as identity under which the service method will be executed. The run-as identity can be configured on a per method basis. Currently, the following run-as identities are supported:

<caller-identity/>

The service method will be run with the security identity of the client. The caller Subject will contain the following:

  • If using GSI Secure Message: a GlobusPrincipal (the identity of the signer) is added to the principal set of the caller-identity Subject. Also, the signer's certificate chain is added to the public credentials set of the Subject object.
  • If using GSI Secure Conversation: a GlobusPrincipal (the identity of the initiator) is added to the principal set of the Subject.
    • If client authentication was performed, the client's certificate chain will be added to the public credentials set of the Subject object.
    • Also, if delegation was performed, the delegated credential is added to the private credential set of the Subject object.
  • If gridmap file authorization was performed, a UserNamePrincipal is added to the principal set of the Subject object
<system-identity/> The service method will be run with the security identity of the container.
<service-identity/> The service method will be run with the security identity of the service itself (if the service has one, otherwise the container identity will be used).
<resource-identity/> The service method will be run with the security identity of the resource. If no resource is specified or it does not have a configured subject, credential in this order of occurrence will be used: service credential, container credential.

Notes:

  • resource-identity is the default setting.
  • The org.globus.wsrf.impl.security.authentication.SecurityPolicyHandler handler must be installed properly in order for this to work.
  • If the security descriptor is not specified, then the run-as identity is not set and there will be no JAAS subject associated with the execution of the operation. This means that any method calls that require credentials and that are invoked by the service method itself will fail.

Example:

<securityConfig xmlns="http://www.globus.org">

 <method name="add">
   <run-as>
     <caller-identity/>
   </run-as>
 </method>

 <method name="subtract">
   <run-as>
     <system-identity/>
   </run-as>
 </method>

 <!-- default run-as for any other method -->
 <run-as>
  <service-identity/>
 </run-as>

</securityConfig>

In the above example:

  • the add()operation will be run with the caller's identity
  • the subtract()call will be run with the system identity
  • all other operations will be run with the service identity (if the service has one set)

2.5 Configuring authorization mechanism

The container and each service can be configured with a chain of authorization mechanisms (also known as Policy Decision Points (PDPs)), using the authz element. Each PDP name is scoped and the format is prefix:FQDN of the PDP. For example, self:org.globus.wsrf.impl.security.authorization.SelfAuthorization. The authorization is deemed to be a permit if each of the authorization mechanisms in the chain returns a permit.

Example:

<securityConfig xmlns="http://www.globus.org">
 ... 
 <authz value="foo1:org.foo.authzMechanism, bar1:org.bar.barMechanism"/>
 ...
<securityConfig/>
FIXME: detailed explanation may not be required here

Each PDP is instantiated with some configuration information that is used to get any further information that the PDP may need to make authorization decisions. If the authorization chain is configured at the container level, then the parameters are picked up from the global configuration section of the container deployment descriptor. If the authorization chain is configured at the service level, the PDPs will pick up parameters from the relevant service section of the deployment descriptor. Resource level configuration has to be done programmatically and is described here. In all three cases, the prefix specified in the authorization chain configuration is used to get the right property. For example, all properties for foo1:org.foo.authzMechanism are picked up from properties that have been scoped with the prefix foo1-

The following PDPs are a part of the toolkit and are configured as shown. The framework maps and plugs in the scoped name of the PDP at the time of authorization.

none No authorization is performed.
self
  • PDP Name: selfAuthz:org.globus.wsrf.impl.security.authorization.SelfAuthorization
  • This scheme does not require any additional configuration information.

  • Only clients that present the same identity as the identity in the current JAAS subject associated with the service are allowed to access the service.

    The current JAAS subject is determined by the value of the run-as element in the service security descriptor (see Configuring run-as mode)
gridmap
  • PDP Name: grimapAuthz:org.globus.wsrf.impl.security.authorization.GridMapAuthorization
  • A gridmap file must be configured as described in Section 2.1.2.
  • Gridmap file authorization is performed, i.e. a mapping must exist for the client identity in the configured grid map file.
identity
  • PDP Name: idenAuthz:org.globus.wsrf.impl.security.authorization.IdentityAuthorization
  • The property, idenAuthz-identity set to the expected identity must be configured in the service or container deployment descriptor in the case of service level or container level authorization respectively.
  • The client identity must match the value of this property.
host
  • PDP Name: hostAuthz:org.globus.wsrf.impl.security.authorization.HostAuthorization
  • The property, hostAuthz-url set to the expected host name must be configured in the service or container deployment descriptor in the case of service level or container level authorization respectively.
  • Host based authorization is done and should match the expected host set in the property.
samlCallout
  • PDP Name: samlAuthz:org.globus.wsrf.impl.security.authorization.SAMLAuthorizationCallout
  • This scheme calls out to a configured LINKME OGSA-AuthZ compliant authorization service.
  • The authorization service should be configured as a part of the service deployment descriptor using the property
    • authzService. The property should be set to the EPR of the authorization service to contact.
  • The callout by default requests for simple decision from the authorization service LINK ME to OGSA-AuthZ stuff about this. This property can be changed by setting a container level property samlAuthzSimpleDecision to true or false.
  • The callout by default does not sign the query request to the authorization service LINK ME to OGSA-AuthZ stuff about this. This property can be changed by setting a container level property samlAuthzReqSigned to true or false
userName
  • PDP Name: userNameAuthz:org.globus.wsrf.impl.security.authorization.UsernameAuthorization
  • This scheme does not require any additional configuration information.
  • This uses the configured LINKME JAAS Login Module to authorize the user based on username and password. The PDP uses NameCallback and PasswordCallback to send user name and password information to the Login module.

Other than these, any custom authorization scheme could be configured with its own configuration information. Refer to the next section for details on writing a custom authorization mechanism

2.5.1 Writing a custom authorization mechanism

The authorization handler can be configured to call out to a custom authorization class. The class must implement the interface org.globus.wsrf.impl.security.PDP.

If the authorization fails, then a org.globus.wsrf.impl.security.authorization.AuthorizationException should be thrown.

Example: 

  public class FooAuthorization implements PDP {
      public void authorize(Subject peerSubject, ServiceProperties service,
			  MessageContext context) 
	throws AuthorizationException {
	// Evaluate and throw exception if not authorized.
      }
  }

Example:

<securityConfig xmlns="http://www.globus.org">

 <method name="findServiceData">
   <run-as>
     <caller-identity/>
   </run-as>
 </method>

 <method name="destroy">
   <run-as>
     <system-identity/>
   </run-as>
 </method>

 <!-- default run-as for any other method -->
 <run-as>
  <service-identity/>
 </run-as>
 <context-lifetime value="100"/>
</securityConfig>

In the above example, if the service is accessed using a limited proxy, an error is reported. Also, the contexts created at the server end are set to have a lifetime of 100 seconds.

3. Programmatic altering of security descriptor

The security descriptor (container, security and resource) can be created and altered programmatically (as opposed to writing a security descriptor file) For the service and container descriptor, we recommend writing a security descriptor file so that the security properties are initialized at start up.

Container Security Descriptor

This is represented by org.globus.wsrf.impl.security.descriptor.ContainerSecurityDescriptor.

If a container security descriptor file is configured as described in Section 2, then an object is created and stored. To alter the values, use the API provided in org.globus.wsrf.impl.security.descriptor.ContainerSecurityConfig.
Service Security Descriptor

This is represented by org.globus.wsrf.impl.security.descriptor.ServiceSecurityDescriptor.

If a service security descriptor file is configured as described in Section 2, then an object is created and stored. To alter the values, use the API provided in org.globus.wsrf.impl.security.descriptor.ServiceSecurityConfig.
Resource Security Descriptor

This is represented by org.globus.wsrf.impl.security.descriptor.ResourceSecurityDescriptor.

To initialize the descriptor, i.e. load credentials and gridmap, use the API in org.globus.wsrf.impl.security.descriptor.ResourceSecurityDescriptor . Refer to the description of resource security descriptor in Section 4.1 for more details.

4. Resource Security Descriptor

Resource level security can be set using a resource security descriptor, which overrides any service or container level security. To make a resource secure, it needs to implement org.globus.wsrf.impl.security.SecureResource. This interface has a method that returns an instance of org.globus.wsrf.impl.security.descriptor.ResourceSecurityDescriptor. If null is returned, it is assumed that no security is set on the resource.

The resource security descriptor is identical to the service security descriptor and contains API to set and get all properties that are described in Section 2. A descriptor file can also be used to create this object. The file needs to be written as described in Section 2.

Examples:

The following code snippet creates a resource descriptor object directly: 

  ResourceSecurityDescriptor desc = new ResourceSecurityDescriptor();
  desc.setRejectLimitedProxy("true");

The following code snippet creates a resource descriptor object from a file: 

  ResourceSecurityConfig config = new ResourceSecurityConfig("resDescFileName");
  config.init();
  ResourceSecurityDescriptor desc = config.getSecurityDescriptor();
There are two attributes of the security descriptor, credentials and gridmap, that can be specified as objects (javax.security.auth.Subject and org.globus.security.gridmap.GridMap respectively) or as paths to credentials and the gridmap file. Similarly, the service authorization chain object or a comma separated list of PDP names can be specified. In each of these cases, if the properties are configured as filenames or PDP names as the case may be, the helper API in org.globus.wsrf.impl.security.descriptor.ResourceSecurityConfig can be used to load the classes. The credentials, gridmap and PDP specified in the authorization chain are loaded if the property initialized in the descriptor is set to false.

For example, the code snippet below is a descriptor that has a gridmap file and specifies authorization chain. When config.init() is called, gridmap is loaded and an instance service authorization chain class is created. The configuration information for the service authorization chain is by default picked up from global deployment descriptor. To provide for other PDP configuration, it needs to be set programmatically, as shown here.

  ResourceSecurityDescriptor desc = new ResourceSecurityDescriptor();
  desc.setGridMapFile("foo/bar/gridmap");
  desc.setAuthz("customAuthz:org.globus.some.customAuthz, foo1:org.foo.barAuthz");
  ResourceSecurityConfig config = new ResourceSecurityConfig(desc);
  config.init();

If the descriptor property changes, a reload can be forced by setting setInitialized to false:

 desc.setInitialized(false);
 desc.setGridMapFile("foo/bar/newGridMap");
 config.init();

GridMap and Subject object can also be set directly, i.e. without configuring files to be read:

  desc.setInitialized(false);
  GridMap map = new GridMap();
  map.map("Some user DN", "userid");
  desc.setGridMap(map);

Service Authorization can also be set directly by creating an object of org.globus.wsrf.impl.security.authorization.ServiceAuthorizationChain. The chain needs to be initialized with an object implementing the org.globus.wsrf.security.authorization.PDPConfig interface. The org.globus.wsrf.impl.security.descriptor.ResourceSecurityDescriptor class has API to initialize a PDP using a said PDPConfig class. The distribution has a few sample classes that implement org.globus.wsrf.security.authorization.PDPConfig interface and are described below:

  • org.globus.wsrf.impl.security.authorization.ContainerPDPConfig: Reads configuration information off the global deployment descriptor.
  • org.globus.wsrf.impl.security.authorization.ServicePropertiesPDPConfig: Reads configuration information off a said service's deployment descriptor.
  • org.globus.wsrf.impl.security.authorization.ResourcePDPConfig: Reads configuration information off of a hashmap stored in memory.
Examples

This sample creates a authorization chain to be set on the resource security descriptor programmatically:

// Create a resource security descriptor
ResourceSecurityDescriptor desc = new ResourceSecurityDescriptor();
// Configure a chain of PDPs
String authzChain = "identityAuthz, custom:org.something.CustomAuthz";
// Create configuration object that implements PDPConfig interface
PDPConfig config = new ResourcePDPConfig();
// Set properties that are required by the PDPs on the configuration object.
// Property used by Identity authorization: scope, property name, property value
config.setProperty("idenAuthz", "identity", "O=this, OU=is expected, CN=identity");
// Property used by CustomAuthz: scope, property name, property value
config.setProperty("custom", "someProp", "foo");
desc.setAuthzChain(authzChain, config, "Name of Chain", "Some id");

5. Container-only Security Configuration

Other than the security properties that have been described in Security Descriptor, two more properties are exclusive to the container security descriptor.

  • When GSI Secure Conversation is used, a security context is established. A sweeper task is run every 10 minutes to delete all expired contexts. This interval can be set (in milliseconds) in the container security descriptor as shown below: 
     <securityConfig xmlns="http://www.globus.org">
      ...
      <context-lifetime value="10000"/>
      ...
     </securityConfig>
  • For message level security one may also set the amount of time for which to track received messages for the purpose of preventing replay attacks. Messages outside of this window will be reject automatically, whereis messages in this window are checked against recently received messages through the use of the message UUID. This window can be configured (in milliseconds) as shown below: 
     <securityConfig xmlns="http://www.globus.org">
      ...
      <replay-attack-interval value="100"/>
      ...
     </securityConfig>

6. Other Configuration

FIXME Configuring container security descriptor at command line?