GT 3.9.5 Delegation Service: Developer's Guide

Introduction

Delegation service provides interface for service developers to be able to retrive a delegated credential, given the endpoint reference to the credential resource. No remote interface is provided for this functionality, but the access is through shared Java state. Also, the component provides for utility API that can be used for developing client side code to generate delegated credential and delegate it.

Architecture and design overview

Overview

This component offers an interface to accept a delegated credential, which it exposes as WS-Resources identified by an EPR which it returns to the delegator. It allows co-hosted services access to those credentials through shared Java state.

The delegation service exposes it's public key as a ResourceProperty. The public key of the DS is contained in a certificate chain for the host system (either as the EEC or a Proxy Certificate issued by the EEC), allowing the client to verify the validity of the public key. Clients of the DS delegate by extracting the public key from the certificate received in the response to the ResourceProperty lookup, resigning it into a proxy and then passing the Proxy Certificate and any certificates in the certificate chain to the DS via its interface.

Additionally the component allows for renewal of delegated credentials by the delegator. Other entities may subscribe in order to receive notification of renewals, allowing them to obtain the renewed credential.

This component has a Delegation Factory Service and Delegation Service. The Delegation Factory service exposes its public key as resource property. A delegate call on the factory, creates a resource in Delegation Service that represents the delegated credential. The delegate call returns a Endpoint Reference (EPR) that can be further used to refresh the credentials.

The services that are interested in the credential, can register a listener (an object that implements org.globus.delegation.DelegationRefreshListener) with the specific resource. This does not have a remote interface and 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.

Relationship to WS-Trust

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 probably do not achieve the "spirit" intended by the specification.

Normal Usage Patterns

Creation

  1. The client does a lookup on the Delegation Service (DS) for the Resource Property (RP) containing the certificate chain of the DS. To perform this lookup the client uses the EPR of the DS obtained from a 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.
  2. The client creates a proxy certificate binding public key of DS, obtained from certificate china in previous step, to a proxy identity of client.
    • Lifetime of proxy certificate defaults to lifetime of signing certificate (typically short-lived proxy)
  3. The client sends the proxy certificate (and chain) to DS; EPR identifying delegation is returned to client for use in subsequent invocations of other services co-hosted with DS.
    • EPR uniquely identifies delegation
    • Resource expires on proxy expiration
    • An ACL is created for the Proxy Resource, which contains the identity of the credential delegator.

Refresh

The original delegator of a credential may refresh the credential (i.e. replace it with a credential with a different credential, presumably one that has an expiration date later 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 Service.

Credential Storage

The Delegation Service uses a standard Grid service credential, namely a private key and certificate chain where the EEC has a DN containing the FQDN of the host on which the Delegation Service is running. The private key and certificate chain are stored on local disk, protected by local file system permissions (in PEM file in /etc/grid-security/containercert.pem).

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 use of the delegated credential by services in the hosting environment.

Access to Delegated Proxy Resources

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.

Registration for Renewal Events

Services internal to the hosting environment can register with a resource proxy to receive updated credentials when they renewed by the client. Such registrations are authorized in the same manner as direct access to the proxy. Registered client will have any renewed credentials pushed to them.

Public interface

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.

Usage scenarios

Client-side scenario

  • Prior to delegating, the client needs to get information about the public key of the Delegation Facory service, to be able to delegate on that. A utility API to do that is described here.
  • Once the delegation client has the public key of delegation factory service it needs to create a delegated credential on that and then use the remote interface on the factory and 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 API that can be used to refresh is described here

Service-side scenario

This section describes the usage scenario where some service is provided with a delegated credential EPR and needs to access the credential. Typically, as a part of application the delegated credential EPR is sent to the service and and it is assumed that the delegation service is cohosted (that is runs in the same hosting environment).

The service need to create a listener object that implements org.globus.delegation.DelegationRefreshListener interface. When the listener is registered, the service checks to ensure that delegator idenity matches either the identity set in the subject object that is set as part of API or is the peer subject in the current message context. Details about the API are described here.

Upon registering the listener, the delegated credential is set on the listener. Any time the credential is refreshed, it is set on the listener.

Tutorials

There are no tutorials available at this time

Feature summary

Features new in release 3.9.5

  • 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

Tested Platforms for Delegation Service

  • Windows XP
  • Linux (Red Hat 7.3)

Backward compatibility summary

The Delegation Service is a new component in GT version 4.0

Technology dependencies

The Delegation Service depends on the following GT components:

  • WS Authentication and Authorization Message-Level Security

The Delegation Service depends on the following 3rd party software:

  • Apache Axis

Security considerations

Key Pair Reuse

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 a 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.

Debugging

[information on standard debugging]

Troubleshooting

[help for common problems developers may experience]

Related Documentation