Java WS Security Descriptor Framework

1. Security Descriptors Introduction

Security descriptors contain various security properties like credentials, the grid map file location, required authentication and authorization mechanisms and so on. There are four types of security descriptors in the code base for setting container, service, resource and client security properties:

Descriptor Type Funcationality
container security descriptordetermines the container level security requirement that needs to be enforced.
service security descriptordetermines the service level security requirement that needs to be enforced.
resource security descriptordetermines the resource level security requirement that needs to be enforced.
client security descriptordetermines the security properties that need to be used for a particular invocation.

Each of these is represented as a Java object and can be altered programmatically. If the security descriptor file is altered at runtime, it will not be reloaded

Service and container security descriptors can be configured as XML files in the global and service deployment descriptor as shown below. Resource security descriptors can only be created dynamically, either programmatically or from a descriptor file. Client security descriptor can be configured as a XML file and set as property on Stub.

2.  Security Descriptor Schemas

All security descriptor files need to comply with a defined schema and should be written within the defined namespace.

Table 1. Security descriptor schema

Descriptor Schema Namespace Root Element
Container security descriptor

Schema

http://www.globus.org/security/descriptor/container containerSecurityConfig
Service security descriptor

Schema

http://www.globus.org/security/descriptor/service serviceSecurityConfig
Resource security descriptor

Schema, (Same schema as service)

http://www.globus.org/security/descriptor/service serviceSecurityConfig
Client security descriptor

Schema

http://www.globus.org/security/descriptor/client clientSecurityConfig

2.1.  Loading Security Descriptor Files

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

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

3. Server side Security Descriptors

3.1. Configuring Using Files

3.1.1. Configuring Container Security Descriptor

  1. The container security descriptor can be configured in the <globalConfiguration> section of the Java WS Core deployment descriptor. That file is in wsrf/java/core/source/deploy-server.wsdd if editing source, prior to deploy or $GLOBUS_LOCATION/etc/globus_wsrf_core/server-config.wsdd in a binary install.

       <globalConfiguration>
       ...
       <parameter name="containerSecDesc"
                  value="/path/to/container/descrptor/file.xml">
       ...
       <globalConfiguration>
       ...
       
  2. The descriptor file name can also be specified as a parameter when the Java WS Core continer is started up. The option is -containerSecDesc "/path/to/container/descrptor/file.xml"

    [Note]Note

    This setting takes precendence over 1

3.1.2. Configuring Service Security Descriptor

  1. The service security descriptor can be configured in the service's deployment descriptor section as parameter. The parameter is a name/value that provides the path to the security descriptor file.

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

  2. A ServiceSecurityDescriptor object can be created and initialized in the service's contructor.

        public class MyDummyService {
           public MyDummyService() throws Exception {
    
              ServiceSecurityDescriptor serviceDesc = 
                new ServiceSecurityDescriptor();
    
               // set security properties on the above object using get/set methods
               // in the API
    
               ServiceSecurityHelper
                .setSecurityDescriptor("DummyServiceName"
                                       serviceDesc);
            }
         }
    

    [Note]Note

    This method takes precendence over 1

  3. A ServiceSecurityDescriptor object can be created similar to above, but initialized from a file and set in the constructor.

        public class MyDummyService {
    
            public MyDummyService() throws Exception {
    
                ServiceSecurityDescriptor serviceDesc = 
                    new ServiceSecurityDescriptor("/path/to/security/file");
    
                ServiceSecurityHelper
                    .setSecurityDescriptor("DummyServiceName"
                                       serviceDesc);
            }
        }
    

    [Note]Note

    This method takes precendence over 1

3.1.3. Configuring Resource Security Descriptor

