The IdP 2.x installation manual had been recommending to use the ComputeID connector to generate eduPersonTargetedID values.  While that made the setup simpler (no database setup needed), it has the consequence that there is no database of eduPersonTargetedID values issued.

This page describes how to change the IdP configuration to use a StoredID Connector instead to store the values in a database.

Earlier versions of the manual for Upgrading a 2.x IdP to 3.x were instructing to follow the instructions here when performing an upgrade from a 2.x IdP that was using ComputedIdConnector for eduPersonTargetedID (i.e., not storing the values in a database).

While it is still strongly recommended to store the values in a database, it is no longer deemed necessary to change the configuration of the version 2 IdP, as the version 3 IdP would be producing the same values.

However, if the existing persistent ID values are not stored in a database, it is crucial to use the identical salt value on the old 2.x and the new 3.x IdP.

This document is left here as a resource to configure a IdP 2.x IdP to store the persistent ID values in a database, but it is no longer a prerequisite for upgrading to IdP 3.x.

 

Motivation

As in the migration to IdP v3, there would be also a migration from eduPersonTargetedID (used as an attribute) to SAML2 Persistent NameID (used as the NameID in SAML assertions), there will also be a need to switch to a different generator of persistent IDs.   The new generator (used with SAML2 Persistent NameIDs) can be configured to use the same database and reuse persistent IDs already assigned.  When configured with identical salt, for matching usernames, it would also generate same values as the previous generator. 

Earlier versions of this document were incorrectly stating these values would be different.  The wording in the rest of the document is kept with the original assumption the values would be different.

 

Therefore, to ensure a smooth migration, it is necessary to re-configure eduPersonTargetedID on the existing IdP to switch to using a database (with the StoredID connector which generates same values as the ComputeId connector) and populate the database with all persistent IDs already in use.

With this change in place, any persistent ID passed in an SSO session would be recorded in the database.  To cover all persistent IDs ever issued, it would be possible to:

After that, the migration to IdPv3 would preserve persistent IDs for all users.

Assumptions

This manual expects an IdP 2.x installation based on the manual Installing a Shibboleth 2.x IdP.

It expects a local MySQL database server has been already set up and a database created (for storing auEduPersonSharedToken values).

It also expects MySQL JDBC driver has been already installed in Tomcat.

Fixing missing assumptions - MySQL database

If the MySQL-related assumptions above do not hold, the following steps would make them hold:

And in addition to fixing missing assumptions, also explicitly install the MySQL driver into the IdP deployment directory - so that the aacli.sh tool used later can find the driver as well:

ln -s /usr/share/java/mysql-connector-java.jar /opt/shibboleth-idp/lib/

Creating MySQL table

The persistent ID values are stored in the shibpid table.

For simplicity, we recommend creating the table in the idp_db database which already holds the auEduPersonSharedToken values (in the tb_st table).

Create the table with the following DDL (reused from https://wiki.shibboleth.net/confluence/display/SHIB2/StoredIDDataConnectorDDL): - run mysql idb_db and enter:

CREATE TABLE IF NOT EXISTS shibpid (
  localEntity TEXT NOT NULL,
  peerEntity TEXT NOT NULL,
  principalName VARCHAR(255) NOT NULL DEFAULT '',
  localId VARCHAR(255) NOT NULL,
  persistentId VARCHAR(36) NOT NULL,
  peerProvidedId VARCHAR(255) DEFAULT NULL,
  creationDate timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,
  deactivationDate TIMESTAMP NULL DEFAULT NULL,
  KEY persistentId (persistentId),
  KEY persistentId_2 (persistentId, deactivationDate),
  KEY localEntity (localEntity(16), peerEntity(16), localId),
  KEY localEntity_2 (localEntity(16), peerEntity(16),
    localId, deactivationDate)
) ENGINE=MyISAM DEFAULT CHARSET=utf8;

Changes to Attribute Resolver

Edit /opt/shibboleth-idp/conf/attribute-resolver.xml and make the following changes:

Triggering recalculation of Persistent ID values

With the IdP now configured to store Persistent ID values in the database, any newly calculated values are stored in the database as they are used. However, to ensure all users keep their identity at all services they ever accessed, we would either need to wait until they log into all of the services again (yes, unrealistic), or we trigger the IdP to act as if the user logged into the service. For that, we use the command-line interface to the Attribute Authority - aacli.sh.

Troubleshooting aacli.sh invocations

The aacli.sh tool may fail to run for a number of reasons.  Here are the most common ones - and possible remedies: