CollectionSpace Identity Provider (CS IdP)

Unknown macro: {multi-excerpt}

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

Unknown macro: {multi-excerpt-include}

Assumptions

Unknown macro: {multi-excerpt}

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

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:

Create necessary tables in database
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.

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.

Table users: stores user names, (encrypted) passwords
Table roles: stores role names, role group
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

Unknown macro: {multi-excerpt}

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

    <!--
copy the following snippet into $JBOSS_HOME/server/cspace/conf/login-config.xml
copy before the "other" application-policy
-->

<application-policy name="cspace">
    <authentication>
        <login-module code="org.collectionspace.authentication.jaas.CSpaceJBossDBLoginModule"
                      flag="required">
            <module-option name="dsJndiName">CspaceDS</module-option>
            <module-option name="hashAlgorithm">SHA-256</module-option>
            <module-option name="ignorePasswordCase">false</module-option>
            <module-option name = "principalClass">org.collectionspace.authentication.CSpacePrincipal</module-option>
            <module-option name="principalsQuery">
                select passwd from users where username=?
            </module-option>
            <module-option name="rolesQuery">
                select rolename, 'Roles' from users_roles where username=?
            </module-option>
            <module-option name="tenantsQuery">
                select t.id, t.name, 'Tenants' from accounts_common as a, accounts_tenants as at, tenants as t where a.userid=? and a.csid = at.TENANTS_ACCOUNTSCOMMON_CSID and at.tenant_id = t.id
            </module-option>
        </login-module>
    </authentication>
</application-policy>

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.

References

Account Service Description and Assumptions