Server-Side-Storage und Persistent Identifier

Per default werden Informationen zu User Consent (ehemals uApprove) und Persistent IDs client-seitig in Cookies abgelegt. Dies kann aber nur als initiale „Notlösung“ betrachtet werden, damit der IdP auch ohne angeschlossene SQL-Datenbank funktioniert. In einem fertigen Produktivszenario ist das Abspeichern dieser Informationen auf Serverseite unbedingt zu empfehlen, da nur damit erweiterte SAML-Funktionalitäten möglich sind (z.B. persistentId, Single-Logout).

root@idp:~# apt-get install mysql-server mysql-client libmysql-java 

Damit der Tomcat die MySQL-Java-Library beim Starten einliest (d.h. der IdP sie dann verwenden kann), wird diese üblicherweise in /etc/tomcat8/catalina.properties in den „common.loader“ aufgenommen. Dies hat den Nachteil, dass diese Datei dann bei jedem Upgrade manuell mit einer neuen catalina.properties verglichen werden muss. Man kann sich die Arbeit ersparen (sofern man dort nicht sowieso Anpassungen machen muss, was beim Einsatz des IdPs als einziges Servlet im Tomcat aber nicht nötig sein sollte!), indem man die mysql-Datei in das Runtime-Lib-Verzeichnis von Tomcat verlinkt. Dort wird sie dann automatisch eingelesen:

root@idp:~# ln -s /usr/share/java/mysql.jar /var/lib/tomcat8/lib/mysql.jar

Starten Sie Tomcat neu um die neuen Einstellungen zu aktivieren (dabei Logdateien mitverfolgen!):

root@idp:~# service tomcat8 restart

Siehe hierzu einstweilen die Anleitung der Schweizer Kolleg(inn)en. Hierzu ist jedenfalls die entsprechende Java JDBC Komponente installieren (Debian/Ubuntu):

root@idp:~# apt-get install libpostgresql-jdbc-java

yum install postgresql-server postgresql

Zunächst ist eine logische Datenbank zu erstellen. Hierzu müssen, wie vom IdP 2.x gewohnt, zunächst nur die Tabellen für die Angaben zur Persistent Id angelegt werden, die Tabelle „StorageRecords“ (u.a. für die User Consent Informationen) wird automatisch generiert.

Hier ein Beispiel für MySQL, wobei hier vorausschauend auch gleich eine Tabelle für die persistentId angelegt wird, welche später noch gebraucht wird (siehe später in dieser Anleitung):

mysql> SET NAMES 'utf8';
SET CHARACTER SET utf8;
CHARSET utf8;
CREATE DATABASE IF NOT EXISTS shibboleth CHARACTER SET=utf8;
USE shibboleth;
 
mysql> CREATE TABLE IF NOT EXISTS 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)
);
 
mysql> CREATE USER 'shibboleth'@'localhost' IDENTIFIED BY 'GeHEIM007';
 
mysql> GRANT ALL PRIVILEGES ON shibboleth.* TO 'shibboleth'@'localhost';
 
mysql> FLUSH PRIVILEGES;

Ein Beispiel für PostgreSQL findet sich beim SWITCH.

Der DB-Zugriff wird über den JPAStorageService gekapselt. Dieser wird in ./conf/global.xml definiert. Diese Datei ist im Auslieferungszustand leer (bis auf Kommentare). Ersetzen Sie sie durch die hier bereitgestellte Version.

Starten Sie Tomcat neu, um sicherzustellen, dass die global.xml ohne Probleme eingelesen werden kann (dabei Logdateien mitverfolgen!):

root@idp:/opt/shibboleth-idp# service tomcat8 restart

Hinweis: bei älteren Java Versionen führt der Parameter „p:validationQueryTimeout“ zu einer Fehlermeldung, in dem Fall einfach weglassen und Tomcat neu starten.

PostgreSQL: Siehe Dokumentation von SWITCH und die dort zur Verfügung gestellte global.xml:
https://www.switch.ch/aai/guides/idp/installation/global.xml

