Authentication Service Configuration Guide

This page describes the following configurations.

1. CollectionSpace Identity Provider (CS IdP)
2. Configuration of CollectionSpace service layer for authentication

We assume that JBoss is used as an application server for deploying the CollectionSpace services.

Set up and configure the CollectionSpace Identity Provider (CS IdP)

Enable authentication for CollectionSpace web services

To enable authentication for CollectionSpace web services, the J2EE web-app deployment descriptor (web.xml) and JBoss's web-app description (jboss-web.xml) - in the WEB-INF directory, within the cspace-services.war file that is deployed to $JBOSS_HOME/server/cspace/deploy - need to be configured as described below.

The jboss-web.xml file is already correctly configured to enable authentication. However, you'll need to make a couple of editing changes to the web.xml file, and then deploy the edited copy of that file to the 'cspace' server.

To do this:

1. If the 'cspace' server is running in JBoss, quit that server.
2. If you haven't already done so, download the source code for the CollectionSpace Services Layer.
3. Change to the JaxRsServiceProvider module of the Services Layer source code tree (relative path, if you've downloaded via the linked instructions: services/JaxRsServiceProvider; full path from the root of the entire CollectionSpace project's source code: /src/services/trunk/services/JaxRsServiceProvider).
4. Edit the web.xml file within that module (relative path: src/main/webapp/WEB-INF/web.xml; full path: /src/services/trunk/services/JaxRsServiceProvider/src/main/webapp/WEB-INF/web.xml).
5. Delete these two comment lines in that file:

   <!-- BEGIN-AUTH comment the following
   

   and

   END AUTH -->
   

   By deleting those two comment lines, this will enable the <security-constraint> and <login-config> sections of that file.
6. Rebuild the Services Layer WAR file (cspace-services.war):

   /src/services/trunk/services/JaxRsServiceProvider> mvn clean install -DskipTests
   

7. Deploy the newly-edited WAR file to the 'cspace' server in JBoss:

   /src/services/trunk/services/JaxRsServiceProvider> ant deploy
   

8. Start the 'cspace' server.

Test

Test data

You will also need to seed the security realm of the CS IdP with users, roles, and password(s), in order to run your tests.

To help you get started, you can begin your testing with some sample data - with two users and roles, and a single password - by running a SQL script via either of the following methods:

• Run the create_db ant target

  cd /src/services/trunk/services/authentication/
  ant create_db
  

  This will run a script to set up the users, roles, and users_roles tables, /src/services/trunk/services/authentication/pstore/src/main/resources/db/mysql/authentication.sql, and then execute a second SQL script, mentioned below, to insert test data into those tables.
  
  or
  
  
• If you've already created the users, roles, and users_roles tables, just execute the SQL script that inserts test data into those tables: /src/services/trunk/services/authentication/pstore/src/main/resources/db/mysql/test_authentication.sql

This SQL script contains the following SQL INSERTs:

insert into `users` (`username`,`passwd`, `created_at`) VALUES ('test','n4bQgYhMfWWaL+qgxVrQFaO/TxsrC4Is0V1sFbDwCgg=', '2010-02-17 16:31:48');

insert into `roles` (`rolename`, `rolegroup`, `created_at`) values ('kernel', 'kernel', '2010-02-17 16:31:48');
insert into `roles` (`rolename`, `rolegroup`, `created_at`) values ('collections_manager', 'collections', '2010-02-17 16:31:48');
insert into `roles` (`rolename`, `rolegroup`, `created_at`) values ('collections_registrar', 'collections', '2010-02-17 16:31:48');

insert into `users_roles`(`username`, `rolename`, `created_at`) values ('test', 'collections_manager', '2010-02-17 16:31:48');
insert into `users_roles`(`username`, `rolename`, `created_at`) values('admin', 'collections_registrar', '2010-02-17 16:31:48');

Creating new test users and generating their hashed passwords

The SQL script mentioned above, /src/services/trunk/services/authentication/pstore/src/main/resources/db/mysql/test_authentication.sql, will create a single test user named 'test', with the hashed password 'test', into the database.

Here's how to generate your own test users. For each new user, you will:

1. Generate a "hash" of the new test user's password.
2. Add an 'insert' command to that SQL script, to add the new test user. This command will include the user's username, their password hash, and their tenant ID.
3. Add one or more 'insert' command(s) to that SQL script, to associate the new test user with one or more roles.

Generating a password hash

<module-option name="hashAlgorithm">SHA-256</module-option>
<!-- default is base64 encoding -->
<module-option name="hashEncoding">base64</module-option>

java -cp $JBOSS_HOME/server/cspace/lib/jbosssx.jar org.jboss.security.Base64Encoder test SHA-256
[n4bQgYhMfWWaL+qgxVrQFaO/TxsrC4Is0V1sFbDwCgg=]

Adding a new test user