Secure resources must implement org.globus.wsrf.security.SecureResource interface.

  1. A ResourceSecurityDescriptor object can be created and initialized in the resource's constructor. The object should be returned as a part of the getSecurityDescriptor method.

    
        public MyDummyResource implements SecureResource {
        
           private ResourceSecurityDescriptor desc = null;
    
           public MyDummyResource() throws Exception {
    
                this.desc = new ResourceSecurityDescriptor();
    
              // set security properties on the above object using get/set methods
              // in the API
            }
    
            public ResourceSecurityDescriptor getSecurityDescriptor() {
                return this.desc;
            }
        }
    

  2. A ResourceSecurityDescriptor object can be created similar to above, but initialized from a file and set in the constructor.

        public MyDummyResource implements SecureResource {
        
           private ResourceSecurityDescriptor desc = null;
    
                this.desc = new ResourceSecurityDescriptor("/path/to/security/file");
                this.desc.initialize();
            }
    
            public ResourceSecurityDescriptor getSecurityDescriptor() {
                return this.desc;
            }
        }
    

3.1.4. Common Configuration for server-side security descriptors

The next few sections deal with writing server side security descriptor files—that is, container, service and resource descriptor files to set various properties. Only the properties that are common all these descriptor are discussed here. Other properties specific to each descriptor are discussed in following sections.

When parameters are configured in multiple descriptors the order of precendence is resource, service and then container.

3.1.4.1. Configuring credentials

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

Example for option (a):

<serviceSecurityConfig xmlns="http://www.globus.org/descriptor/server">
   ...
   <proxy-file value="proxyFile"/>
   ...
</serviceSecurityConfig>

Example for option (b):

<serviceSecurityConfig 
            xmlns="http://www.globus.org/security/descriptor/service">
   ...
   <credential>
       <cert-key-files>
              <key-file value="keyFile"/>
              <cert-file value="certFile"/>
       </cert-key-files>
   </credential>
   ...
</serviceSecurityConfig>

[Note]Note

The above examples show use of service security descriptor. If setting in container security descriptor, set namespace and outer element as shown in Section 2, “ Security Descriptor Schemas ”.

Credentials can be configured at resource, service or container level and the framework will look for credentials in the following order:

  1. Resource credentials
  2. Service credentials
  3. Container credentials
  4. Default credentials. If credentials are not configured using any of the above methods, then underlying CoG JGlobus library is used. This will attempt to load the proxy certificate of the user that is running the container as described in Section 3.4, “Proxy file Location”.

3.1.4.2. Configuring replay attack prevention parameters

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 rejected automatically, whereas messages within this window are checked against recently received messages through the use of the message UUID.

  • Parameter replay-attack-fileter can be set to true or false to enable or disable replay attack prevention framework. By default, this feature is enabled.

    <serviceSecurityConfig 
                xmlns="http://www.globus.org/security/descriptor/service">
       ...
           <replay-attack-filter value="true"/>
       ...
    </serviceSecurityConfig>
  • Parameter replay-attack-window can be set to number of minutes the replay window should be. By default it is 5 minutes.

    <serviceSecurityConfig 
                xmlns="http://www.globus.org/security/descriptor/service">
       ...
           <replay-attack-window value="100"/>
       ...
    </serviceSecurityConfig>
[Note]Note

The above examples show use of service security descriptor. If setting in container security descriptor, set namespace and outer element as shown in Section 2, “ Security Descriptor Schemas ”.

3.1.4.3. Reject Limited Proxy

This parameter can be used to configure if clients that present limited proxies can be allowed to authenticate successfully. By default, limited proxes are accepted.

<serviceSecurityConfig 
            xmlns="http://www.globus.org/security/descriptor/service">
   ...
       <reject-limited-proxy value="true"/>
   ...
</serviceSecurityConfig>
[Note]Note

The above examples show use of service security descriptor. If setting in container security descriptor, set namespace and outer element as shown in Section 2, “ Security Descriptor Schemas ”.

3.1.4.4. Context lifetime

