net.shibboleth.idp.saml.nameid.impl

Class JDBCPersistentIdStoreEx

java.lang.Object

net.shibboleth.utilities.java.support.component.AbstractInitializableComponent

net.shibboleth.idp.saml.nameid.impl.JDBCPersistentIdStoreEx

All Implemented Interfaces:

PersistentIdStoreEx, IPersistentIdStore, Component, DestructableComponent, InitializableComponent

public class JDBCPersistentIdStoreEx
extends AbstractInitializableComponent
implements PersistentIdStoreEx

JDBC-based storage management for SAML persistent IDs.

The general DDL for the database is:

 CREATE TABLE shibpid (
      localEntity VARCHAR(255) NOT NULL,
      peerEntity VARCHAR(255) NOT NULL,
      persistentId VARCHAR(50) NOT NULL,
      principalName VARCHAR(50) NOT NULL,
      localId VARCHAR(50) NOT NULL,
      peerProvidedId VARCHAR(50) NULL,
      creationDate TIMESTAMP NOT NULL,
      deactivationDate TIMESTAMP NULL,
      PRIMARY KEY (localEntity, peerEntity, persistentId)
     );

. The first three columns should be defined as the primary key of the table, and the other columns should be indexed.

Field Summary

Fields

Modifier and Type	Field and Description
private String	attachSQL Parameterized update statement used to attach an alias to an ID.
private String	creationTimeColumn Name of the creation time column.
private DataSource	dataSource JDBC data source for retrieving connections.
private String	deactivateSQL Parameterized update statement used to deactivate an ID.
private String	deactivationTimeColumn Name of the deactivation time column.
private String	deleteSQL Parameterized delete statement used to clear dummy rows after verification.
private String	getByIssuedSelectSQL Parameterized select query for lookup by issued value.
private String	getBySourceSelectSQL Parameterized select query for lookup by source ID.
private String	insertSQL Parameterized insert statement used to insert a new record.
private String	issuerColumn Name of the issuer entityID column.
private org.slf4j.Logger	log Class logger.
private String	peerProvidedIdColumn Name of recipient-attached alias column.
private String	persistentIdColumn Name of the persistent ID column.
private String	principalNameColumn Name of the principal name column.
private long	queryTimeout Timeout of SQL queries in milliseconds.
private String	recipientColumn Name of the recipient entityID column.
private Collection<String>	retryableErrors Error messages that signal a transaction should be retried.
private String	sourceIdColumn Name of the source ID column.
private String	tableName Name of the database table.
private int	transactionRetry Number of times to retry a transaction if it rolls back.
private boolean	verifyDatabase Whether to fail if the database cannot be verified.

Constructor Summary

Constructors

Constructor and Description
JDBCPersistentIdStoreEx() Constructor.

Method Summary

Methods

Modifier and Type	Method and Description
void	attach(String nameQualifier, String spNameQualifier, String persistentId, String spProvidedId) Attach an SPProvidedID value to an existing entry.
private List<PersistentIdEntry>	buildIdentifierEntries(ResultSet resultSet) Builds a list of PersistentIdEntrys from a result set.
void	deactivate(String nameQualifier, String spNameQualifier, String persistentId, DateTime deactivation) Deactivate/revoke a persistent ID.
protected void	doInitialize()
PersistentIdEntry	getByIssuedValue(String nameQualifier, String spNameQualifier, String persistentId) Get the PersistentIdEntry for a previously issued ID triple.
PersistentIdEntry	getBySourceValue(String nameQualifier, String spNameQualifier, String sourceId, String principal, boolean allowCreate, ComputedPersistentIdGenerationStrategy computedIdStrategy) Get the PersistentIdEntry for a given subject and audience, creating one if allowable and necessary.
private Connection	getConnection(boolean autoCommit) Obtain a connection from the data source.
DataSource	getDataSource() Get the source datasource used to communicate with the database.
private String	getLogPrefix() Return a string which is to be prepended to all log messages.
long	getQueryTimeout() Get the SQL query timeout.
Collection<String>	getRetryableErrors() Get the error messages to check for classifying a driver error as retryable, generally indicating a lock violation or duplicate insert that signifies a broken database.
int	getTransactionRetries() Get the number of retries to attempt for a failed transaction.
boolean	getVerifyDatabase() Get whether to allow startup if the database cannot be verified.
void	setAttachSQL(String sql) Set the UPDATE statement used to attach an SPProvidedID to an issued value.
void	setCreateTimeColumn(String name) Set the name of the creation time column.
void	setDataSource(DataSource source) Get the source datasource used to communicate with the database.
void	setDeactivateSQL(String sql) Set the UPDATE statement used to deactivate issued values.
void	setDeactivationTimeColumn(String name) Set the name of the deactivation time column.
void	setDeleteSQL(String sql) Set the DELETE statement used to clear dummy row(s) created during verification.
void	setGetByIssuedSelectSQL(String sql) Set the SELECT statement used to lookup records by issued value.
void	setGetBySourceSelectSQL(String sql) Set the SELECT statement used to lookup records by source ID.
void	setInsertSQL(String sql) Set the INSERT statement used to insert new records.
void	setLocalEntityColumn(String name) Set the name of the issuer entityID column.
void	setPeerEntityColumn(String name) Set the name of the recipient entityID column.
void	setPeerProvidedIdColumn(String name) Set the name of the peer-provided ID column.
void	setPersistentIdColumn(String name) Set the name of the persistent ID column.
void	setPrincipalNameColumn(String name) Set the name of the principal name column.
void	setQueryTimeout(long timeout) Set the SQL query timeout.
void	setRetryableErrors(Collection<String> errors) Set the error messages to check for classifying a driver error as retryable, generally indicating a lock violation or duplicate insert that signifies a broken database.
void	setSourceIdColumn(String name) Set the name of the source ID column.
void	setTableName(String name) Set the table name.
void	setTransactionRetries(int retries) Set the number of retries to attempt for a failed transaction.
void	setVerifyDatabase(boolean flag) Set whether to allow startup if the database cannot be verified.
(package private) void	store(PersistentIdEntry entry, Connection dbConn) Store a record containing the values from the input object.
private void	verifyDatabase() Check the database and the presence of a uniqueness constraint.