Die Properties für den DB-Zugriff werden jetzt noch in idp.properties ergänzt (bitte auf die Tomcat-Version achten!):

/opt/shibboleth-idp/conf/idp.properties

# Tomcat7
#mysql.class   = org.apache.commons.dbcp.BasicDataSource
# Tomcat8
mysql.class    = org.apache.tomcat.jdbc.pool.DataSource
mysql.url      = jdbc:mysql://localhost:3306/shibboleth
mysql.username = shibboleth
mysql.password = GeHEIM007

Starten Sie Tomcat neu um die neuen Einstellungen zu aktivieren (dabei Logdateien mitverfolgen!):

root@idp:/opt/shibboleth-idp# service tomcat8 restart

Die persistentId wird in drei Schritten aktiviert:

Erstens wird festgelegt, wie die Id generiert und abgelegt werden soll:

/opt/shibboleth-idp/conf/saml-nameid.properties

# ein Attribut aus attribute-resolver.xml als unique Identifier, dabei wird hier der Wert der "id"
# dieses Attributes aus attribute-resolver.xml referenziert und _nicht_ der Attribut-Name aus dem IdM!
# in den allermeisten Fällen wird das immer 'uid' sein, auch bei Microsoft AD (dort dient das IdM-
# Attribut 'sAMAccountName' bzw. neuerdings 'cn' als Quelle fur das IdP-Attribut 'uid')
idp.persistentId.sourceAttribute = uid 
#idp.persistentId.useUnfilteredAttributes = true
# Do *NOT* share the salt with other people, it's like divulging your private key.
#idp.persistentId.algorithm = SHA
idp.persistentId.salt = MöglichstBeliebigUndGeHeim-mindestens-16bytes
 
# To use a database, use shibboleth.StoredPersistentIdGenerator
idp.persistentId.generator = shibboleth.StoredPersistentIdGenerator
# For basic use, set this to a JDBC DataSource bean name:
idp.persistentId.dataSource = shibboleth.MySQLDataSource

Hinweise zur Wahl des Quellatributs:

• Als Quellattribut aus dem IdM für die persistentId muss man ein IdM-Attribut nehmen, welches auch über die Zeit für alle Benutzer eindeutig ist. Oft ist dies das IdM-Attribut 'uid' (oder bei AD 'sAMAccountName' bzw. neuerdings 'cn'). Sollte dies bei Ihnen nicht der Fall sein, d.h. diese Attribute werden für neue User recycled (auch aus anderen Gründen nicht zu empfehlen!), dann muss ein anderes IdM-Attribut gefunden werden.
• Eine Möglichkeit, dieses Problem zu umgehen, besteht darin, sich ein neues Attribut in attribute-resolver.xml zu definieren. Dieses Attribut könnte zum Beispiel aus einem Hash aus uid und dem Anlegedatum des Accounts bestehen.
• Beispiele zur Generierung finden Sie unter Persistent ID - Sonderfälle.

Zweitens wird die Java-Bean für die Generierung aktiviert indem der Eintrag für shibboleth.SAML2PersistentGenerator ent-kommentieren wird:

/opt/shibboleth-idp/conf/saml-nameid.xml

<beans ...>
    <!-- ... -->
    <!-- SAML 2 NameID Generation -->
    <util:list id="shibboleth.SAML2NameIDGenerators">
 
        <ref bean="shibboleth.SAML2TransientGenerator" />
 
        <!-- Uncommenting this bean requires configuration in saml-nameid.properties. -->
 
        <ref bean="shibboleth.SAML2PersistentGenerator" />
 
    </util:list>
    <!-- ... -->
</beans>

Drittens wird die Verarbeitung der Id aktiviert:

/opt/shibboleth-idp/conf/c14n/subject-c14n.xml

<beans ...>
    <!-- ... -->
    <util:list id="shibboleth.SAMLSubjectCanonicalizationFlows">
        <!-- ... -->
 
        <!-- Handle a SAML 2 persistent ID, provided a stored strategy is in use. -->
        <ref bean="c14n/SAML2Persistent" />
 
        <!-- ... -->
    </util:list>
    <!-- ... -->
