Table of Contents
The Delegation Service provides an interface that, given the endpoint reference to the credential resource, allows service developers to retrieve a delegated credential. While there is a remote interface to delegate and refresh a credential, no remote interface is provided for acquiring the delegated credential (that is, all access is through a shared Java state.)
In addition, the component provides a utility API that can be used for developing client side code to generate a credential, delegate it and refresh it.
Features new in GT 4.0
- Provides an interface for the delegation and renewal of credentials to a host.
- Allows for a single delegated credential to be reused across multiple service invocations (e.g. GRAM jobs).
Other Supported Features
- The Delegation Service is a new component in GT 4.0.
Deprecated Features
- The Delegation Service is a new component in GT 4.0.
Tested Platforms for Delegation Service
- Windows XP
- Linux (Red Hat 7.3)
Tested Containers for Delegation Service
- Java WS Core container
- Tomcat 5.0.30
The Delegation Service depends on the following GT components:
- WS Authentication and Authorization
- Java WS Core
The Delegation Service depends on the following 3rd party software:
- Apache Axis
The current design re-uses the keys associated with the delegation service for each of the proxy certificates delegated to it. During a security review it was pointed out that while this was fine from a cryptographic standpoint, compromising this single long lived key pair may significantly extend the time for which a single intrusion (presuming an exploitable security flaw making the intrusion possible) is effective.
This can be remedied by either frequently regenerating the key pair used by the delegation service, which can be accomplished with a simple cron job, or by generating a new key pair for each new delegation. The later of these approaches requires changes to the design and may be adopted in future versions of the toolkit. For the time being we recommend the former approach should this issue concern you.
The delegation client that is distributed with the toolkit allows for delegation of credentials even when no authorization of the server is done. Also, when using secure message authentication the authorization of the server is done after the completion of the operation. These two scenarios could lead to the delegation of credentials to a malicious server.
To prevent this users should use secure transport (HTTPS) or GSI secure conversation and appropriate client side authorization.
This component offers an interface for delegating credentials and subsequently managing them. It exposes the delegated credentials as a WS-Resources and allows authorized co-hosted services to access these credentials through a Java API. Furthermore, it gives clients the ability to refresh and manage the lifetime of their delegated credentials.
This component has a Delegation Factory Service and Delegation Service. A delegate call on the factory creates a WS-Resource managed by the Delegation Service that represents the delegated credential. The delegate call returns a Endpoint Reference (EPR) that can be used to later refresh the credentials.
Services that are interested in the delegated credential can register a
listener (an object that implements org.globus.delegation.DelegationRefreshListener) with the
specific delegated credential resource. There currently is no remote interface for this, hence
only services that are in the same hosting environment can register
interest. The credentials are pushed to the listener anytime a refresh
is done.
In practice delegation is done as follows. The Delegation Factory Service publishes its certificate chain, including the service's certificate, as a Resource Property. In the first step of the delegation process the client obtains this certificate chain, validates and authorizes it, and extracts the public key from the Delegation Factory Service certificate. The client then creates the proxy certificate it is going to delegate by binding, i.e. signing, the service's public key to the proxy certificate information using its private key. In the third and final step the client passes the certificate chain that starts with the proxy certificate to the Delegation Factory Service, which upon receipt replies with the address to the created delegated credential WS-Resource.
Additionally, the component allows the delegator to renew delegated credentials. Credential renewal follows the same steps as the initial delegation except for the final step, in which the client acts against its WS-Resource instead of the Delegation Service Factory.
The Delegation service uses WS-Trust messages as described in the WS-Trust specification. However, it should be noted that these messages are underspecified (the contents of the basic WS-Trust envelop are xsd:any) and the contents of these messages for the Delegation Services are simplistic and do not achieve the "spirit" intended by the specification.
The client does a lookup on the Delegation Factory Service (DFS) for the Resource Property (RP) containing the certificate chain of the DFS. To perform this lookup the client uses the EPR of the DFS obtained from an RP of another application (e.g. GRAM, RFT) or some other OOB method.
- This lookup is secured via transport-level security. The client and server mutually authenticate and authorize each other. Messages are integrity protected.
The client creates a proxy certificate by binding the public key of the DFS, obtained from the certificate chain in the previous step, to the proxy identity of the client.
- The lifetime of a proxy certificate defaults to the lifetime of the signing certificate (typically a short-lived proxy).
The client sends the proxy certificate (and chain) to the DFS. An endpoint reference (EPR) for the delegated credential is returned to client, which the client may use in subsequent invocations of other services co-hosted with the Delegation Service.
- The resource expires on proxy expiration.
- An ACL is created for the delegated credential resource, which contains the identity of the credential delegator.
The original delegator of a credential may refresh the credential (i.e. replace it with a different credential, presumably one that has an expiration date farther in the future). The usage pattern for this method is identical to the Creation method described in the previous section, with the exception that the EPR of the previously created Delegation Resource is used as opposed to the EPR of the Delegation Factory Service.
The Delegation Factory Service and the Delegation Service use standard Grid service credentials, namely a private key and certificate chain where the EEC has a DN containing the FQDN of the host on which the services are running. The private key and certificate chain are stored on local disk, protected by local file system permissions. By default the PEM files /etc/grid-security/containercert.pem and /etc/grid-security/containerkey.pem are used.
When a delegated proxy credential is persisted to disk, it is stored as a serialized JAVA object in ~globus/.globus/persisted/{ip addr}/DelegationResource/. The private key of the Delegation Service is stored with the delegated proxy certificate to ease the use of delegated credentials by services in the hosting environment.
After delegating a credential to the Delegation Service a client will typically invoke an application service (e.g. GRAM, RFT) that requires the use of such a delegated credential. In such situations the client will pass the EPR of the delegated credential to the service which it is invoking.
The service will use an internal hosting environment API (as opposed to a web services method) to access the delegated credential. This interface provides the identity of the requesting client to the underlying software, which verifies that the client identity is present in the ACL of the proxy resource before returning the requested credential.
Services internal to the hosting environment can register with a resource proxy to receive updated credentials when they are renewed by the client. Such registrations are authorized in the same manner as direct access to the proxy. Registered services will have any renewed credentials pushed to them.
The semantics and syntax of the APIs and WSDL for the component, along with descriptions of domain-specific structured interface data, can be found in the Public Interface Guide.
- Prior to delegating, the client needs to get information about the public key of the Delegation Factory Service. A utility API to do that is described here.
- Once the delegation client has the public key of the Delegation Factory Service, it needs to create a delegated credential using that public key and then invoke the remote interface on the factory to delegate the credential. A utility API to do all of the above is described here. The Endpoint Reference that is returned by this operation can be distributed to services that the user would like to delegate its rights to.
- The user may need to refresh the delegated credential. The onus is on the user to do this prior to expiration of the delegated credential. If the user does not refresh the credential, the expired credential will be garbage collected and the Endpoint Reference cannot be reused. A utility API that can be used to refresh is described here.
This section describes the usage scenario where a service is provided with a delegated credential EPR and needs to access the credential. Typically, as a part of an application the delegated credential EPR is sent to the service and and it is assumed that the delegation service is co-hosted (that is, it runs in the same hosting environment).
The service needs to create a listener object that implements
the org.globus.delegation.DelegationRefreshListener
interface and register the listener with the Delegation Service. Upon registering the listener the Delegation Service checks that the delegator identity matches either the identity passed in the
subject object or the identity contained in the peer subject
associated with the current message context. Once the listener has been authorized the delegated credential is made available to the listener. Details about the API are described here.
Log output from the delegation service is a useful tool for debugging issues. Logging in the delegation service code is based on the Jakarta Commons Logging API and is described in more detail here. As described in the above section, configuration files need to be edited to enable logging at different levels. For example, to see all debug logging statements for the delegation service, the following lines need to be added:
log4j.category.org.globus.delegation.service=DEBUG log4j.category.org.globus.delegation.factory=DEBUG
Debugging information from delegation clients can be obtained by setting the following line in the client side logging configuration file:
log4j.category.org.globus.delegation.client=DEBUG
![[Note]](../../../../../docbook-images/note.gif) | Note |
|---|---|
Client side logging configuration has to be done in $GLOBUS_LOCATION/log4j.properties. |
This error occurs when attempting to register a listener with a delegated credential resource without a JAAS subject. There are two ways of registering: either the JAAS subject can be explicitly passed using the API or the JAAS subject can be picked up from the current message context (the subject representing the client). If the later mechanism for registering is used and there is no client credential associated with the thread that is calling the register function, then this exception is thrown. If this occurs, make sure to use the API call that explicitly passes the subject.
Only the user who created the delegated credential is allowed to access it. There are two sets of API functions for getting the credential and registering listeners: one in which the caller's DN is picked up from the current thread and the other in which a JAAS subject (containing the caller's DN) is explicitly passed as a function parameter. If the caller's DN (picked up from thread or specified explicitly) does not match the DN of the user who created the credential, this error is thrown. Ensure that the DN explicitly specified or the client DN associated with the thread matches the creator's DN.
| Note |
|---|---|
The test user DN specified in the error message is just a placeholder and will contain the actual DN of the user attempting to access the credential. |
Also, for security related troubleshooting the CoG FAQ might prove useful (especially sections on configuring credentials, CAs and so on).
- WS-Security
- WS-Security: X.509 Certificate Tokens
- WS-Trust
- RFC 3820 Proxy Certificates