Stored ID Data Connector

This connector creates and persists unique identifiers. The first ID created for a given requester is always the same as those created by the computed ID data connector in order to provide a migration path from that data connector. Every subsequently generated ID for a given user/IdP/SP triple, if the first one is revoked, is a Type 4 UUID.

The IDs are created by this data connector are usually used as user identifiers because of their properties:

each requester receives a unique, opaque, identifier preventing multiple requesters from performing any correlation attacks
each requester always get the same ID so they may associate user preferences with the ID
the ID can be used as a SAML 1 or SAML 2 name identifier
an ID may be revoked and new one generated

1. Define the Database

The Stored ID data connector stores its created ID in a database. You must create a database with the following definition. Note this definition is database independent and may need additional information depending on the database you use. Examples for common database systems are available.

CREATE TABLE shibpid (
    localEntity VARCHAR NOT NULL,
    peerEntity VARCHAR NOT NULL,
    principalName VARCHAR NOT NULL,
    localId VARCHAR NOT NULL,
    persistentId VARCHAR NOT NULL,
    peerProvidedId VARCHAR NULL,
    creationDate TIMESTAMP NOT NULL,
    deactivationDate TIMESTAMP NULL
)

You should also create indexes on the following sets of fields:

persistentId
persistentId, deactivationDate
localEntity, peerEntity, localId,
localEntity, peerEntity, localId, deactivationDate

Ensure that the collation associated with the localId field is appropriate for use with the sourceAttributeID you will specify below. An inappropriate collation could render the attribute non-unique.
In particular, it has been observed that a case-sensitive collation is needed if using the Active Directory objectSid as the source attribute, to ensure that persistent IDs are uniquely identified.
utf8_bin has been found to work in this circumstance.

2. Define the Connector

To define a new computed ID data connector, create a <DataConnector xsi:type="dc:StoredId" xmlns="urn:mace:shibboleth:2.0:resolver:dc"> element with the following attributes:

id - a unique identifier for the data connector
sourceAttributeID - the ID of an attribute, provided by a dependency, whose first value will be used within the computed ID hash
generatedAttributeID - name of the attribute produced by this data connector. optional, defaults to storedId

salt - a string of random data; must be at least 16 characters, 48 characters is recommended. Be sure to write down this salt value somewhere safeso that the persistentIDs are not lost if you delete your configuration file!

It is recommended that the attribute given by sourceAttributeID be a non-reassigned value, unique to each user. Usage of such a value effectively eliminates problems that may occur if a value is re-assigned and a service provider has not cleaned out state from the previous owner of that ID.

<resolver:DataConnector xsi:type="dc:StoredId" xmlns="urn:mace:shibboleth:2.0:resolver:dc"
                        id="UNIQUE_ID"
                        generatedAttributeID="OUTPUT_UNIQUE_ID"
                        sourceAttributeID="SOME_ID"
                        salt="ThisIsRandomText">

    <!-- Remaining configuration from the next steps go here -->

</resolver:DataConnector>

3. Define Dependencies

This data connector requires exactly one dependency, which provides the attribute identified by the sourceAttributeID attribute.

Dependencies are expressed by the <resolver:Dependency> with a ref attribute whose value is the unique ID of the attribute definition or the data connector that this connector depends on.

<resolver:DataConnector xsi:type="dc:StoredId" xmlns="urn:mace:shibboleth:2.0:resolver:dc"
                        id="UNIQUE_ID"
                        sourceAttributeID="SOME_ID"
                        generatedAttributeID="OUTPUT_UNIQUE_ID"
                        salt="ThisIsRandomText">

     <resolver:Dependency ref="DEFINITION_ID_1" />

    <!-- Remaining configuration from the next steps go here -->

</resolver:DataConnector>

4a. Define Identity Provider (Application) Managed Database Connections

Deployers wishing to allow the data connector to manage connections to the database should follow these instructions, those wishing to allow the Servlet container to manage the connections should use the instructions in step 4b.

Identity Provider (application) managed connections are defined by a <ApplicationManagedConnection> element with the following attributes:

jdbcDriver - the fully qualified class name of the JDBC driver used to make connections to the database
jdbcURL - the connection URL for the database
jdbcUserName - the user name used to connect to the database
jdbcPassword - the password used to connect to the database

<resolver:DataConnector xsi:type="dc:StoredId" xmlns="urn:mace:shibboleth:2.0:resolver:dc"
                        id="UNIQUE_ID"
                        sourceAttributeID="SOME_ID"
                        generatedAttributeID="OUTPUT_UNIQUE_ID"
                        salt="ThisIsRandomText">

     <resolver:Dependency ref="DEFINITION_ID_1" />

     <ApplicationManagedConnection jdbcDriver="DRIVER_CLASS"
                                   jdbcURL="DATABASE_URL"
                                   jdbcUserName="DATABASE_USER"
                                   jdbcPassword="DATABASE_USER_PASSWORD" />

</resolver:DataConnector>

In order to use a database you must place the JDBC driver, for your database, in the IDP_SRC/lib directory. You must then rerun the install script (to generate a new WAR) and eventually restart your servlet container.

Advanced Options

The <ApplicationManagedConnection> element also allows the following, advanced, configuration attributes controlling how connections are pooled:

poolAcquireIncrement - number of new connections to create when a pool is exhausted; defaults to 3
poolAcquireRetryAttempts - number of times the pool will attempt retry connections, upon a failure; defaults to 36
poolAcquireRetryDelay - number of milliseconds the pool will wait before trying to establish a connection to the database if an error occurs; defaults to 5000
poolBreakAfterAcquireFailure - boolean flag indicating whether the database should be marked as permanently unavailable if a good connection can not be created after the poolAcquireRetryAttempts; defaults to true
poolMinSize - minimum number of open connections that the pool will keep; defaults to 2
poolMaxSize - maximum number of open connections the pool will keep; defaults to 50, a value of 0 indicated no maximum
poolMaxIdleTime - number of seconds a connection may remain idle before being shutdown; defaults to 600
poolIdleTestPeriod - number of seconds the pool will wait before running the next scan for idle connections; defaults to 180

4b. Define Container Managed Database Connections

Configuration that use container managed connections can not be tested from the command line.

Deployers wishing to have their Servlet container manage connections to a database should follow these instructions, those wishing to allow the data connector to manage the connections should use the instructions in step 4a.

Servlet container managed connections are defined by a <ContainerManagedConnection> element with the following attributes:

resourceName - JNDI location of the Java Connection DataSource

The <ContainerManagedConnection> may also contain any number of <JNDIConnectionProperty> elements that specify the JNDI connection properties appropriate for the container. Refer to your container documentation for these properties. Some common JNDI connection parameters are listed by Sun.

<resolver:DataConnector xsi:type="dc:StoredId" xmlns="urn:mace:shibboleth:2.0:resolver:dc"
                        id="UNIQUE_ID"
                        sourceAttributeID="SOME_ID"
                        generatedAttributeID="OUTPUT_UNIQUE_ID"
                        salt="ThisIsRandomText">

     <resolver:Dependency ref="DEFINITION_ID_1" />

     <ContainerManagedConnection resourceName="RESOURCE_NAME"  />
</resolver:DataConnector>

In order to use a database you must place the JDBC driver, for your database, in your servlet's classpath and restart your servlet container. Refer to your servlet container's documentation for instructions.