GT 3.0 CAS: User's Guide

• Using the Community Authorization Service
• Generating CAS credentials:cas-proxy-init
• Using CAS credentials: cas-wrap
• CAS Service Data
• Writing CAS Clients

Using the Community Authorization Service

A typical CAS user will use only two CAS-specific commands: cas-proxy-init, which contacts a CAS server and obtains a credential, and cas-wrap, which wraps a grid-enabled client program, causing that client program to use the credential that was previously generated using cas-proxy-init. For example, a day in the life of a CAS user might look something like this:

        % grid-proxy-init
        % cas-proxy-init -t tag

The first line generates a Globus proxy credential; the second uses that credential to contact the CAS server and retrieve a CAS credential that includes all the permissions granted to the user by the community. The tag argument can be any string and is used to assign a name for that credential (cas-wrap uses this name to locate the credential).

2.Several times throughout the day, the user runs commands that look like:

        % cas-wrap -t tag grid-enabled-program args

This runs the program grid-enabled-program with arguments args, using the CAS credential that had been created by and assigned the name tag. For example:

        % cas-wrap -t my-community gsincftp myhost.edu

looks for a CAS credential with the name "my-community" (e.g., a credential that had been created using "cas-proxy-init -t my-community") and then runs the command "gsincftp myhost.edu", causing the gsincftp program to use that CAS credential to authenticate.

3. At the end of the day, the user runs:

        % cas-wrap -t tag grid-proxy-destroy

to destroy the CAS credential, and:

        % grid-proxy-destroy

to destroy the Globus proxy credential.Or the user might simply let both credentials expire.

Generating CAS credentials: cas-proxy-init

The syntax of the cas-proxy-init program is:

        cas-proxy-init [options] [ -t tag | -p proxyfile ]

This program contacts the CAS server, obtains a credential, and places that credential into a file. If "-p proxyfile" is used, then the credential is placed in the file named proxyfile; if "-t tag" is used, then cas-proxy-init chooses a filename based on the value of tag.

A environment variable, GLOBUS_LOCATION needs to be set to point to the GT3 install location. If CAS clients have been deployed, then this script is placed in GLOBUS_LOCATION/bin. This directory needs to be added to the PATH for it to be executed from other locations.

The other options that can be used with cas-proxy-init are:

    http://GT3Host:GT3Port/ogsa/services/base/cas/CASService
  

The cas-proxy-init program also consults environment variables to determine the appropriate URL to connect to and server identity to expect.The URL is determined using this algorithm:

• If the -c option was specified, use the URL specified with that option is used.
• Otherwise, if the CAS_SERVER_URL environment variable is set, use the value of that variable as the URL.

The server identity is determined in a similar fashion:

• If the -s option was specified, use the identity specified with that option
• Otherwise, if the CAS_SERVER_IDENTITY environment variable is set, use the value of that variable as the expected server identity.
• If neither is set, host authorization is done and the expected server credential is cas/, where is the fully qualified domain name of the host on which the CAS service is up.

Getting specific CAS rights

It is possible to request specific permissions from the CAS server using the -f option. This option causes cas-proxy-init to read a set of requested rights from a file.

This file should contain one or more resource identifiers:

        Resource: ResourceNamesapce|ResourceName 

For each resource, one or more actions identifers:

        serviceType action 

For example, if the client needed assertions for "file/read" service/action for resource "ftp://sample.org" and "ftp://sample3.org", both in "FTPNamespace" and "directory/read" and "directory/write" permissions on the former resource only, the policy file should have the following entries:

        Resource: FTPNamespace|ftp://sample1.org
        file read
        directory read
        directory write
        Resource: FTPNamespace|ftp://sample3.org
        file read

To indicate any resource, the following wildcard notation should be used.

uri:samlResourceWildcard

To indicate any action, the following wildcard notation for serviceType and action should be used. Note that this should be the first (and clearly the only action) in the list of action specified. All other actions in the list are ignored and if it is not the first, it is not treated as wildcard.

uri:samlActionNSWildcard uri:samlActionWildcard

For example, if the client needs assertions for all resources and all actions the policy file should look like.

       Resource: uri:samlResourceWildcard
       uri:samlActionNSWildcard uri:samlActionWildcard

If the client needs assertions for all actions on resource "FTPNamespace|ftp://sample1.org", the policy file should be as follows

       Resource: FTPNamespace|ftp://sample1.org
       uri:samlActionNSWildcard uri:samlActionWildcard

Using CAS credentials: cas-wrap

The cas-wrap program runs a grid-enabled program, causing it to use previously-generated CAS credentials.Its syntax is:

        cas-wrap [-t tag | -p proxyfile ] command args

Both versions of this command run:

        command args

in an environment in which command will use a previously-generated CAS credential.The first form should be used if cas-proxy-init was run with a tag argument; for example,

A environment variable, GLOBUS_LOCATION needs to be set to point to the GT3 install location. If CAS clients have been deployed, then this script is placed in GLOBUS_LOCATION/bin. This directory needs to be added to the PATH for it to be executed from other locations.

        % cas-wrap -t my-community gsincftp myhost.edu

will look for a credential generated by a previous execution of:

        % cas-proxy-init -t my-community

and then set the environment to use that credential while running the command

        % gsincftp myhost.edu

The second form should be used if cas-proxy-init was run with the –o option; for example,

        % cas-wrap –p /path/to/my/cas/credential gsincftp myhost.edu