When GSI Secure Conversation is used, a security context is established and by default the life of the context is determined by the least lifetime of the chain of certificates used in establishing the context. The value of the lifetime can be altered to be lesser than the above value by setting the value for following parameter in milliseconds.

<serviceSecurityConfig 
            xmlns="http://www.globus.org/security/descriptor/service">
   ...
       <context-lifetime value="1000"/>
   ...
</serviceSecurityConfig>
[Note]Note

The above examples show use of service security descriptor. If setting in container security descriptor, set namespace and outer element as shown in Section 2, “ Security Descriptor Schemas ”.

3.1.4.5. Configuring authorization mechanisms

The container and each service/resource can be configured with a chain of interceptor, where each interceptor is a Policy Decision Points (PDPs) or Policy Information Points (PIPs). The element authzChain can be used to configure it.

  • Each chain can contain an optional list of Bootstrap PIPs, an optional list of PIPs and a list of PDPs (with atleast one PDP).

  • Each interceptor name is scoped and the format is prefix:FQDN of the interceptor. For example, self:org.globus.wsrf.impl.security.authorization.SelfAuthorization. The prefix is used to allow multiple instances of the same intercepor to exist in the same PDP chain.

    Example:

    <serviceSecurityConfig 
                xmlns="http://www.globus.org/security/descriptor/service">
       ...
    <authzChain>
    
       <pips>
    	<interceptor name="scope2:org.globus.sample.PIP1"/>
       </pips>
       <pdps>
            <interceptor name="foo1:org.foo.authzMechanism bar1:org.bar.barMechanism"/>
       </pdps>
    
    </authzChain>
       ...
    <serviceSecurityConfig/>
  • Bootstap PIPs are optional and by default, org.globus.wsrf.impl.security.authorization.X509BootstrapPIP is used by the framework. Any other PIPs listed with in the <bootstrapPips> element is appended to the default PIP. If the configuration should override (that is X5008BootstapPIP should not be used), the optional attribute overwrite can be set to true.

    <serviceSecurityConfig 
                xmlns="http://www.globus.org/security/descriptor/service">
       ...
    
    <authzChain combiningAlg="org.globus.sample.SampleAlg>
       <bootstrapPips overwrite="true"
          <interceptor name="scope1:org.globus.sample.BootstrapPIP1"/>
    </bootstrapPips>
       <pips>
    	<interceptor name="scope2:org.globus.sample.PIP1"/>
       </pips>
       <pdps>
    	<interceptor name="scope3:org.globus.sample.PDP1"/>
       </pdps>
    </authzChain>
    ..
    </serviceSecurityConfig>
    

    In the above case, X509BootstrapPIP will not be used adn the BoostrapPIP1 will be used.

    <serviceSecurityConfig 
                xmlns="http://www.globus.org/security/descriptor/service">
       ...
    
    <authzChain combiningAlg="org.globus.sample.SampleAlg>
       <bootstrapPips>
          <interceptor name="scope1:org.globus.sample.BootstrapPIP1"/>
    </bootstrapPips>
       <pips>
    	<interceptor name="scope2:org.globus.sample.PIP1"/>
       </pips>
       <pdps>
    	<interceptor name="scope3:org.globus.sample.PDP1"/>
       </pdps>
    </authzChain>
    ..
    </serviceSecurityConfig>
    

    In the above case, X509BootstrapPIP followed by BoostrapPIP1 will be used.

  • The authorization chain can be configured with a combining algorithm using the attribute combiningAlg. The value should be a FQDN of a class that implements org.globus.wsrf.security.authorization.AuthorizationEngineSpi. The attribute is optional and by default the org.globus.wsrf.impl.security.authorization.providers.PermitOverrideAlgorithm is used.

    Example:

    <serviceSecurityConfig 
                xmlns="http://www.globus.org/security/descriptor/service">
       ...
    
    <authzChain combiningAlg="org.globus.sample.SampleAlg>
       <pips>
    	<interceptor name="scope2:org.globus.sample.PIP1"/>
       </pips>
       <pdps>
    	<interceptor name="scope3:org.globus.sample.PDP1"/>
            <interceptor name="scope4:org.globus.sample.PDP2"/>
       </pdps>
    </authzChain>
    ..
    </serviceSecurityConfig>
    

    In the above, the default X509BootstrapPIP will be used. Following that, the PIPs, PIP1 will be invoked to collect attributes. Finally the SampleAlg combining algorithm is used with the configured PDPs (PDP1 and PDP2) are run to determine the decision.

  • Each interceptor can specify a parameter value and the schema defines it as xsd:any to allow for any user defined parameters. The parser extracts the elements in <parameter> element and returns them as DOM Element. It is left up to the Interceptor to parse the Element. The DOM object created is placed in the ChainConfig object passed to the authorization engine as a parameter called "parameterObject". The prefix will be the scope specified in the interceptor name.

    Since schema validation is done, a schema must be supplied for the user defined parameters. The schema location is loaded as a resource and hence can be included in some jar placed in GLOBUS_LOCATION lib directory.

  • The toolkit provides a parameter schema by default, that allows for a name/value pair, where the value is a string. Example :

    <containerSecurityConfig xmlns="http://www.globus.org/security/descriptor/container" 
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
      xsi:schemaLocation="http://www.globus.org/security/descriptor 
      name_value_type.xsd"
      xmlns:param="http://www.globus.org/security/descriptor">
       <authzChain>
         <pdps>
           <interceptor name="gridmapAuthz:org.globus.wsrf.impl.security.GridMapAuthorization">
                        <parameter>
                            <param:nameValueParam>
                                <param:parameter name="gridmap-file"
                                                value="/home/user1/grid-mapfile"/>
                            </param:nameValueParam>
                        </parameter>
               </interceptor>
    	</pdps>
        </authzChain>
    </containerSecurityConfig>
        
        

    When the above is parsed, a DOM Element is constructed with element <param:nameValuParam> and stored in the ChainConfig object as parameter with name "gridmapAuthz:parameterObject". The GridMapAuthorization PDP, uses ObjectDeserializer to retrieve the name/value pairs.

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.

