Page Comparison

This page describes the following configurations.

...

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:

   Code Block
   <!-- BEGIN-AUTH comment the following

   and

   Code Block
   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

   Code Block

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

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

8. Start the Start the 'cspace' server.

Test

Test data

...

• Run the create_db ant target

  Code Block
  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

...

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

{multi-excerpt:name=generating a password hash}
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.

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

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

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

The content between the square brackets ('\[' and '\]') is the password hash.
{multi-excerpt}

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

...

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

{multi-excerpt:name=generating a password hash}
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.

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

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

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

The content between the square brackets ('\[' and '\]') is the password hash.
{multi-excerpt}

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*

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.

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.

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

...

...

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:

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/jboss-web-security-config.xml.