will look for a credential generated by a previous execution of:

        % cas-proxy-init –o /path/to/my/cas/credential

and then set the environment to use that credential while running the command

        % gsincftp myhost.edu

Most grid-enabled programs (specifically, most programs written using the Globus GSI libraries) will honor the environment variable X509_USER_PROXY; if this variable is set, they will use its value as the name of a file containing the proxy credential to use when authenticating.A user could, for example, cause the gsincftp program to use CAS credentials by running these two commands:

        % setenv X509_USER_PROXY /path/to/my/cas/credential

The cas-wrap utility program works by running the specified command in an environment in which that variable is set.

CAS Service Data

• ServerDN: This is the DN of the credentials used by the CAS server.
• VODescription: This is a short description of the VO in which the CAS server is running.

There are scripts in the GT3 install to run get the values for the above said service data, ogsi-find-service-data in GLOBUS_LOCATION/bin. For more detailed instructions refer to the User's Guide in GT3.

An example run of the command line client to get the value of the service data value of the server DN is shown below. The query was run against a GT3 container running on localhost and port number 8080 from GLOBUS_LOCATION/bin.

C:\cygwin\home\Administrator\ogsa\impl\java\bin>ogsi-find-service-data-by-name.bat -gsiSecConv sig -auth self "http://ogsa.globus.org/base/cas:ServerDN"  http://localhost:8080/ogsa/services/base/cas/CASService

ServiceDataValues: 
 <ns2:serviceDataValues xmlns:ns2="http://www.gridforum.org/namespaces/2003/03/serviceData">
     <ns4:ServerDN xmlns:ns3="http://ogsa.globus.org/base/cas/casTypes" 
     xmlns:ns4="http://ogsa.globus.org/base/cas" 
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
     xsi:type="ns3:ServerDN">
      <ns3:serverDN>/O=Grid/O=Globus/OU=extreme.indiana.edu/CN=Rachana Ananthakrishnan</ns3:serverDN>
     </ns4:ServerDN>
    </ns2:serviceDataValues>

Writing CAS Clients

Listed below are some helper methods in the client package that maybe used for writing clients for the CAS service. Refer to code and/or Java Docs for more information.

• Getting handle to CAS service port type

  org.globus.ogsa.impl.base.cas.client.CasClientSetup is used.

  Code:

  • To get a handle to CAS service with instance URL, instanceURL and identity serviceIdentity,

     CasClientSetup clientSetup = new CasClientSetup();
     CommunityAuthorizationServicePortType casPort = 
    	    clientSetup.getCASPort(instanceURL, serverIdentity);
    

  • To get a handle to CAS service with instance URL, instanceURL and use host authorization,

     CasClientSetup clientSetup = new CasClientSetup();
     CommunityAuthorizationServicePortType casPort = 
    	    clientSetup.getCASPort(instanceURL);
    

• Generating proxy with CAS assertions embedded

  API in class org.globus.ogsa.impl.base.cas.client.CasProxyHelper can be used to generate a proxy with CAS assertions embedded. To pass in relevant parameters, class org.globus.ogsa.impl.base.cas.client.ClientParams is used. The datatype, org.globus.ogsa.impl.base.cas.client.ResourceActionsMap is used to represent the resource/actions mapping for which assertions are requested on.

  Listed below are steps to use the API. org.globus.ogsa.impl.base.cas.client.CasProxyInit has sample code that generates a proxy embedded with CAS assertions.

  Code:

  1. ClientParams class is used to construct the parameter. If the default constructor is used and none of the values are set, requested assertion lifetime is set to 24 hours, default proxy file is used, the proxy with assertions embedded is named with a ".cas" tag at the end of proxy file.

      ClientParams clientParams = new ClientParams();

  2. Sets assertion lifetime. If not set, 24 hours is used.

      clientParams.setAssertionLifetime(lifetime);
     

  3. Sets file name of the proxy to use. If not set, defualt credential is used..

      clientParams.setProxyFileName(proxyFilename);
     

  4. Sets file name of the proxy with CAS assertions to be written to. If not set, original proxy file name is appended with a tag.

      clientParams.setCasProxyFileName(casProxyFilename);
     

  5. Sets tag to append to original proxy filename. If not set, the tag "cas" is used. The tag is used if a filename for assertion embedded proxy is not set.

      clientParams.setCasProxyTag(tag);
     

  6. Sets the resource/actions for which assertion is requested on. It uses an array of data type ResourceActionsMap (explained below)

      clientParams.setResourceActionsMap(resActions);
     

  7. ResouceActionsMap datatype is used to represent the resource and the actions on the resource for which the permissions are required. It has a String to represent resource and a vector of string sto represent the actions.

     The resource should be of the form, "objectNamespace|objectName". The action should be of the form, "serviceType actionName"

  8. Instance of Helper class:

      CasProxyHelper casProxyHelper = new CasProxyHelper(instanceURL, serverIdentity);
     

     where,
     • instanceURL is the URL to contact CAS service.
       
     • serverIdentity is the expected identity of the server. If null, host authorization is used.
  9. Generating proxy with CAS assertions

      String casProxyFilename = casProxyHelper.getCasProxy(clientParams);
     

     This methods contacts the CAS service, retrieves assertions, embeds in credetial and returns the path to the proxy file with CAS proxy embedded.