Table 2. Builtin PDPs

Default Descriptor Configuration Default Prefix Reference
acl aclAuthz Access Control List PDP
none noneAuthz NoAuthorization PDP
self selfAuthz

Self Authorization PDP

gridmap gridmapAuthz

GridMapAuthorization PDP

identity idenAuthz

IdentityAuthorization PDP

host hostAuthz

HostAuthorization PDP

samlCallout samlAuthz

SAMLAuthorizationCallout PDP

userName userNameAuthz

Username Authz PDP

samlAssertion samlAssertionAuthz SAML Authz Assertion PDP
N.A N.A ResourceProperties PDP

Other than these, any custom authorization scheme could be configured with its own configuration information. Refer to Section 4.6.2.3, “Writing a custom server-side authorization mechanism”, for details on writing a custom authorization mechanism.

3.1.5. Container-only security configuration

Other than the security properties that have been described in previous section, few more properties are exclusive to the container security descriptor.

3.1.5.1. Administrator Authorization Chain

Other than the container/service/resource authorization, a administrative level authorization chain can be configured using the <adminAuthz> element. The decision returned by this chain, overrides subsequent authorization decision. That is, if the administator's authorizaiton chain returns a deny, the rest of the configured authorization (at container/service/resource) is not evaluated and the operation is denied. If the the administattor's chain returns the permit, the rest of the configuration is evaluated to see if the operation is allowed.

The element has the same schema as described in Section 3.1.4.5, “Configuring authorization mechanisms”, with the outer element called adminAuthz in palce of authzChain.

Example:

<containerSecurityConfig 
            xmlns="http://www.globus.org/security/descriptor/container">
   ...
