Skip to end of metadata
Go to start of metadata

CollectionSpace has an out-of-the-box easy to use identity provider. This is the default identity provider of CollectionSpace. This identity provider is also tenant-aware (release 0.4). That means the realm managed by it is partitioned per tenant. This provider would be consulted in addition to any other 3rd party identity providers while verifying identities of the users.

The CS IdP is implemented as JAAS LoginModule. The implementation is derived from JBoss's DatabaseServerLoginModule. You can find source code at CSpaceDBLoginModule


This document is linked from the Authentication Service Configuration Guide. If you are seeking to set up authentication in your CollectionSpace system, please start with that document. (You may potentially be referred back to this document to complete some parts of the process.)

Tenant-aware security context

Once the authentication is successful, the security context should contain tenant-qualified information about the authenticated principal. The CollectionSpace Authorization Service should make sure that the context is tenant-qualified post authentication.

Java Subject - some background

In Java, the security context could be in the form of a Subject if JAAS framework is used for authentication. A subject may be any entity, such as a person or a service. Once the subject is authenticated, a Java Subject is populated with associated identities, or principals. A Java Principal could represent any entity, such as an individual, a corporation, and a login id. A Subject may also own credentials. Sensitive credentials that require special protection, such as private cryptographic keys, are stored within a private credential Set. Credentials intended to be shared, such as public key certificates, are stored within a public credential Set. Access to credentials is provided based on permissions.

Security context in the form of a Subject is made available by the Java Application Server to application (mostly, attached to the thread context) once the authentication completes.

CollectionSpace Tenant Group

The CollectionSpace security runtime could further populate the Subject with tenant-specific information post successful authentication. This information could be in the form of a special group called "Tenants". Each member of this group would represent a tenant to whose resources the user principal would have access to. This context could then be used for the following purposes.

  1. Retrieve tenant-specific bindings in order to process the service request
  2. Enforce access control policies/permissions (using roles implemented as groups)


  1. It is assumed that at the time of provisioning a tenant, a user with privileges to administer the accounts for that tenant is added into the system.
  2. It is also assumed that the above mentioned user is added off-band without using the Account Service

Following sections describe how to configure this provider in JBoss 4.2.3 GA.

Build and deploy CS IdP

Shutdown the JBoss server if it is running. Execute the following commands from prompt. It is assumed that you have executed ant deploy at the trunk level as follows.

Error rendering macro 'code': Invalid value specified for parameter 'lang'
cd src/services/trunk/
ant deploy

With this command, the datasource configuration is copied to $JBOSS_HOME/server/cspace/deploy/cspace-ds.xml among other things including CS IdP binaries.

Configure JDBC datasource

The CS IdP uses database to persist the security realm it manages. It uses JDBC to access the database. Following is a snippet of the configuration of the JDBC datasource.


Since 0.4, the CS IdP is able to use datasource to get connection to the database. See CSPACE-259 for resolution.

You may find latest version of this in /src/services/trunk/services/src/main/resources/config/cspace-ds.xml.

Configure JAAS Login Module for CS IdP

Configuration of JAAS Login Module involves two steps:

  1. Create necessary tables in database
  2. Configure JBoss's login configuration to add an application policy using the login module

Create tables (MySQL)

The preferred way to create tables is to use ant task create_db. This task not only creates necessary tables, it also populates them with test data.

Error rendering macro 'code': Invalid value specified for parameter 'lang'
cd src/services/trunk/services/authentication
ant create_db

Note: You may want to set required environment variables (DB_USER, DB_PASSWORD) before running create_db. See Services Build for more details.

Alternately, you could use the following sql script to create necessary tables. Use the following script to create tables in MySQL database named cspace. Here, we create 3 tables.

  1. Table users: stores user names, (encrypted) passwords
  2. Table roles: stores role names, role group
  3. Table users_roles: associates users and roles

You may find a copy of this in src/services/trunk/services/authentication/client/src/main/resources/db/mysql/authentication.sql.

Then you may want to add the following indices regardless of the approach you use to create tables.

You may find a copy of this in src/services/trunk/services/authentication/client/src/main/resources/db/mysql/authentication_index.sql

Configure application policy

To configure JBoss's login configuration to add an application policy using the JAAS Login Module:

Edit $JBOSS_HOME/server/cspace/conf/login-config.xml and add the following snippet anywhere above the application-policy named other.


The following configuration is according to release 0.5

Note that the module-option with name dsJndiName is referring to the same datasource as configured in datasource configuration . Secondly, the name of the application-policy cspace is also the name of security domain for JBoss. Lastly, you would require to use CSpacePrincipal to populate tenant-specific context into the security context.

The above configuration indicates that hash algorithm SHA-256 is used to encrypt passwords before storing in the database. Password is case-sensitive. It also lists SQL queries to use to retrieve password and user-role association(s) from the database.

You may find the latest version of this in /src/services/trunk/services/authentication/service/src/main/resources/config/jboss-login-config.xml.


  1. Account Service Description and Assumptions