Methods inherited from class net.shibboleth.utilities.java.support.component.AbstractInitializableComponent

destroy, doDestroy, initialize, isDestroyed, isInitialized

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

log

@Nonnull
private final org.slf4j.Logger log

Class logger.

dataSource

@NonnullAfterInit
private DataSource dataSource

JDBC data source for retrieving connections.

queryTimeout

@Duration
@NonNegative
private long queryTimeout

Timeout of SQL queries in milliseconds.

transactionRetry

@NonNegative
private int transactionRetry

Number of times to retry a transaction if it rolls back.

retryableErrors

@Nonnull
@NonnullElements
private Collection<String> retryableErrors

Error messages that signal a transaction should be retried.

verifyDatabase

private boolean verifyDatabase

Whether to fail if the database cannot be verified.

tableName

@Nonnull
@NotEmpty
private String tableName

Name of the database table.

issuerColumn

@Nonnull
@NotEmpty
private String issuerColumn

Name of the issuer entityID column.

recipientColumn

@Nonnull
@NotEmpty
private String recipientColumn

Name of the recipient entityID column.

principalNameColumn

@Nonnull
@NotEmpty
private String principalNameColumn

Name of the principal name column.

sourceIdColumn

@Nonnull
@NotEmpty
private String sourceIdColumn

Name of the source ID column.

persistentIdColumn

@Nonnull
@NotEmpty
private String persistentIdColumn

Name of the persistent ID column.

peerProvidedIdColumn

@Nonnull
@NotEmpty
private String peerProvidedIdColumn

Name of recipient-attached alias column.

creationTimeColumn

@Nonnull
@NotEmpty
private String creationTimeColumn

Name of the creation time column.

deactivationTimeColumn

@Nonnull
@NotEmpty
private String deactivationTimeColumn

Name of the deactivation time column.

getByIssuedSelectSQL

@NonnullAfterInit
private String getByIssuedSelectSQL

Parameterized select query for lookup by issued value.

getBySourceSelectSQL

@NonnullAfterInit
private String getBySourceSelectSQL

Parameterized select query for lookup by source ID.

insertSQL

@NonnullAfterInit
private String insertSQL

Parameterized insert statement used to insert a new record.

deactivateSQL

@NonnullAfterInit
private String deactivateSQL

Parameterized update statement used to deactivate an ID.

attachSQL

@NonnullAfterInit
private String attachSQL

Parameterized update statement used to attach an alias to an ID.

deleteSQL

@NonnullAfterInit
private String deleteSQL

Parameterized delete statement used to clear dummy rows after verification.

Constructor Detail

JDBCPersistentIdStoreEx

public JDBCPersistentIdStoreEx()

Constructor.

Method Detail

getDataSource

@NonnullAfterInit
public DataSource getDataSource()

Get the source datasource used to communicate with the database.

Returns:

the data source;

setDataSource

public void setDataSource(@Nonnull
                 DataSource source)

Get the source datasource used to communicate with the database.

Parameters:

source - the data source;

getQueryTimeout

@NonNegative
@Duration
public long getQueryTimeout()

Get the SQL query timeout.

Returns:

the timeout in milliseconds

setQueryTimeout

