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.
You should also create indexes on the following sets of fields:
- 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
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
sourceAttributeIDbe 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.
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.
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
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.
<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
<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.
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.