CAS: User's Guide

Contents:

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:

1. In the morning, the user runs: 

        % 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:

-c url

Contact URL for the CAS server. This typically looks like, 

    http://GT3Host:GT3Port/ogsa/services/base/cas/CASService
where GT3Host and GT3Port are host and port where container with CAS service is running.

-s server_identity

When doing mutual authentication with the CAS server, expect server_identity as the remote identity.

-f policy_file

Generate a CAS credential that includes only those permissions specified in file policy_file (the default is to generate a credential with all the user’s permissions).

-l hours

Generate a credential that will time out after hours hours. This is a request for lifetime, but the CAS server may have a set maximum for the assertion lifetime which will be enforced.

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:

The server identity is determined in a similar fashion:

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

The CAS service exposes two strings as service data and is within the following namesapce http://ogsa.globus.org/base/cas. These are constants that are set at the service start up and cannot be modified.

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.

Updated: 01 - 30 - 2004