@Duration
public void setQueryTimeout(@Duration@NonNegative
                            long timeout)

Set the SQL query timeout. Defaults to 5000.

Parameters:

timeout - the timeout to set in milliseconds

getTransactionRetries

public int getTransactionRetries()

Get the number of retries to attempt for a failed transaction.

Returns:

number of retries

setTransactionRetries

public void setTransactionRetries(@NonNegative
                         int retries)

Set the number of retries to attempt for a failed transaction. Defaults to 3.

Parameters:

retries - the number of retries

getRetryableErrors

@Nonnull
@NonnullElements
public Collection<String> getRetryableErrors()

Get the error messages to check for classifying a driver error as retryable, generally indicating a lock violation or duplicate insert that signifies a broken database.

Returns:

retryable messages

setRetryableErrors

public void setRetryableErrors(@Nullable@NonnullElements
                      Collection<String> errors)

Set the error messages to check for classifying a driver error as retryable, generally indicating a lock violation or duplicate insert that signifies a broken database.

Parameters:

errors - retryable messages

getVerifyDatabase

public boolean getVerifyDatabase()

Get whether to allow startup if the database cannot be verified.

Returns:

whether to allow startup if the database cannot be verified

setVerifyDatabase

public void setVerifyDatabase(boolean flag)

Set whether to allow startup if the database cannot be verified.

Verification consists not only of a liveness check, but the successful insertion of a dummy row, a failure to insert a duplicate, and then deletion of the row.

Parameters:

flag - flag to set

setTableName

public void setTableName(@Nonnull@NotEmpty
                String name)

Set the table name.

Parameters:

name - table name

setLocalEntityColumn

public void setLocalEntityColumn(@Nonnull@NotEmpty
                        String name)

Set the name of the issuer entityID column.

Parameters:

name - name of issuer column

setPeerEntityColumn

public void setPeerEntityColumn(@Nonnull@NotEmpty
                       String name)

Set the name of the recipient entityID column.

Parameters:

name - name of recipient column

setPrincipalNameColumn

public void setPrincipalNameColumn(@Nonnull@NotEmpty
                          String name)

Set the name of the principal name column.

Parameters:

name - name of principal name column

setSourceIdColumn

public void setSourceIdColumn(@Nonnull@NotEmpty
                     String name)

Set the name of the source ID column.

Parameters:

name - name of source ID column

setPersistentIdColumn

public void setPersistentIdColumn(@Nonnull@NotEmpty
                         String name)

Set the name of the persistent ID column.

Parameters:

name - name of the persistent ID column

setPeerProvidedIdColumn

public void setPeerProvidedIdColumn(@Nonnull@NotEmpty
                           String name)

Set the name of the peer-provided ID column.

Parameters:

name - name of peer-provided ID column

setCreateTimeColumn

public void setCreateTimeColumn(@Nonnull@NotEmpty
                       String name)

Set the name of the creation time column.

Parameters:

name - name of creation time column

setDeactivationTimeColumn

public void setDeactivationTimeColumn(@Nonnull@NotEmpty
                             String name)

Set the name of the deactivation time column.

Parameters:

name - name of deactivation time column

setGetByIssuedSelectSQL

public void setGetByIssuedSelectSQL(@Nonnull@NotEmpty
                           String sql)

Set the SELECT statement used to lookup records by issued value.

Parameters:

sql - statement text, which must contain three parameters (NameQualifier, SPNameQualifier, value)

setGetBySourceSelectSQL

public void setGetBySourceSelectSQL(@Nonnull@NotEmpty
                           String sql)

Set the SELECT statement used to lookup records by source ID.

Parameters:

sql - statement text, which must contain six parameters (NameQualifier, SPNameQualifier, source ID, NameQualifier, SPNameQualifier, source ID)

setInsertSQL

public void setInsertSQL(@Nonnull@NotEmpty
                String sql)

Set the INSERT statement used to insert new records.

Parameters:

sql - statement text, which must contain 8 parameters (NameQualifier, SPNameQualifier, value, principal, source ID, SPProvidedID, creation time, deactivation time)

setDeactivateSQL

public void setDeactivateSQL(@Nonnull@NotEmpty
                    String sql)

Set the UPDATE statement used to deactivate issued values.

Parameters:

sql - statement text, which must contain four parameters (deactivation TS, NameQualifier, SPNameQualifier, value)

setAttachSQL

public void setAttachSQL(@Nonnull@NotEmpty
                String sql)

Set the UPDATE statement used to attach an SPProvidedID to an issued value.

Parameters:

sql - statement text, which must contain four parameters (SPProvidedID, NameQualifier, SPNameQualifier, value)

setDeleteSQL

public void setDeleteSQL(@Nonnull@NotEmpty
                String sql)

