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

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.

  Basic Stored ID Data Connector

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

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

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>