GT 3.9.4 Authorization Framework: Security Descriptor
- Introduction
- Writing security descriptor file
- Programmatic altering of security descriptors
- Resource Security Descriptor
- Container-only Security Configuration
- Other Configuration
1. Introduction
Security descriptors contain various security properties like credentials, gridmap, required authentication and authorization and so on. There are three kinds of security descriptors in the code base for setting container, service and resource security properties, respectively:
- service security descriptor
- container security descriptor
- resource security descriptor
Each of these are represented as objects 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 The security descriptor file is altered at runtime, it will not be reloaded
Configuring service and container descriptor files:<globalConfiguration>
...
<parameter name="containerSecDesc" value="etc/container-security-config.xml">
...
<globalConfiguration>
...
<service name="my/dummy/service" provider="Handler" style="wrapped">
...
<parameter name="securityDescriptor" value="org/globus/wsrf/impl/security/descriptor/security-config.xml"/>
...
</service>
If the security descriptor is configured as a file, it is loaded as follows:
- As a file if absolute file path is sepecified
- As a resource (can be included as part of jar file)
- 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 relaoded. 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">Example for option (b):
...
<credential>
<key-file value="keyFile"/>
<cert-file value="certFile"/>
</credential>
...
</securityConfig>
<securityConfig xmlns="http://www.globus.org">
...
<proxy-file value="proxyFile"/>
...
</securityConfig>
The service will look for credentials in this order:
- Resource credentials
- Service credentials
- Container credentials
- 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 the <method name="qname"> elements. 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 |
|
<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 |
|
<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 |
|
<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.SecurityPolicyHandlerhandler 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:
|
<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 occurentce will be used: service credential, container credential. |
Notes:
- resource-identity is the default setting.
- The
org.globus.wsrf.impl.security.authentication.SecurityPolicyHandlerhandler 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="counter:add" xmlns:counter="http://www.globus.org/samples/counter">
<run-as>
<caller-identity/>
</run-as>
</method>
<method name="counter:subtract" xmlns:ogsi="http://www.globus.org/samples/counter">
<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 mechanism (also known as Policy Decision Point (PDP)), using the authz element. Each PDP name is scoped and the format is prefix:FQDN of PDP. For example, self:org.globus.wsrf.impl.security.authorization.SelfAuthorization. The authorization is deemed to be a permit if each of the authorization scheme in the chain returns a permit.
Example:
<securityConfig xmlns="http://www.globus.org">FIXME: detailed explanation may not be required here
...
<authz value="foo1:org.foo.authzMechanism, bar1:org.bar.barMechanism"/>
...
<securityConfig/>
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 is configured in the container, the information is picked up from the global configuration section of the deployment descriptor. If the authorization is configured at service level, the PDP is configured to pick up the information from service deployment descriptor. The resource level configuration has to be done programatically and is described here. In all three cases, the prefix specified in the authorization scheme configuration is used to get the right property. For example, all properties for foo1:org.foo.authzMechanism is picked up from properties that have been scoped with prexif 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 |
|
gridmap |
|
identity |
|
host |
|
samlCallout |
|
userName |
|
Other than these, any custom authorization scheme could be configured with its own configuration information. Refer to 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="ogsi:findServiceData" xmlns:ogsi="http://www.gridforum.org/namespaces/2003/03/OGSI">
<run-as>
<caller-identity/>
</run-as>
</method>
<method name="ogsi:destroy" xmlns:ogsi="http://www.gridforum.org/namespaces/2003/03/OGSI">
<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 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
|
| Service Security Descriptor | This is represented by
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
|
| Resource Security Descriptor | This is represented by To initialize the descriptor, i.e. load credentials and gridmap, use
the API in |
4. Resource Security Descriptor
Resource level security can be set using resource security
descritpor, 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 path to
credentials and gridmap. Similarly, either the service
authorization chain object or a comma separated list of PDP
names can be specified. In each of these cases, if the proeprties are
configured as filenames or PDP names as the case maybe, 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, by default for the service
authorization chain is picked up from global deployment
descriptor. To provide for other PDP configuration, it needs to be
set programatically, 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 initalized 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.
This sample creates a authorization chain to be set on the resource security descriptor programatically
// 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 requried 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">
...
<replay-attack-interval value="10000"/>
...
</securityConfig>
6 Other Configuration
Some other security properties that can be configured as a part of the container or service descriptor are described below:
<context-lifetime value="lifetime
in seconds"/> |
This sets the lifetime of the context that is created at the server end; the value is set in seconds. If this option is not specified, the default value is the lifetime of the credential. Relevant for all operations requiring GSI Secure Conversation authentication. |