</beans>

Viertens: meist sind Usernamen im IdM-System unabhängig von Gross- und Kleinschreibung. D.h. die User können Ihren Loginnamen sowohl in Gross- als auch Kleinschreibung angeben und damit einen erfolgreichen Login durchführen. Allerdings führt dieses später zu Problemen beim Verwalten der Usernamen in der lokalen IdP-Datenbank da diese Gross- und Kleinschreibung unterscheidet. Wir empfehlen daher den Usernamen in diesen Fällen im IdP in Kleinbuchstaben umzuwandeln:

./conf/c14n/simple-subject-c14n-config.xml

   ...
   <util:constant id="shibboleth.c14n.simple.Lowercase" static-field="java.lang.Boolean.TRUE"/>
   ...

Damit werden die Usernamen vom IdP nur noch in Kleinbuchstabenform verarbeitet und in die Datenbank geschrieben.

Nachdem Datenbankverbindung und persistentId aktiviert sind, können diese nun für die Speicherung von Session- und User Consent-Informationen genutzt werden. Dadurch wird als netter Nebeneffekt auch SingleLogout- Unterstützung im IdP ermöglicht:

/opt/shibboleth-idp/conf/idp.properties

...
# Set to "shibboleth.StorageService" for server-side storage of user sessions
idp.session.StorageService = shibboleth.JPAStorageService
 
# Set to "shibboleth.StorageService" or custom bean for alternate storage of consent
idp.consent.StorageService = shibboleth.JPAStorageService 
 
# Set to "shibboleth.consent.AttributeConsentStorageKey" to use an attribute
# to key user consent storage records (and set the attribute name)
idp.consent.userStorageKey = shibboleth.consent.AttributeConsentStorageKey
idp.consent.userStorageKeyAttribute = %{idp.persistentId.sourceAttribute}
 
# Flags controlling how built-in attribute consent feature operates
#idp.consent.allowDoNotRemember = true
# damit der User für jeden SP mindestens einmal einwilligen muß sollte
# die Möglichkeit für eine globale Einwilligung abgeschaltet werden:
idp.consent.allowGlobal = false
#idp.consent.allowPerAttribute = false
 
# Damit auch bei neuem Wert eines Attributes und bei neuem Terms-Of-Use-Text der
# User erneut abnicken muss. Da jetzt statt Browser-Cookies eine lokale DB zur
# Verfügung steht sollte dieses sinnvolle Feature aktiviert werden!
idp.consent.compareValues = true

Starten Sie Tomcat neu, um die neuen Einstellungen zu aktivieren (dabei Logdateien mitverfolgen!):

root@idp:/opt/shibboleth-idp# service tomcat8 restart

Um die persistentId für alle SPs freizugeben muss die SAML2.SSO-Bean-Definition erweitert werden:

/conf/relying-party.xml

<beans ...>
  <!-- ... -->
  <bean id="shibboleth.DefaultRelyingParty" parent="RelyingParty">
    <property name="profileConfigurations">
       <list>
         <!-- ... -->
         <bean parent="SAML2.SSO" 
               p:postAuthenticationFlows="#{{'terms-of-use', 'attribute-release'}}" 
               p:nameIDFormatPrecedence="#{{'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient'}}"/>
         <!-- ... -->
        </list>
    </property>
  </bean>
  <!-- ... -->
</beans>

Starten Sie Tomcat neu, um die neuen Einstellungen zu aktivieren (dabei Logdateien mitverfolgen!):

root@idp:/opt/shibboleth-idp# service tomcat8 restart

Testen Sie nochmals einen Login mithilfe der DFN-Test-SP(s) und überzeugen Sie sich, dass die persistentId übertragen wird.

Falls Sie die persistentId nur an ausgewählte SPs übertragen wollen, finden Sie Beispiele unter Persistent ID - Sonderfälle.

Weiter geht es mit Single Logout.