Java WS A&A Security Descriptor Framework

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

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

If the security descriptor file is altered at runtime, it will not be reloaded

If security properties are configured in multiple locations, then the following order of precedence is used

This section describes configuration of the container security descriptor.

To configure container level credentials, refer to Section 1, “Credentials”

To configure authorization at container level for use if not overridden by service or resource level policy, refer to Section 5, “Authorization”

Other than the container/service/resource authorization, an administrative-level authorization chain can be configured using the <adminAuthz> element. If the administrator's authorization chain returns a deny, the rest of the configured authorization (at container/service/resource) is not evaluated and the operation is denied. If the administrator'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 inSection 5, “Authorization”, with the outer element called adminAuthz in place ofauthzChain.

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/>

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 5, “Authorization” and allows for xsd:any as the 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>

Container can choose to require that clients use full proxies for access and reject limited proxies. To configure such a policy, refer to Section 2, “Reject Limited Proxy”

You can control the lifetime of the context with GSI Secure Conversation as an authentication mechanism, as described inSection 4, “Context lifetime”.

You can control the replay attack window for services that allow for GSI Secure Message, as desribed inSection 3, “Replay attack prevention”.

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 10 minutes.

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

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>

This parameter sets the 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 1, “Trusted Certificates Location” .

Programmatic creation and altering of a service security descriptor is not discussed in detail here. Refer to Configuring Security Descriptor Programmatically for some details on using the API to modify a descriptor.

To configure credentials specific to your service rather than use the container level configuration, refer to Section 1, “Credentials”

This section describes configuring policy on the authentication mechanism required by your service. This specifies the security policy that determines the authentication methods clients should use for contacting your service.

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 inSection 5, “Authentication and run-as per-method”.

Currently, the following authentication methods are supported:

Notes:

Example:

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

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

This section describes the credentials your service should use for the operation being invoked. This is important if remote secure operations are being invoked from your service, since it determines what credentials are used for such an access.

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 inSection 5, “Authentication and run-as per-method”. Currently, the following run-as identities are supported:

Notes:

Example:

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

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

</serviceSecurityConfig>

This section describes configuring the authentication and run-as mechanism per method, rather than for the whole service.

A per-method configuration can be used to define expected authentication methods for the method and also a run-as configuration. The element methodAuthentication is used to list all the method's configuration. For each method, element method with method name as attribute needs to be used. The method name attribute can either be the local name of the method or a string representation of the QName of the method. If the QName is used, the toString() representation from the javax.xml.namespace.QName.toString(), should be used. For example,{http://foo.bar}methodName. If a method does not have such a configuration, the default configuration, as described in the last two sections, is used.

Example

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

     <method name="{http://foo.bar}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:

To configure authorization policy at the service level, refer to Section 5, “Authorization”. In addition to the authorization mechanisms shipped, you can write custom authorization mechanism for a service as described in Section 6, “Writing a custom authorization mechanism”

Your service can choose to require that clients use full proxies for access and reject limited proxies. To configure such policy, refer to Section 2, “Reject Limited Proxy”

If your service allows for GSI Secure Conversation as an authentication mechanism, you can control the lifetime of the context as described inSection 4, “Context lifetime”.

If your service allows for GSI Secure Message, you can control the replay attack window at the service level as desribed inSection 3, “Replay attack prevention”.

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

Resource level security can be set up using a resource security descriptor. The configuration properties and schema are identical to the 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 Common Configuration for server-side security descriptors. Refer to Section 1, “Configuring Resource Security Descriptor” for information on configuring resource security descriptors.

The ResourceSecurityDescriptor object also exposes an API to set and get all properties that are described inCommon 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 an 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 a resource security descriptor:

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

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/security/descriptor/service">
...
<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
	The above examples show use in the service security descriptor. If setting in the container security descriptor, the namespace and outer element should also be set as shown inSection 1, “Security Descriptor Schemas”.

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

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

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

	Note
	The above example shows use in the service security descriptor. If setting in the container security descriptor, set the namespace and outer element as shown inSection 1, “Security Descriptor Schemas”. (fixme doublecheck link)

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.

	Note
	The above examples show use in the service security descriptor. If setting in the container security descriptor, set the namespace and outer element as shown inSection 1, “Security Descriptor Schemas”.

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 less than the above value by setting the value for the following parameter in milliseconds:

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

	Note
	The above example shows use in the service security descriptor. If setting in the container security descriptor, the namespace and outer element must be set as shown inSection 1, “Security Descriptor Schemas”.