<adminAuthz>

   <pips>
	<interceptor name="scope2:org.globus.sample.PIP1"/>
   </pips>
   <pdps>
        <interceptor name="foo1:org.foo.authzMechanism bar1:org.bar.barMechanism"/>
   </pdps>

</adminAuthz>
   ...
<containerSecurityConfig/>
3.1.5.2.  Default Authorization Chain

This element is used to configure default properties for any interceptor configured in authorization chains. The schema for this is similar to the authorization chain specification as described in Section 3.1.4.5, “Configuring authorization mechanisms” and allows for xsd:any as interceptor parameter.

<defaultAuthzParam>
	<interceptor name="scope1:org.globus.sample.SamplePDP"/>
                    <parameter>
                        <param:nameValueParam>
                            <param:parameter name="policy-file" 
                                            value="/home/user1/samplePDPConfig"/>
                        </param:nameValueParam>
                    </parameter>
	</interceptor>
</defaultAuthzParam>

3.1.5.3. Context Timer Interval

When GSI Secure Conversation is used, a security context is established and a worker thread cleans up expired contexts. This parameter sets the interval on the timer thread that collects expired contexts established when GSI Secure Conversation is used. The value is the number of seconds between each run and defaults to 10minutes.

<containerSecurityConfig 
            xmlns="http://www.globus.org/security/descriptor/container">
   ...
       <context-timer-interval value="100000"/>
   ...
</containerSecurityConfig>
3.1.5.4. Replay Timer Interval

This parameter sets the interval on the timer thread that collects expired message digest ids, stored to prevent replay attack in the case of Secure Message. The value is set in seconds and the default value is 1 minute.

<containerSecurityConfig 
            xmlns="http://www.globus.org/security/descriptor/container">
   ...
       <replay-timer-interval value="100"/>
   ...
</containerSecurityConfig>
3.1.5.5. Trusted Certificates

This parameter sets location of trusted certificates to be used. The value should be a comma separated list of locations.

<containerSecurityConfig 
            xmlns="http://www.globus.org/security/descriptor/container">
   ...
       <trusted-certificates value="/home/user1/trustedCerts /home/user1/newCerts"/>
   ...
</containerSecurityConfig>

If this configuration is not set, the underlying CoG JGlobus library is used to pick up trusted certificates. The library attempts to load the certificates as described in Section 3.1, “Trusted Certificates Location”.

3.1.6.  Service Security Descriptor Configuration

3.1.6.1. Configuring authentication methods

The authentication method required for accessing a service can be configured in the descriptor using the <auth-method> element. A per method configuration can also be done as described in Section 3.1.6.3, “Configuring per method authentication and run-as”.

Currently, the following authentication methods are supported:

Table 3. Authentication methods

Authentication Method Element Options/Notes
No Authentication <none/>

This method cannot be specified with any other authentication method.

GSI Secure Message <GSISecureMessage/>

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 and signed).

GSI Secure Conversation <GSISecureConversation/>

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 and signed).

GSI Secure Transport Authentication <GSITransport/>

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 and signed).

Notes:

  • Multiple authentication methods can be specified under the <auth-method> element (except for the <none/> method, see above). As long as one of the specified authentication methods is used, access to the service is allowed.
  • If multiple authentication methods are specified, they need to be in alphabetical order. That is the following order needs to be maintained: GSISecureConversation, GSISecureMessage, GSISecureTransport. This does not imply that all three need to be specified, but just indicates that the specified authentication mechanisms needs to comply with above order.
  • 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:

<serviceSecurityConfig xmlns="http://www.globus.org/security/descriptor/service">

   <!-- default auth-method for any other method -->
   <auth-method>
      <GSISecureConversation/>
   </auth-method>
</securityConfig>
3.1.6.2. Configuring the 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 also as described in Section 3.1.6.3, “Configuring per method authentication and run-as”. Currently, the following run-as identities are supported:

Table 4. Run-as methods