After generating a hash for the new test user's password, you can then add an 'insert' command to the SQL script which loads test users, /src/services/trunk/services/authentication/pstore/src/main/resources/db/mysql/test_authentication.sql, to add your own new test user. (Be sure to replace the sample values below, which follow the word VALUES, with your actual values for your new test user's username; their password hash - that is, the content generated by the previous command, above, between the square brackets; and their tenant ID.)

INSERT INTO `users` (`username`,`passwd`, `tenantid`) VALUES ('test','n4bQgYhMfWWaL+qgxVrQFaO/TxsrC4Is0V1sFbDwCgg=', '1');

You can find more information about using this utility in section "Using Password Hashing" at Security Configuration.

Associating the new test user with roles

In addition to adding an 'insert' command to the SQL script which loads test users, the /src/services/trunk/services/authentication/pstore/src/main/resources/db/mysql/test_authentication.sql, you will then need to insert one or more additional commands into that script to associate your new test user with one or more roles.

Please see that script for examples of commands that insert new records into the 'users_roles' table, and follow those examples.

Start server and deploy a service

Start the server by following instructions from Deploying the CollectionSpace Service Layer. You may have to start both the servers if you are using CollectionObject service for testing purposes.

Run a test client

You could use any CollectionSpace service Java client to test authentication or you could use browser based client as well. Here we are using CollectionObject client for authentication. You could run this client without authentication as follows:

cd /src/services/trunk/services/security/client
mvn test

Successful test

To run a test using Java client library of CollectionSpace services, following system properties are required as shown below.

Required system properties*

1. cspace.auth** to true, indicates to use HTTP authentication. We will use BASIC authentication in these tests.
2. cspace.user indicates user name to use
3. cspace.password indicates password to use (clear text ... this is only a test)
4. cspace.server.secure*** true, indicates that services layer is enabled for security. (To run tests with security disabled, either omit this property or explicitly set its value to false.)

*With r1416, all tests are enabled to use authentication by default. Use these properties to apply non-default values.
**With r1416, anonymous access is disabled on the service layer. This property is set to true by default.
***With release 0.5 (inclusion of Spring Security), the cspace.server.secure property is no more needed.

For example, you could run a test with these properties as follows.

mvn -Dcspace.server.secure=true -Dcspace.auth=true -Dcspace.user=test -Dcspace.password=test test

Note: There is an issue with certain versions of the Maven Surefire plugin that prevents system properties entered on the command line from being used in tests. To workaround that issue, with Maven 2.1 and later, you can add -DforkMode=never to your mvn test commands; e.g.:

mvn -Dcspace.auth=true -Dcspace.user=test -Dcspace.password=test -Dcspace.server.secure=true -DforkMode=never test

You should see bunch of messages printed on your command prompt with successful test result.

Failure test: no credentials

If you don't provide any credentials from test client but the service layer is configured for authentication, you may see an error as follows.

2009-06-30 11:30:32,108 [main] INFO org.apache.commons.httpclient.HttpMethodDirector - No credentials available for BASIC 'org.collectionspace.services realm'@localhost:8180

Failure test: invalid user or password

2009-06-30 11:39:46,683 [main] INFO org.apache.commons.httpclient.HttpMethodDirector - Failure authenticating with BASIC 'org.collectionspace.services realm'@localhost:8180

Configurations to enable authentication

To enable authentication for CollectionSpace web services, the J2EE web-app deployment descriptor (web.xml) and JBoss's web-app description (jboss-web.xml) - in the WEB-INF directory, within the cspace-services.war file that is deployed to $JBOSS_HOME/server/cspace/deploy - need to be configured as follows:

web.xml

    <security-constraint>
        <web-resource-collection>
            <web-resource-name>CollectionSpace Services</web-resource-name>
            <url-pattern>/*</url-pattern>
        </web-resource-collection>
        <auth-constraint>
            <role-name>*</role-name>
        </auth-constraint>

        <user-data-constraint>
            <transport-guarantee>NONE</transport-guarantee>
        </user-data-constraint>
    </security-constraint>

    <login-config>
        <auth-method>BASIC</auth-method>
        <realm-name>CollectionSpace realm</realm-name>
    </login-config>

The above security-constraint indicates (with url-pattern) that access to any resource deployed by the web-app requires authentication. The auth-constraint with wild card value for role-name indicates to the servlet container to basically ignore J2EE-based authorization. The user-data-constraint with transport-guarantee of NONE indicates no SSL is required (Note in production environment this would not be the case). The auth-method of BASIC indicates HTTP BASIC authentication is used.

You may find a copy of this in /src/services/trunk/services/authentication/src/main/resources/config/web-security-config.xml.

jboss-web.xml

The JBoss servlet container needs to be instructed to use a particular security domain while authenticating users accessing a web application. For this, add the cspace security domain to the JBoss web application descriptor (jboss-web.xml) file of the CollectionSpace service web app as follows. Note that the name of the security domain should match the name of the application policy.

<security-domain>java:/jaas/cspace</security-domain>

You may find a copy of this in /src/services/trunk/services/authentication/src/main/resources/config/jboss-web-security-config.xml.