Set the DELETE statement used to clear dummy row(s) created during verification.

Parameters:

sql - statement text, which must contain one parameter (NameQualifier)

doInitialize

protected void doInitialize()
                     throws ComponentInitializationException

Overrides:

doInitialize in class AbstractInitializableComponent

Throws:

ComponentInitializationException

getByIssuedValue

@Nullable
public PersistentIdEntry getByIssuedValue(@Nonnull@NotEmpty
                                          String nameQualifier,
                                          @Nonnull@NotEmpty
                                          String spNameQualifier,
                                          @Nonnull@NotEmpty
                                          String persistentId)
                                   throws IOException

Get the PersistentIdEntry for a previously issued ID triple.

Specified by:

getByIssuedValue in interface PersistentIdStoreEx

Parameters:

nameQualifier - the NameQualifier value

spNameQualifier - the SPNameQualifier value

persistentId - the persistent ID value

Returns:

PersistentIdEntry for the given inputs or null if none exists

Throws:

IOException - if an error occurs accessing the store

getBySourceValue

@Nullable
public PersistentIdEntry getBySourceValue(@Nonnull@NotEmpty
                                          String nameQualifier,
                                          @Nonnull@NotEmpty
                                          String spNameQualifier,
                                          @Nonnull@NotEmpty
                                          String sourceId,
                                          @Nonnull@NotEmpty
                                          String principal,
                                          boolean allowCreate,
                                          @Nullable
                                          ComputedPersistentIdGenerationStrategy computedIdStrategy)
                                   throws IOException

Get the PersistentIdEntry for a given subject and audience, creating one if allowable and necessary.

Specified by:

getBySourceValue in interface PersistentIdStoreEx

Parameters:

nameQualifier - the NameQualifier value

spNameQualifier - the SPNameQualifier value

sourceId - source attribute underlying the persistent ID

principal - principal name of subject (may or may not be the same as the sourceId)

allowCreate - whether it's permissible to establish/issue a new identifier

computedIdStrategy - optional source of initial computed IDs for compatibilty with that mechanism

Returns:

PersistentIdEntry for the given inputs, or null if none exists and allowCreate is false

Throws:

IOException - if an error occurs accessing the store

deactivate

public void deactivate(@Nonnull@NotEmpty
              String nameQualifier,
              @Nonnull@NotEmpty
              String spNameQualifier,
              @Nonnull@NotEmpty
              String persistentId,
              @Nullable
              DateTime deactivation)
                throws IOException

Deactivate/revoke a persistent ID.

Specified by:

deactivate in interface PersistentIdStoreEx

Parameters:

nameQualifier - the NameQualifier value

spNameQualifier - the SPNameQualifier value

persistentId - ID to deactivate

deactivation - deactivation time (if null the current time is used)

Throws:

IOException - if there is an error updating the store

attach

public void attach(@Nonnull@NotEmpty
          String nameQualifier,
          @Nonnull@NotEmpty
          String spNameQualifier,
          @Nonnull@NotEmpty
          String persistentId,
          @Nonnull@NotEmpty
          String spProvidedId)
            throws IOException

Attach an SPProvidedID value to an existing entry.

Specified by:

attach in interface PersistentIdStoreEx

Parameters:

nameQualifier - the NameQualifier value

spNameQualifier - the SPNameQualifier value

persistentId - ID to deactivate

spProvidedId - the value to attach

Throws:

IOException - if there is an error updating the store

store

void store(@Nonnull
         PersistentIdEntry entry,
         @Nonnull
         Connection dbConn)
     throws SQLException

Store a record containing the values from the input object.

Parameters:

entry - new object to store

dbConn - connection to obtain a statement from.

Throws:

SQLException - if an error occurs

getConnection

@Nonnull
private Connection getConnection(boolean autoCommit)
                          throws SQLException

Obtain a connection from the data source.

The caller must close the connection.

Parameters:

autoCommit - auto-commit setting to apply to the connection

Returns:

a fresh connection

Throws:

SQLException - if an error occurs

verifyDatabase

private void verifyDatabase()
                     throws SQLException

Check the database and the presence of a uniqueness constraint.

Throws:

SQLException - if the database cannot be verified

buildIdentifierEntries

@Nonnull
@NonnullElements
@Live
private List<PersistentIdEntry> buildIdentifierEntries(@Nonnull
                                                                          ResultSet resultSet)
                                                throws SQLException

Builds a list of PersistentIdEntrys from a result set.

Parameters:

resultSet - the result set

Returns:

list of PersistentIdEntrys

Throws:

SQLException - thrown if there is a problem reading the information from the database

getLogPrefix

@Nonnull
@NotEmpty
private String getLogPrefix()

Return a string which is to be prepended to all log messages.

Returns:

"Stored Id Store:"