GT 3.9.5 CAS: System Administrator's Guide

• Introduction
• Building and Installing
• Configuring
• Deploying
• Testing
• Example of CAS Server Administration
• Security Considerations
• Troubleshooting

Introduction

This guide contains advanced configuration information for system administrators working with the Community Authorization Service (CAS). It provides references to information on procedures typically performed by system administrators, including installation, configuring, deploying, and testing the installation.

This information is in addition to the basic installation instructions in the GT 3.9.5 System Administrator's Guide.

Note: This document contains information about deploying a CAS server and is not needed for a CAS client installation. [expand on this a little more]

Building and Installing

Configuring

Configuration overview

The CAS service can be configured with a description of the VO the CAS service serves and the maximum lifetime of the assertion it can issue. Also, the service needs to be configured with information about the backend database it uses. Any JDBC compliant database can be used, PostGres was used for development and testing. The database needs to be set up such that it can receive requests over TCP/IP. The CAS database schema to be used with PoseGres has been provided in $GLOBUS_LOCATION/etc/globus_cas_utils/casDbSchema/cas_pgsql_database_schema.sql.

Other than that, the security configuration of the service can be 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 security configuration is installed:

• Credentials set for use by container is used. If that is not specified, default credentials are used.
• GSI Secure conversation authentication is enforced for all meethods
• The security framework is not used for authorization, but the the service uses the backend database to determine if the call is permitted.

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

Syntax of the interface

• To change the maximum assertion lifetime and VO description, set the parameters maxAssertionLifetime and voDescription in $GLOBUS_LOCATION/globus_cas_service/jndi-config.xml to required values.
• To alter the configuration of database backend, edit databseConfiguration section of $GLOBUS_LOCATION/globus_cas_service/jndi-config.xml as follows:

  driver	The JDBC driver to be used
  connectionURL	JDBC connection url to be used to connect to database
  userName	user name to connect to database as
  password	database password for the said username
  activeConnections	Maximum number of active connections at any given instance
  onExhaustAction	Action to perform when pool is exhausted. If value is, 0 - fail, 1 - block, 2 - grow (get more connections)
  maxWait	Maximum time in milliseconds pool will wait for a connection to be returned
  idleConnections	Maximum number of idle connections at any given instance

• To alter security descriptor configuration refer to Security Descriptors. The file to be altered is $GLOBUS_LOCATION/globus_cas_service/security-config.xml

Deploying

CAS service can be deployed as a part of the toolkit installtion. Please refer to System Administrator's Guide for details. Other than steps described in the above guide, the following are needed to deploy the CAS service.

• Obtaining credentials for the CAS server
• Database installation and configuration

Obtaining credentials for the CAS server

The CAS service could run with its own set of credentials. Instructions to obtain service credentials may be found here.

The standard administrator clients that come with the distribution can be used to perform host authorization and expect that the CAS service have credentials that have service name "cas". The command in the above mentioned web page may be altered as follows:

  casadmin$ grid-cert-request -service cas -host FQDN

The certificate and private key are typically placed in /etc/grid-security/cas-cert.pem and /etc/grid-security/cas-key.pem, respectively. In this document, the location of certificate and key files is referred to as CAS_CERT_FILE and CAS_KEY_FILE, respectively.

Database installation and configuration

Installing the database

Brief instructions to install a JDBC compliant database and specifically PostGres can be found here. For more detailed instructions, please refer to specific database documentation.

Creating CAS database

The schema of the database that needs to be created for CAS can be found at $GLOBUS_LOCATION/globus_cas_service/casDbSchema/cas_pgsql_database_schema.sql

To create a database, for example casDatabase, on a PostgreSQL, install on local machine:

casadmin$ createdb casDatabase  
casadmin$ psql -U casadmin -d casDatabase -f  \
          $GLOBUS_LOCATION/globus_cas_service/casDbSchema/cas_pgsql_database_schema.sql

You will see a list of notices on the screen. Unless any of them say "ERROR", these are just output for information.

Information about the database needs to be configured as described here for the CAS service to be able to use it.

Bootstrap the CAS database

The CAS database needs to be initialized with data implicit to CAS and information about a super user to bootstrap CAS operations. The command line script cas-server-bootstrap can be used to do the same.

     cas-server-bootstrap [<options>] -d <dbPropFile> [ -implicit | -b <bootstrapFile> ]

    dbDriver=database driver name
    dbConnectionURL=database connection URL
    dbUserName=Username to access database
    dbPassword=Password for the above username
  

To bootstrap the CAS datbase with both implicit and user data the following command can be used. Prior to running that, the following files need to be created with appropriate values filled in.

• $GLOBUS_LOCATION/share/globus_cas_service/casDbProperties

       dbDriver=org.postgresql.Driver
       dbConnectionURL=jdbc:postgresql://127.0.0.1/casDatabase
       dbUsername=tester
       dbPassword=foobar

• $GLOBUS_LOCATION/share/globus_cas_service/bootstrapProperties

       ta-name=defaultTrustAnchor
       ta-authMethod=X509
       ta-authData=/C=US/O=Globus/CN=Default CA
       user-name=superUser
       user-subject=/O=Grid/O=Globus/OU=something/CN=someone
       userGroupname=superUserGroup

• Command to run

  $GLOBUS_LOCATION/bin/cas-server-bootstrap -d $GLOBUS_LOCATION/share/globus_cas_service/casDbProperties -implicit -b $GLOBUS_LOCATION/share/globus_cas_service/bootstrapProperties

Testing

CAS has two sets of tests, one for the backend database access module and another set to test the service itself. To install both tests, install the CAS test package (gt4-cas-delegation-test-3.9-src_bundle.tar.gz) using GPT FILLME: instructions into GLOBUS_LOCATION.

It is assumed that:

• a backend database has been set up and configured
• CAS service and tests are installed in $GLOBUS_LOCATION
• the service is running on localhost and port 8080 (for the sample commands)
• the database is set up with:
  1. username as tester
  2. database name as casDatabase
  3. host as foo.bar.gov and default port.

Testing the backend database module

1. Run:

    cd $GLOBUS_LOCATION 

2. Populate the file etc/globus_cas_unit_test/casTestProperties with the following database configuration information:
   
   

   dbDriver	The JDBC driver to be used
   dbConnectionURL	JDBC connection url to be used to connect to database
   dbUsername	user name to connect to database as
   dbPassword	database password for the said username

   
   
3. The database needs to be empty for these tests to work. To delete all the data in the database, run:

   psql -d casDatabase -U tester -h foo.bar.gov -f etc/globus_cas_utils/database_delete.sql 

4. Run:

   ant -f share/globus_cas_unit_test/cas-test-build.xml testDatabase 

5. Test reports are placed in $GLOBUS_LOCATION/share/globus_cas_unit_test/cas-test-reports.

Testing CAS service module

These tests can be set up so as to be able to test multiple user scenario or it can be configured to run just as a single identity. The first set of tests are used to test admin functionality and sets up the database for second user. As the second user the permissions and queries are tested to ensure that the set up worked.

All the configuraiton information for the test, needs to be configured in etc/globus_cas_unit_test/casTestProperties file. The database section of the properties file needs to be configured as described here. Other than those, the following properties also need to be configured for these tests:

Steps for testing:

1. Run:

    cd $GLOBUS_LOCATION                

2. The database needs to be empty for these tests to work. To delete all the data in the database, run:

   psql -d casDatabase -U tester -h foo.bar.gov -f etc/globus_cas_utils/database_delete.sql 

3. In the test properties file, set user2SubjectDN to be the subject in your regular proxy. The following returns the appropriate string:

   casadmin$ bin\grid-cert-info -subject -globus

