GT 3.9.4 Component Guide to Public Interfaces: WS A&A Delegation Service

Semantics and syntax of APIs

Programming Model Overview

This component consists of two services: the delegation factory service and the delegation service

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

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

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:

Semantics and syntax of the WSDL

Protocol overview

The delegation service allows for delegation of credentials and is based on 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. Other co-hosted services interested in the credentials can register listeners and will be notified on credential refresh.

Operations

Delegation Factory Service

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

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.

Resource properties

Delegation Factory Service

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

Faults

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

Schema Definition

Command-line tools

Two command line clients are available as a part of this component:

globus-credential-delegate

Tool description

Used to contact delegation service and store a delegated credential. A delegated credential is created, stored in a delegation service and the Endpoint Referecne(EPR) of the credetial is written out to a file for further use.

Command syntax

globus-credential-delegate [options]
where options can be
-h <host>

Host on which delegation factory service is running. Defaults to localhost
-p <port>

Port on which delegation factory service is running. Defaults to 8080
-c <credFile>

Filename to read credential from. If not speecified, default proxy location is used.
-l <lifetime>

Lifetime for the created delegated credentials, specified in seconds. Defaults to 12 hours.
-d <true/false>

If set to "true", full delegation is done, if set to "false" limited delegation is done. Defaults to limited delegation.
-m <security mechanism>

Sets the security mechanism type. If set to 'msg' Secure Message is used, if set to 'conv' Secure Conversation is used or if set to 'trans' Secure Transport is used. Defaults to Secure Transport.
-n <protection type>

Sets the protection type. If set to 'sig' siganture is used, if set to 'enc' encryption is used. Defaults to signature.
-a <authz>

Type of client authorization to use. If set to "none" no authorization is done, "host" host authorization is done, "self"l; self authorization is done else the string specified is used as expected identity. Defaults to host authorization.
-o <filename>

Filename to write out EPR of delegated credential

globus-credential-refresh

Tool description

Used to refresh delegated credentials pointed to be specified EPR. A new credential is generated and the one the delegation service is overwritten.

Command syntax

globus-credential-refresh [options]
where options can be
-c <credFile>

Filename to read credential from. If not speecified, default proxy location is used.
-l <lifetime>

Lifetime for the created delegated credentials, specified in seconds. Defaults to 12 hours.
-d <true/false>

If set to "true", full delegation is done, if set to "false" limited delegation is done. Defaults to limited delegation.
-m <security mechanism>

Sets the security mechanism type. If set to 'msg' Secure Message is used, if set to 'conv' Secure Conversation is used or if set to 'trans' Secure Transport is used. Defaults to Secure Transport.
-n <protection type>

Sets the protection type. If set to 'sig' siganture is used, if set to 'enc' encryption is used. Defaults to signature.
-a <authz>

Type of client authorization to use. If set to "none" no authorization is done, "host" host authorization is done, "self"l; self authorization is done else the string specified is used as expected identity. Defaults to host authorization.
-e <filename>

Filename to read EPR of delegated credential from. Defaults to "delegatedCredEPR"

Overview of Graphical User Interface

There is no GUI for the Delegation Service.

Semantics and syntax of domain-specific interface

The org.globus.delegation.DelegationUtil provides API for users to be able to get the certificate chain exposed as resource property, delegate to a service, refresh and register listeners.

  • To get certificate chain of delegation factory service

    static X509Certificate[] getCertificateChainRP(String delegationUrl)

    This takes the endpoint to 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 on the returned chain.

  • 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 parameter. The lifetime and type of the delegated credential created is determined by lifetime and fullDelegation parameters. The security token (delegated credential) thus created is then stored in the delgation service specified by the delegationServiceUrl. The client security descriptor determines the authentication mechanism, protection and authorization type to use.

    The Endpoint Reference returned points to the delegated credential and can be used by cohosted services (services in the same hosting environment) to retrieve the delegated credential.

  • 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 refesh a delegated credential that is referred to by epr. A new delegated credential is created using issuingCred, certTosIgn, lifetime and fullDelegation. The client security descriptor determines the authentication mechanism, protection and authorization type to use.

  • 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 credentials in the subject object matches the user who delegated the credential.

    static void
        registerDelegationListener(EndpointReferenceType epr,
                                   DelegationRefreshListener listener)

    This API has the same functionality as the previous one. But 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 delegator of credential matches the value of the property, then the operation is permitted.

Configuration interface

Configuration overview

The security settings for Delegation Factory Service and Delegation Service can be configured by modifying the security descriptor. It allows for configuring in the credentials that will be used by the service, type of authentication and authorization that needs to be enforced.

By default, the following configuration is installed:

  • Delegation Factory Service:
    • Credentials set for use by container is used. If that is not specified, default credentials are used.
    • GSI Secure message authentication is enforced for requestSecurityToken operation. No authentication is required for all other operations.
    • Gridmap authorizatin is done and the gridmap file is read from /etc/grid-security/grid-mapfile.
  • Delegation Service
    • Credentials set for use by container is used. If that is not specified, default credentials are used.
    • GSI Secure message authentication is enforced for refresh operation. No authentication is required for all other operations.
    • Gridmap authorizatin is done and the gridmap file is read from /etc/grid-security/grid-mapfile.

Note: Changing required authentication and authorization method will require suitable changes to the clients that contact this service.

Syntax of the interface

To alter security descriptor configuration refer to Security Descritpors.

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

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

Environment variable interface

Refer to Environment variable interface for details.

The environment varaibles describe only affect if default credentials are used by the service and the credentials set in the delegation service or factory security descritpor override these settings.