Element Functionality
<run-as value="caller"/>

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 grid map file authorization was performed, a UserNamePrincipal is added to the principal set of the Subject object.
<run-as value="service"/> 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).
<run-as value="resource"/> The service method will be run with the security identity of the resource. If no resource is specified or if the resource does not have a configured subject, credentials in this order of occurrence will be used: service credential, container credential.
<run-as value="system"/> The service method will be run with the security identity of the container.

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. It is installed by default.
  • 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:

<servicesecurityConfig xmlns="http://www.globus.org/security/descriptor/service">

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

</serviceSecurityConfig>
3.1.6.3. Configuring per method authentication and run-as

A per method configuration can be used to define expected authentication method for the method and also a run-as configuration. The element methodAuthentication is used to list all the method configuration. For each method, element method with method name as attribute needs to be used. If a method does not have such a configuration, default configuration, described in the last two sections are used.

Example


<serviceSecurityConfig 
            xmlns="http://www.globus.org/security/descriptor/service">
 ...
   <method name="findServiceData">
      <auth-method>
         <none/>
      </auth-method>
   </method>

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

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

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

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

In the above example:

  • the findServiceData() operation does not require any authentication. Since no run-as per method is specified, default specification, system-identity is used.
  • the destroy() operation requires either GSI Secure Message authentication with either level of protection or GSI Secure Conversation authentication with integrity protection. Default run-as is used.
  • substract method does not have a specific authentication speicifed, so the default GSI Secure Conversation is used. But the operation is run with service identity.
  • all other operations must be authenticated with GSI Secure Conversation with either level of protection.

3.2. Configuring Programmatically

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.

Table 5. Descriptor classes

Descriptor TypeJava Class Representation
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 3.1.1, “Configuring Container Security Descriptor”, 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 3.1.2, “Configuring Service Security Descriptor”, 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.ResourceSecurityConfig. Refer to the description of resource security descriptors in Section 3.3, “Resource security descriptors” for more details.

Client Security Descriptor

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

To initialize the descriptor, use the API in org.globus.wsrf.impl.security.descriptor.ClientSecurityConfig.

3.3. Resource security descriptors

Resource level security can be set up using a resource security descriptor. The configuration properties and schema are identical to service security descriptor. A resource security descriptor overrides any service or container level security settings. 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.

A resource security descriptor object can be created by reading settings from a descriptor file. The file needs to be written as described in Section 3.1.4, “Common Configuration for server-side security descriptors ”. Refer to Section 3.1.3, “Configuring Resource Security Descriptor” forinformation on configuring resource security descriptors.

The Resource security descriptor object also exposes an API to set and get all properties that are described in Section 3.1.4, “Common Configuration for server-side security descriptors ”. The descriptor can be set up programmatically using the API

Examples:

The following code snippet creates a resource descriptor object directly:

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

To set default gridmap.

   GridMap gridmap = new GridMap();
   // set GridMap mappings
   desc.setDefaultGridMap(gridmap);
  

To set credentials

  import javax.security.auth.Subject;

  Subject subject = new Subject;
  // set public/private credentials on subject object
  desc.setSubject(subject);
  

To set up authorization chain

  String[] pdpChain = new String[2];
  pdpChain[0] = "prefix1:some.PDP";
  pdpChain[1] = "prefix2:some.other.PDP";

  // Similar API for PIPs and Bootstrap PIP
  String[] pips = new String[1];
  pips[0] = "pip1:some.PIP";

  ResourcePropertiesChainConfig config = new ResourcePropertiesChainConfig();
  config.setProperty("prefix1", "property1", value1);

  AuthorizationEngine engine = 
        AuthzUtil.getAuthzEngine("Chain name", pips, pdpChain, config);
  desc.setAuthzEngine(engine);
  

To force initializing of resource security descriptor

  desc.setInitialized(false);
  desc.initialize();
  

4. Client side Security Descriptors