4. Generate an independent proxy using the following command:

   casadmin$ bin\grid-proxy-init -independent

5. Set the identity in the proxy generated from the above step as user1SubjectDN in the test properties file. The following command will return the relevant string:

   casadmin$ java org.globus.tools.ProxyInfo -subject -globus

6. Start a container on port (for example, testPort) and host (for example, hostPort).
7. The following command runs tests for self permissions and sets up the database for user with subjectDN that is user2SubjectDN:

   casadmin$ ant -f share/globus_cas_unit_test/cas-test-build.xml -Dtest.port=testPort \
               -Dtest.host=testHost user1TestService

8. To test as the second user, generate proxy for the subject DN specified for the second user:

   casadmin$ bin/grid-proxy-init 

9. To test as second user, run the following:

   casadmin$ ant -f share/globus_cas_unit_test/cas-test-build.xml -Dtest.port=testPort \
               -Dtest.host=testHost user2TestService

10. Test reports are placed in $GLOBUS_LOCATION/share/globus_cas_unit_test/cas-test-reports.
11. After these tests, the CAS database needs to be reset. The following command will delete all entries from the database:

     casadmin$ psql -U casadmin -d casDatabase -f GLOBUS_LOCATION/share/cas/database_delete.sql

Example of CAS Server Administration

Alice, Bob and Carol are three members of a community who have set up a Community Authorization service:

• Alice's role is primarily to administer the CAS server.
• Bob is an analyst who needs read access to much of the community data.
• Carol is a scientist who needs to be able to both read and write community data.

These examples show how:

1. Alice adds the users Bob and Carol to the CAS server
2. Adds a FTP server with some data available to the community
3. Adds permissions for the users using the CAS administration clients.

These examples assume the following:

• Alice has installed the CAS server and bootstrapped the database with herself as super user. Please refer to installation documentation for details.
• Alice's nickname on the CAS server is alice and at bootstrap she has created a user group, suGroup,which has super user permissions on the database.
• The CAS service URL is http://localhost:8080/ogsa/services/base/cas/CASService.
• For all commands listed below, the enviroment variable, GLOBUS_LOCATION, has been set to point to the GT core install and the commands are run from GLOBUS_LOCATION/bin.
• An environment variable, CAS_SERVER_URL, has been set to point to the CAS server URL, http://localhost:8080/ogsa/services/base/cas/CASService.

1. Adding a user group

Since at the time of booting up the CAS server, only one user group that has super user permissions on the CAS server is created, Alice might want to create another user group to which new users maybe added and permissions to newly enrolled CAS entities may be given. This also eases the process of giving same rights to many users.Given they are two types of roles in the community she might want to create two groups, analysts and scientists.

Also, all permissions on the newly created group will be given to users of a particular user group. Say, Alice would like all users of the user group analysts to be able to manipulate the group.

To create a new user group Alice uses the cas-group-admin client.It requires a name for the new group being created, say analysts.

alice%  cas-group-admin user create analysts analysts

This will create a user group analysts and give all users in that group the permission to manage the group (i.e add users, remove users and so on). She can similarly create a group called scientist

2. Adding a trust anchor

Prior to adding Bob and Carol to CAS server, Alice needs to ensure that the trust anchors for both have been added. If they share the same trust anchor with Alice then this step can be skipped, since at bootstrap Alice's trust anchor would have been added to the database.

In our example, Alice and Carol share a trust anchor different from Bob's. Therefore, Alice needs to add Bob's trust anchor by using cas-enroll client with the trustAnchor option. She needs to provide details about the trust anchor such as the authentication method and authentication data used.

alice%  cas-enroll trustAnchor analysts AbcTrust X509 "/C=US/O=some/CN=ABC CA"

3. Adding users

Now, Alice can add Bob and Carol as users using the cas-enroll command with the user option. She needs to provide the user's subject DN and a reference to the trust anchor used by the user. As with any entity added to the CAS server, the admin needs to choose a user group whose members will have all permissions on that entity. In this example, Alice would like the members of user group suUser to be able to maninipulate the user entity Bob.

