GT 4.2.0 CAS Admin Guide

The CAS service can be configured with the following :

By default, the CAS service is not loaded at start up. To change this behavior, uncomment the loadOnStartup property set in $GLOBUS_LOCATION/etc/globus_cas_service/server-config.wsdd as shown below.

Once the loadOnStartup property is uncommented, the following happens at start up:

<service name="CASService" provider="Handler" use="literal" 
      
      style="document">
      
      <!-- Uncomment if the service needs to be initialized at startup -->
      
      <parameter name="loadOnStartup" value="true"/>
      
      <parameter name="allowedMethodsClass" 
      
      value="org.globus.cas.CASPortType"/>
      
      .
      
      .
      
      .
      
      </service>

To change the VO description, set the parameter voDescription in $GLOBUS_LOCATION/etc/globus_cas_service/jndi-config.xml to the desired values.

To change the maximum assertion lifetime set the parameters maxAssertionLifetime in $GLOBUS_LOCATION/etc/globus_cas_service/jndi-config.xml to the desired values.

To alter the configuration of the database back end edit the databseConfiguration section of $GLOBUS_LOCATION/etc/globus_cas_service/jndi-config.xml as described below. If you are using the default Derby installation, the only parameter to change is the connectionURL to replace GLOBUS_LOCATION with the actual location of your toolkit installation.

By default, the following security configuration is installed:

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

	Note
	Changing required authentication and authorization methods will require matching 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.

CAS is used to administer access rights to files and directories and the GridFTP server can be configured to enforce those rights.

For detailed information about configuring CAS for use with a GridFTP server, see How to Set up CAS with GridFTP.

The CAS server can be used to admiminster rights for access to web services. The mapping from CAS objects to the web service resource is shown on this table:

An example scenario is described here.

With a default GT 4.0.1 installation, CAS is automatically registered with the default WS MDS Index Service running in the same container for monitoring and discovery purposes.

	Note
	If you are using GT 4.0.0, we strongly recommend upgrading to 4.0.1 to take advantage of this capability.

However, if must use GT 4.0.0, or if this registration was turned off and you want to turn it back on, this is how it is configured:

There is a jndi resource defined in $GLOBUS_LOCATION/etc/globus_cas_service/jndi-config.xml as follows :

 
    <resource name="mdsConfiguration" 
    
    type="org.globus.wsrf.impl.servicegroup.client.MDSConfiguration">
    <resourceParams>
    <parameter> 
    <name>reg</name>
    <value>true</value>
    </parameter>
    <parameter> 
    <name>factory</name>
    <value>org.globus.wsrf.jndi.BeanFactory</value>
    </parameter>
    </resourceParams>
    </resource>
  

To configure the automatic registration of CAS to the default WS MDS Index Service, change the value of the parameter <reg> as follows:

      <Content xsi:type="agg:AggregatorContent"
      xmlns:agg="http://mds.globus.org/aggregator/types">
      
      <agg:AggregatorConfig xsi:type="agg:AggregatorConfig">
      
      <agg:GetResourcePropertyPollType
      xmlns:cas="http://www.globus.org/07/2004/cas">
      <!-- Specifies that the index should refresh information
      every 8 hours (28800000ms) -->
      <agg:PollIntervalMillis>28800000</agg:PollIntervalMillis>
      
      <!-- specifies that all Resource Properties should be
      collected from the RFT factory -->
      
      <agg:ResourcePropertyName>cas:VoDescription</agg:ResourcePropertyName>
      
      </agg:GetResourcePropertyPollType>
      </agg:AggregatorConfig> 
      <agg:AggregatorData/>
      </Content>
    

If a third party needs to register an CAS service manually, see Registering with mds-servicegroup-add in the WS MDS Aggregator Framework documentation.

The CAS service can run with its own service specific credentials. Instructions for obtaining service credentials may be found here.

The standard administrator clients that come with the distribution by default use identity authorization to authorize the service they are running against (and expect that the CAS service has credentials that have the FQDN of the host the server is running on and the service name "cas" as part of DN). Command line options can be used to specify the identity of the CAS service, if the default identity is not used. The command in the above mentioned web page may be altered as follows to get credentials for the CAS server:

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 locations of certificate and key files are referred to as CAS_CERT_FILE and CAS_KEY_FILE, respectively. The subject name in these credentials is expected by CAS clients by default.