4.1. Configuring Using Files

4.1.1. Configuring Client Security Descriptor

  1. Client security descriptors from a file can be configured directory on stub as follows:

    // Client security descriptor file 
    String CLIENT_DESC = 
      "org/globus/wsrf/samples/counter/client/client-security-config.xml";
    //Set descriptor on Stub 
    ((Stub)port)._setProperty(Constants.CLIENT_DESCRIPTOR_FILE, CLIENT_DESC);
    

  2. Client security descriptors object can be constructed from a file and configured directory on stub as follows:

    // Client security descriptor file 
    String CLIENT_DESC = "org/globus/wsrf/samples/counter/client/client-security-config.xml";
    ClientSecurityDescriptor desc = new ClientSecurityDescriptor(CLIENT_DESC);
    //Set descriptor on Stub 
    ((Stub)port)._setProperty(Constants.CLIENT_DESCRIPTOR, desc);
    

    [Note]Note

    This takes precedence over 1

  3. Client security descriptors object can be created and get/set methods can be used to set security properties. The object then ca be configured on stub as follows:

    ClientSecurityDescriptor desc = new ClientSecurityDescriptor();
    
    // set security properties on the above object using set/get object
    
    //Set descriptor on Stub 
    ((Stub)port)._setProperty(Constants.CLIENT_DESCRIPTOR, desc);
    

    [Note]Note

    This takes precedence over 1

4.1.2. Client Security Descriptor Configuration

4.1.2.1. Configuring credentials

The client can be configured with credentials using the descriptor. The credentials can be set using either: a) the path to a proxy file, or b) the path to a certificate and key file. The credentials can be configured by adding one of the following blocks to the client security descriptor.

Example for option (a):

<clientSecurityConfig xmlns="http://www.globus.org/descriptor/clent">
   ...
   <proxy-file value="proxyFile"/>
   ...
</clientSecurityConfig>

Example for option (b):

<clientSecurityConfig 
            xmlns="http://www.globus.org/security/descriptor/client">
   ...
   <credential>
       <cert-key-files>
            <key-file value="keyFile"/>
            <cert-file value="certFile"/>
       </cert-key-files>
   </credential>
   ...
</clientSecurityConfig>

If credentials are not configured using any of the above methods, then underlying CoG JGlobus library is used. This will attempt to load the proxy certificate of the user that is running the container as described in Section 3.4, “Proxy file Location”.

4.1.2.2. Configuring authorization mechanism

The <authz> element is used to determine the mechanism to use to authorize the server that is being contacted. Note that the security descriptor cannot be used to configure custom client authorization. Refer to Section 4.6, “Semantics and syntax of domain-specific interface” for details. The following values are currently supported:

Configuration Funcationality
noneNo authorization is done.
selfSelf authorization is done, i.e the server should be running with the same credentials as the client.
hostHost authorization is done, i.e the server should be running with credentials that have the host name it is running on embedded in it.
hostSelfHost authorization is done (i.e the server should be running with credentials that have the host name it is running on embedded in it). If that fails, an attempt at self authorization (i.e the server should be runnign with same credentials as client) is made.
any other stringIdentity authorization is done using the value as the identity, i.e the server should be running with identity specified as value.

The following sample configures self authorization:

  <clientSecurityConfig xmlns="http://www.globus.org/security/descriptor/client">
     ...
     <authz value="self"/>
     ...
  </clientSecurityConfig>

4.1.2.3. Configuring GSI Secure Conversation

The client can be configured to do GSI Secure Conversation using the element <GSISecureConversation>. The following subelements can be used to set various properties

ElementFunctionality
<integrity>Sets protection level to signature.
<privacy>Sets protection level to encryption (signature is also done).
<anonymous>Server is accessed as anonymous.
<delegation value="type of delegation">Determines the type of delegation to be done. The value can be set to full or limited. If the delegation element is not used, no delegation is done. If delegation is enabled, some form of client authorization is required.
<context-lifetime>Determines the lifetime of the context established. If not specified, the least lifetime of the chain of certificates used in establishing the context is used as context lifetime.

