Authentication Service Configuration Guide

This page describes the following configurations.

CollectionSpace Identity Provider (CS IdP)
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)

Unknown macro: {multi-excerpt-include}

If the $JBOSS_HOME/server/cspace/conf/login-config.xml file does not exist, please review each of the steps in CollectionSpace Identity Provider (CS IdP) to make sure the CS IdP has been set up and configured properly. Then return to this document and begin with the next step, below.

Enable authentication for CollectionSpace web services

With release 0.5 (inclusion of Spring Security), the following change in the web.xml is no more needed. That means skip steps #2-6

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:

If the 'cspace' server is running in JBoss, quit that server.
If you haven't already done so, download the source code for the CollectionSpace Services Layer.
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).
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).
Delete these two comment lines in that file:
```
 
```
and
```
 
```
By deleting those two comment lines, this will enable the <security-constraint> and <login-config> sections of that file.
Rebuild the Services Layer WAR file (cspace-services.war):
```
 
```
Deploy the newly-edited WAR file to the 'cspace' server in JBoss:
```
 
```
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
```
 
```
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:

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:

Generate a "hash" of the new test user's password.
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.
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

Unknown macro: {multi-excerpt}

Rather than storing passwords in clear text in the CollectionSpace account and authentication services infrastructure, passwords are "hashed" and the hash values are stored instead. Essentially, an algorithm is run on the password that creates a fixed-length value, or "hash," which acts like a "digital fingerprint" of the password. It is the hash, rather than the password itself, that is stored. Incoming passwords are compared against the hash to identify whether the correct password is being entered.

The hash algorithm, in the default configuration of the CollectionSpace Identity Provider (CS IdP), is SHA-256 and the hash is Base64-encoded.

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

Assuming that you're still using these default settings for the hash algorithm and encoding, you could generate the hash for a new user's password as follows. (Be sure to change the word 'test' in the command below to the actual password for which you want to generate a hash.)

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

The content between the square brackets ('[' and ']') is the password hash.

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.)

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:

Successful test

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

Required system properties*

cspace.auth** to true, indicates to use HTTP authentication. We will use BASIC authentication in these tests.
cspace.user indicates user name to use
cspace.password indicates password to use (clear text ... this is only a test)
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.

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

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.

Failure test: invalid user or password

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:

With release 0.5 (inclusion of Spring Security), the following change in the web.xml is no more needed.

web.xml

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.

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