The container and each service/resource can be configured with a chain of interceptors, where each interceptor is a Policy Decision Point (PDP) or Policy Information Point (PIP).Refer to Section 2, “Authorization framework overview” for details on the authorization framework. The element authzChain can be used to configure this.

All PDPs and PIPs shipped with the toolkit are provided here: ???? and????.

The following PDPs are included in GT and are configured using short tags. The framework maps and plugs in the scoped name of the PDP at the time of authorization.

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

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

Example Bootstrap PIP:

package org.foobar;

import ....;
import org.globus.security.authorization.BootstrapPIP;

public class FooBootstrapPIP implements BootstrapPIP {



    public void initialize(String chainName, String prefix_, 
                           ChainConfig config) throws InitializeException {

        logger.debug("Initialize called");
    }

    public void collectRequestAttributes(RequestEntities requestAttrs)
            throws AttributeException {

        // add attributes to RequestEntities
    }

    public NonRequestEntities collectAttributes(RequestEntities requestAttr) {
     
        // any attributes for non request entities
    }

    public void close() throws CloseException {
    }

}

To use the above Bootstrap PIP, configure security descriptor as follows

    <authzChain combiningAlg="org.globus.sample.SampleAlg>
        <bootstrapPips "
             <interceptor name="scope1:org.foobar.GooBootstrapPIP"/>
        </bootstrapPips>
    </authzChain>

Example PIP:

package org.foobar;

import ....;

public class FooPIP implements PIPInterceptor {

   public void initialize(String chainName, String prefix, ChainConfig config)
            throws InitializeException {
            // initialize
   }

    public NonRequestEntities collectAttributes(RequestEntities requestAttr)
            throws AttributeException {

            // collect attributes, both for request entities and others
    }

    public void close() throws CloseException {

    }

}

To use the above PIP one would configure a service security descriptor with the following authorization settings:

        <authzChain>
            <pips>
                <interceptor name="scope2:org.foobar.FooPIP"/>
            </pips>
        </authzChain>

Example PDP:

package org.foobar;

import ....;

public class FooPDP implements PDP {

    public void initialize(String chainName, String prefix_, 
                           ChainConfig config) throws InitializeException {

        // use to read in configuration
     }

    public Decision canAccess(RequestEntities requestEntities,
                              NonRequestEntities nonRequestEntities)
            throws AuthorizationException {
            
        // evaluate to see if Subject can access
    }

    public Decision canAdminister(RequestEntities requestEntities,
                                  NonRequestEntities nonRequestEntities)
            throws AuthorizationException {

        // evaluate to see if Subject can administer
    }

     public void close() throws CloseException {

     }
}

To use the above PDP one would configure a service security descriptor with the following authorization settings:

        <authzChain>
            <pdps>
                <interceptor name="scope2:org.foobar.FooPDP"/>
            </pdps>
        </authzChain>

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/security/descriptor/client">
    ...
    <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 the underlying CoG JGlobus library is used. This will attempt to load the proxy certificate of the user that is running the container as described inSection 5, “Proxy file Location”.

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 Authorization domain-level interface for details. The following values are currently supported:

The following sample configures self authorization:

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

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

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>

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

The following sample sets GSI Secure Message with integrity:

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

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

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>

Username/password can be used for authentication by the client. This is configured using the <username> and <passwordType> elements. The username 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>

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

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 1, “Trusted Certificates Location” .

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 inSection 5, “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.GridMapPDP">
            <parameter>
                <param:nameValueParam>
                    <param:parameter name="gridmap-file"
                    value="/etc/grid-security/grid-mapfile"/>
                </param:nameValueParam>
            </parameter>
        </interceptor>
     </defaultAuthzParam>
</containerSecurityConfig>

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