The following sample sets GSI Secure Conversation with privacy and full delegation:

  <clientSecurityConfig xmlns="http://www.globus.org/security/descriptor/client">
     ...
     <GSISecureConversation>
         <privacy/>
         <delegation value="full"/>
     </GSISecureConversation>
     ...
  </clientSecurityConfig>

4.1.2.4. Configuring GSI Secure Message

The client can be configured to do GSI Secure Message using the element <GSISecureMessage>. The following subelements can be used to set various properties:

ElementFunctionality
<integrity>Sets protection level to signature
<privacy>Sets protection level to encryption (signature is also done)
<peer-credential value="path to file with credentials to encrypt with">Sets the path to the file containing the credential to use if privacy protection is chosen.

The following sample sets GSI Secure Message with integrity:

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

     ...
     <GSISecureMessage>
         <integrity/>
     </GSISecureMessage>
     ...
  </clientSecurityConfig>

4.1.2.5. Configuring GSI Secure Transport

The client can be configured to do GSI Secure Transport using the element <GSISecureTransport>. The following subelements can be used to set various properties

ElementFunctionality
<integrity>Sets protection level to signature.
<privacy>Sets protection level to encryption (signature is also done).
<anonymous>Server is accessed as anonymous.

The following sample sets GSI Secure Transport with privacy and anonymous:

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

4.1.2.6. Configuring Username/Password

Username/password can be used for authentication by the client. This is configured using <username> and <passwordType> element. The usernam element allows for a string to be configured and the password configuration consists of a password and a type string.

Example configuration:


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

  <usernameType>
     <username value="tester1"/>
     <passwordType>
        <password value="TY^*(Hyu"/>
        <type value="someType"/>
     </passwordType>
  </usernameType>

  </clientSecurityConfig>

4.1.2.7. Configuring trusted credentials

Client side trusted credentials are configured similar to container security descriptor as described in Section 3.1.5.5, “Trusted Certificates”. The outer element and schema for client security descriptor as described in Section 2, “ Security Descriptor Schemas ” should be used.

If this configuration is not set, the underlying CoG JGlobus library is used to pick up trusted certificates. The library attempts to load the certificates as described in Section 3.1, “Trusted Certificates Location”.

4.2. Configuring Programmatically

Table 6. Descriptor classes

Descriptor TypeJava Class Representation
Client Security Descriptor

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

To initialize the descriptor, use the API in org.globus.wsrf.impl.security.descriptor.ClientSecurityConfig.

5. Other configuration

5.1. Configuring Default GridMap Files

The gridmap file is a common configuration in the toolkit and is typically configured within the GridmapPDP configuration. To specify a default value to be used across the toolkit, if not specified with in the GrimapPDP configuration, the defaultAuthz element in container security descriptor is used as described in Section 3.1.5.2, “ Default Authorization Chain”.

The gridmap authorization can be specified with any prefix, but the default configuration uses "gridmapAuthz" as shown in the example below.

Example:


<containerSecurityConfig xmlns="http://www.globus.org/security/descriptor/container" 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
   xsi:schemaLocation="http://www.globus.org/security/descriptor 
   name_value_type.xsd"
   xmlns:param="http://www.globus.org/security/descriptor">

   <defaultAuthzParam>
     <interceptor name="gridmapAuthz:org.globus.wsrf.impl.security.GridMapAuthorization">
                    <parameter>
                        <param:nameValueParam>
                            <param:parameter name="gridmap-file"
                                            value="/etc/grid-security/grid-mapfile"/>
                        </param:nameValueParam>
                    </parameter>
      </interceptor>
   </defaultAuthzParam>
</containerSecurityConfig>

If the grid map file is updated at runtime, it will be reloaded.