GT4 Delegation Service Public Interfaces

The delegation factory service exposes its public certificate as a resource property and allows clients to delegate credentials bound to that public key. Upon delegation an Endpoint Reference(EPR) to the delegated credential, which is implemented as a resource of the delegation service, is returned to the client. The client can use this EPR to provide a reference to the delegated credential to other services.

The delegation service itself has an interface to allow refreshing the credentials remotely. Other co-hosted services can register interest in delegated credentials through listeners and be notified when credentials are refreshed.

1.2. Component API

Some relevant API:

org.globus.delegation.DelegationUtil
org.globus.delegation.DelegationRefreshListener
org.globus.delegation.delegationService.DelegationPortType
org.globus.delegation.delegationService.DelegationFactoryPortType

Complete API:

2. Semantics and syntax of the WSDL

2.1. Protocol overview

The delegation service allows for delegation of credentials and is based on the WS-Trust specification. A WSDL interface to refresh the credentials remotely is also provided. Access to these credentials is restricted to co-hosted services, i.e services that are run in the same container, and is done using shared Java state. Co-hosted services interested in the credentials can register listeners and will be notified upon credential refresh.

2.2. Operations

2.2.1. Delegation Factory Service

RequestSecurityToken: This operation allows for a security token to be sent to the service.

2.2.2. Delegation Service

refresh: This operation is used to refresh a delegated credential. When invoked, all services that have registered interest in the credential through listeners are notified.

2.3. Resource properties

2.3.1. Delegation Factory Service

CertificateChain: This resource property is used to expose the certificate used by delegation service.

2.4. Faults

All operations on delegation service and delegation factory service throw RemoteException in case of failure.

2.5. WSDL and Schema Definition

3. Command-line tools

Please see the Delegation Service Command Reference.

4. Overview of Graphical User Interface

There is no GUI for the Delegation Service.

5. Semantics and syntax of domain-specific interface

5.1. Delegation Service API

The org.globus.delegation.DelegationUtil provides an API that allows users to get the certificate chain resource property exposed by the Delegation Factory Service, delegate to a service, and to refresh and register listeners.

5.1.1. To get certificate chain of delegation factory service

static X509Certificate[] getCertificateChainRP(String delegationUrl)

This takes an endpoint URL to a Delegation Factory Service and queries the CertificateChain resource property. The chain of certificates is returned as an array of X509Certificate. The client needs to delegate on the first certificate in the returned chain.

5.1.2. To delegate

public static EndpointReferenceType delegate(String delegationServiceUrl,
                                                 GlobusCredential issuingCred,
                                                 X509Certificate certificate,
                                                 int lifetime,
                                                 boolean fullDelegation,
                                                 ClientSecurityDescriptor desc)

This utility method is used to create the security token to delegate using the issuingCred and certificate parameters. The lifetime and type of the delegated credential created is determined by the lifetime and fullDelegation parameters. The security token (delegated credential) thus created is then stored by the Delegation Factory Service specified by the delegationServiceUrl. The client security descriptor determines the authentication mechanism, protection and authorization settings to use.

The Endpoint Reference that is returned points to the delegated credential and can be used by co-hosted services (services in the same hosting environment) to retrieve the delegated credential.

5.1.3. To refresh a delegated credential

public static void refresh(GlobusCredential issuingCred,
                               X509Certificate certToSign,
                               int lifetime,
                               boolean fullDelegation,
                               ClientSecurityDescriptor desc,
                               EndpointReferenceType epr)

This method can be used to refresh a delegated credential that is referred to by the EPR epr. A new delegated credential is created using the issuingCred, certToSign, lifetime and fullDelegation parameters. The client security descriptor determines the authentication mechanism, protection and authorization type to use.

5.1.4. To register listener

static void
        registerDelegationListener(EndpointReferenceType epr,
                                   DelegationRefreshListener listener,
                                   Subject subject)

This method registers the listener listener with the delegation resource referenced by epr. The operation is permitted only if the identity in the subject object matches that of the user who delegated the credential.

static void
        registerDelegationListener(EndpointReferenceType epr,
                                   DelegationRefreshListener listener)

This method provides the same functionality as the previous one, except that the subject object is picked up from the property org.globus.wsrf.security.Constants.PEER_SUBJECT in the current message context. If the identity of the user who delegated the credential matches that of the subject object referred to by the property, then the operation is permitted.

6. Configuration interface

6.1. Configuration overview

The security settings for Delegation Factory Service and Delegation Service can be configured by modifying the security descriptors. The descriptors allow for configuring the credentials that will be used by the services and the type of authentication and message protection required, as well as the authorization mechanism.

By default, the following configuration is installed:

Delegation Factory Service:
- Credentials are determined by the container level security descriptor. If there is no container level security descriptor or if it does not specify what credentials to use then default credentials are used.
- Authentication and message integrity protection is enforced for the requestSecurityToken operation. Other operations do not require authentication. This means that you may use any of GSI Transport, GSI Secure Message or GSI Secure Conversation when invoking the requestSecurityToken operation on the delegation factory service.
- Access is authorized using the grid map mechanism and no grid map is configured in the service by default. If a grid map is configured in the container level security descriptor, it is used. To configure a grid map file for this service refer to instructions in the next section.
Delegation Service
- Credentials are determined by the container level security descriptor. If there is no container level security descriptor or if it does not specify what credentials to use then default credentials are used.
- Authentication and message integrity protection is enforced for all operations. This means that you may use any of GSI Transport, GSI Secure Message or GSI Secure Conversation when interacting with the delegation service.
- Access to resources managed by the Delegation Service is managed using the gridmap mechanism. The gridmap used is resource specific and is populated with the subject of the client that originally created the resource. This implies that only the user who delegated can access (and refresh) the delegated credential.

	Note
	Changing required authentication and authorization methods will require corresponding changes to the clients that contact this service.

	Important
	If the service is configured to use GSI Secure Transport, then container credentials are used for the handshake, irrespective of whether service level credentials are specified.

6.2. Syntax of the interface

To alter the security descriptor configuration refer to Security Descriptors.

To alter the security configuration of the Delegation Factory Service, edit the file $GLOBUS_LOCATION/etc/globus_delegation_service/factory-security-config.xml.

Note

To either specify a gridmap file different from the container level configuration or to add one if the container security descriptor does not specify one, the following needs to be added to the Delegation Factory security descriptor.

<securityConfig xmlns="http://www.globus.org">

           .

           .

           .

    <gridmap value="path/to/gridmap/file"/>

</securityConfig>

To alter the security configuration of the Delegation Service, edit the file $GLOBUS_LOCATION/etc/globus_delegation_service/service-security-config.xml

7. Environment variable interface

Refer to the environment variable interface for details.

The environment variables described above only affect the selection of credentials if no credentials are specified in any of the applicable security descriptors.