CAS uses a back end database to store all user data. This section briefly describes the installation of such a database and the creation of the database using the schema required by the CAS back end.

2.1. Installing the database

While any database with a JDBC driver and support for a reasonable set of SQL may be used, Derby has been used for development and testing. The driver for the same is included in the distribution. A default Derby database is created for CAS during installation and the CAS server uses the database in the embedded mode. One set of CAS tests also use the database in the embedded mode and another set uses in the network mode.

	Note
	Any JDBC compliant database might be used as backend. If a different database is used, the corresponding driver should be added to $GLOBUS_LOCATION/lib.

2.2. Creating the CAS database

By default a Derby database is created during deploy time at $GLOBUS_LOCATION/var. But schema for using PostGres or MySQL as backend is provided at $GLOBUS_LOCATION/etc/globus_cas_service/casDbSchema/cas_pgsql_database_schema.sql or $GLOBUS_LOCATION/etc/globus_cas_service/casDbSchema/cas_mysql_database_schema.sql. Please refer to PostGres or MySQL documentation for steps involved in creating the database.

	Note
	This documentation assumes the database name to be casDatabase

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

CAS has been tested to work without any additional setup when deployed into Tomcat. Please follow these basic instructions to deploy GT4 services into Tomcat. Note that the Java WS Core module needs to be built and configured as described in the previous sections.

CAS is used to administer access rights to files and directories and GridFTP server can be configured to enforce those rights. The following is an overview of the process:

In a default Globus Toolkit installation, CAS is installed with a set of credentials associated with the CAS server. A CAS administrator has all rights on the CAS server and manages users. To be used with GridFTP, the administrator needs to add users, add the files and directories he wants protected and grant specific rights to the files.

The user then retrieves a CAS assertion from the server, for either specific files/directories or all his access rights stored in CAS. This is done using the client side command, cas-proxy-init, which embeds the assertion in the user's proxy. Another client side command, cas-wrap can then be used to run the GridFTP command, globus-url-copy, to ensure that the proxy is used.

Details about the CA who issues these credentials needs to be added to the CAS server as a trust anchor. Each user has a nick name, a subject DN and is associated with a trust anchor. A particular user is designated as superuser, so has permissions to add users and manager rights. This can be set up using the bootstrap step.

Users who are not administrators can be added using admin command line tools. Permissions in a CAS database are granted to user groups, rather than users. So a user group needs to be created and users added to it prior to assigning permissions.

Files and directories are "objects" in CAS. Each object has a name and a namespace assocated with it. The namespace determines the scope of the object and also the comparison method to use with object names. A predefined namespace, called FTPDirectoryTree is loaded in the CAS database upon bootstrap and this is the namespace expected for GridFTP objects.

For example, if permission on file "some_file_path" on host "somehost.edu" needs to be managed, it needs to be added as an object, with name "ftp://somehost.edu/some_file_path" and namespace "FTPDirectoryTree". This object "ftp://somehost.edu/some_file_path" will be recognized by the CAS-enabled GridFTP server at "somehost.edu" as referring to the file named "some_file_path". An object in the FTPDirectoryTree namespace with the name "ftp://somehost.edu/some_directory_path/*" will be recognized by the CAS-enabled GridFTP server at "somehost.edu" as referring to all files and directories under "some_directory_path".

In some cases, it may be desirable to have a GridFTP server recognize CAS assertions that use a hostname other than the server's fully qualified domain name. Starting the GridFTP server with the option "-H otherhost" will cause the GridFTP server to recognize objects with names that start with "ftp://otherhost/" instead.

The actions that are allowed on a file and a directory are listed in the following table:

These actions are predefined and loaded onto CAS database when bootstrap is done. Apart from these actions on files/directories, there is another action "authz_assert" which is used to override the existing assertions (either from proxy or from a previous "authz_assert" command) with the assertions received over the GridFTP control channel. FTP clients can use the command "SITE AUTHZ_ASSERT" to send assertions to the GridFTP server.

The following is a summary of supported FTP commands and the permissions they require:

Once the CAS server has been configured (as above), if User1 wants to transfer the file "/tmp/file1" on "ftp://foo.bar.edu", User1 performs the following two steps:

The CAS administrator can create groups of users and groups of objects to ease policy management.

Also, if the administrator wants to provide a set of rights, such as read and lookup, the administrator can create a service action group with these action as members. User groups can then be provided with access to all actions in the group.

