Dies ist eine alte Version des Dokuments!
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).
Installation Datenbanksoftware
MySQL
Debian 8
root@idp:~# apt-get install mysql-server mysql-client libmysql-java
Damit der Tomcat die MySQL-Java-Library beim Starten einliest (damit 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
PostgreSQL
Siehe hierzu einstweilen die Anleitung der Schweizer Kolleg(inn)en. Hierzu jedenfalls die entsprechende Java JDBC Komponente installieren (Debian/Ubuntu):
root@idp:~# apt-get install libpostgresql-jdbc-java
RHEL
yum install postgresql-server postgresql
Datenbank-Konfiguration
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“) für die User Consent Informationen wird automatisch generiert.
Hier ein Beispiel für MySQL, wobei hier vorrausschauend 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 diese Version: global.xml.
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
PersistentId Konfiguration
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 muß 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 muß 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>
Session-Informationen und User Consent in DB ablegen
Nachdem Datenbankverbindung und persistentId aktiviert sind können diese nun für die Speicherung von Session-und Userconsent-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 # damit der User eine ausführliche Logout-Rückmeldung vom IdP bekommt: # Whether to lookup metadata, etc. for every SP involved in a logout # for use by user interface logic; adds overhead so off by default. idp.logout.elaboration = true
Starten Sie Tomcat neu um die neuen Einstellungen zu aktivieren (dabei Logdateien mitverfolgen!):
root@idp:/opt/shibboleth-idp# service tomcat8 restart
Weitergabe der Persistent ID
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 nochmal 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.