alice% cas-enroll user suUser bob "/O=Our Community/CN=Bob Foo" AbcTrust

4. Adding users to a user group

CAS server allows rights to be assigned only to user groups and not to individual users. Hence before Alice can assign rights to Bob or Carol, she needs to add them to some user group. She does this by using cas-group-add-entry client with the user option to indicate she is adding to a user group. This client requires the group name and nick name of the user who needs to be added. To add Bob to the analysts group, the command would be:

alice% cas-group-add-entry user analysts bob

If a user group scientists was created, Carol could similarly be added as a member.

4. Adding a new FTP server

Alice now has the community users in the database and organized. She now wants to add some resources. Because the community currently has a single FTP server, foo.bar.edu, available to it, she will add this to the CAS database.

Each resource or object in the CAS server has a namespace associated to it that defines certain features. For example, it can define the comparison algorithm that needs to be used when this object name is used for comparison. It may also define the base URL that should be prefixed to objects that belong to this namespace. In this case, Alice chooses to use the FTPDirectoryTree namespace that is added to the CAS server at bootup. She uses the cas-enroll client with the object option to add the FTP server to the CAS database:

alice% cas-enroll object suGroup ftp://foo.bar.edu/* FTPDirectoryTree

To be able to grant/revoke access on an indiviual directory, add an object for the directory. For example, if Alice would like to be able to manipulate the data on the server as a separate entity, the following command will add an object for that.

alice% cas-enroll object suGroup ftp://foo.bar.edu/data/* FTPDirectoryTree

4. Creating an object group

Alice suspects the community will end up with more directories containing data on other servers that will have identical polices as the /data directory on foo.bar.edu. So she is going to create an object group called data and assign foo.bar.edu/data to this group. This will allow her to grant rights on this group and easily add other directories to this group later.

To create a group called data, she uses the cas-group-admin client with the group and create options:

alice% cas-group-admin object create suGroup data

5. Adding members to an object group

Alice now can add foo.bar.edu/data to the data group. She can do this by using the cas-group-add-entry with the object option. To add the above described object, ftp://foo.bar.edu/data/* in namespace FooFTPNamespace, to object group data, Alice uses the following command:

alice% cas-group-add-entry object data object FooFTPNamespace ftp://foo.bar.edu/data/*

In the above command:

• the first object refers to the group type.
• data is the name of the object group.
• the second object refers to the type of CAS entity that is being added as a member.
• the last two parameters define the namespace and the object that needs to be added.

6. Adding service types

Alice now needs to add information about the kinds of rights that can be granted for these objects. These are stored as service types and relevant actions are mapped to these service types.

In this scenario, the kind of service types that Alice should add would be file, directory and so on. To do so, the cas-enroll client with serviceType option may be used. To add a service type called file and give members of suGroup all rights on this service type, Alice uses the following command.

alice% cas-enroll serviceType suGroup file

7. Adding action mappings

The relevant action mappings to the above mentioned service types would be read, write and so on. Alice needs to add these mappings to the database so that she can grant rights that allow a user to have file/read or file/write permissions on some object.

To add action mappings to a service type, she uses the cas-action client with add option. The following command should add a mapping of action read to service type file.

alice% cas-action add file add

8. Granting permissions

Alice now has resources in the object group data and users in the user groups analysts and scientists. She now wants to grant permissions on data group to the analysts and scientists, namely read permissions to the analysts and read and write permissions to the scientists.

To grant permissions, Alice needs to use the cas-rights-admin with the grant option. To give read permissions to the analysts group, Alice runs:

alice% cas-rights-admin grant analysts objectGroup data serviceAction file read

Security Considerations

[describe security considerations relevant for this component]

Troubleshooting

[help for common problems sysadmins may experience]