Similarly the administrator can create groups of objects, which would be a group of GridFTP server and files on it, and grant access rights to users.

The following describes how the GridFTP server processes a file transfer using CAS:

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

As with the previous any database backend can be used for testing. If the default Derby database is used, it needs to be configured in network mode since these tests require that both the tested CAS server and the tests use the database. Two files need to be modified for configuring these tests and they are described below.

Steps for testing:

	Important
	The database bootstrap needs to be done again for the server to be ready to receive client requests.

Since at the time of booting up the CAS server only the user group that has super user permissions on the CAS server is created, Alice will want to create another user group to which new users can be added and to which permissions on newly enrolled CAS entities may be given. This also eases the process of giving the same rights to many users. Given that there 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. For example, Alice may want 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 scientists.

Prior to adding Bob and Carol to the CAS server, Alice needs to ensure that the trust anchors for both have been added. If they share the 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 the 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"

The above will enroll a trust anchor with nickname AbcTrust that uses X509 as its authentication method and has the DN specified in the command. The members of the analysts user group are given all rights on this object. This implies that any user who has this trust anchor is assumed to present credentials signed by this trust anchor.

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 the user group suUser to be able to manipulate the user entity Bob.

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

Alice uses a similar command to add Carol to the CAS database.

The 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 the 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 the nickname 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.

Alice now has the community users in the database. The next step is to add some resources. Because the community currently has the FTP server foo.bar.edu available to it she will add it to the CAS database.

Each resource or object in the CAS server has a namespace associated with it that defines certain features. For example, it can define the comparison algorithm that is to be used when the object's name is compared. 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 startup. 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

This command adds the FTP server as an object and gives all members of the suGroup rights to manipulate the object.

To be able to grant/revoke access on an individual directory, add an object for the directory. For example, if Alice would like to be able to manipulate the data directory 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

Alice suspects that the community will end up with more directories containing data on other servers that will have polices identical with the ones on the /data directory on foo.bar.edu. To manage this 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

This creates an object group called data and the members of suGroup get all rights on this group and hence should be able to add/remove members, grant rights to add/delete from this group to others and also delete this 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 object, ftp://foo.bar.edu/data/* in the namespace FooFTPNamespace, to the 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:

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 the 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

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 the add option. The following command adds a mapping of action read to service type file.

alice% cas-action add file add

Similarly, she can add other mappings, like write, to this service type.

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 the 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

She similarly grants rights to scientists group.

This section describes using the CAS server as an authorization service to manage policy for web services. The sample service used here is the Counter Service distributed as a part of Java WS Core component. The CAS server needs to be bootstrapped with information about a super user and the sample assumes that the super user is the client. The methods on Counter Service that need to be protected need to be added as actions and the EPR of the created counter resource needs to be added as an object.

This section describes using the CAS server as a PDP local to the container to manage authorization policy for web services. Unlike the previous section the authorization service interface of CAS is not used. But a PDP, org.globus.cas.impl.LocalCasPdP, distributed with the CAS server code base is used to contact a co-hosted CAS server for authorization decisions. This PDP uses Java calls on the CAS resource to obtain policy information and returns a decision of PERMIT or DENY.

For a service to use this feature, the authorization configuration at service/resoruce level should be the LocalCasPdp. To grant access to users, the users need to be added to the CAS database. This can be done either during bootstrap or during runtime. The resource owner can then facilitate fine grained, per operation authorization by storing appropriate permissions on the local CAS server.

Following is a list of steps that highlights how the CasLocalPdp can be sued:

The following information applies to Java WS Core and all services built on Java WS Core.

Java WS Core server side has two types of loggers. One logger is used for development logging and by default writes to standard out. The other logger includes system administration information and is CEDPs best practices compliant.

On client side, only developer logging is available and is configured using log4j.properties.

   #for debug level logging from org.globus.package.FooClass 
   log4j.category.org.globus.package.name.FooClass=DEBUG
   #for warnings from org.some.warn.package
   log4j.category.org.some.warn.package=WARN
   

log4j.appender.infoCategory=org.apache.log4j.RollingFileAppender
   log4j.appender.infoCategory.Threshold=INFO
   log4j.appender.infoCategory.File=var/containerLog
   log4j.appender.infoCategory.MaxFileSize=10MB
   log4j.appender.infoCategory.MaxBackupIndex=2