Shibboleth IdPv4 in der Schulungs-VM

Hinweise

1. Sie können den Shibboleth Identity Provider mit dieser Anleitung in der VM installieren. Die weiterführenden Links zur Dokumentation sind für Ihre spätere, echte Installation gedacht.
2. Import des heruntergeladenen .ova-Images in Virtualbox: Datei -> Appliance importieren. Im BIOS muss Hardware-Virtualisierung angeschaltet sein.
3. Für ein Copy & Paste ohne Gasterweiterungen können Sie diese Installationsanleitung selbstverständlich auch im Browser in der VM abrufen. Dazu finden Sie im Firefox ein Lesezeichen in der Leiste.
4. Betriebssystem der Schulungs-VM: Ubuntu 22.04
5. Alle Passwörter lauten "shibboleth".
6. Auf der VM befindet sich ein LDAP-Browser (phpLDAPadmin), der im Web-Browser (Firefox) als Lesezeichen gesetzt ist. Im Verzeichnis finden Sie vier Test-Accounts mit verschiedenen Attributen.
7. Zum besseren Verständnis des lokalen Setups (idp/sp1/sp2) hilft ein Blick in /etc/hosts und die Apache-Konfiguration unter /etc/apache2/sites-enabled.
8. Für die echte spätere Installation folgen Sie bitte der Anleitung im Wiki.
9. Die wichtigsten vorinstallierten Pakete sind Web-, Datenbank- und LDAP-Server:
• Apache 2.4, Java 11, Tomcat 9
• MariaDB 10.6, libmariadb-java
• OpenLDAP (slapd, ldap-utils), phpldapadmin
10. Los geht's! Starten Sie die virtuelle Maschine in Virtualbox und melden Sie sich mit dem Passwort "shibboleth" an. Bitte arbeiten Sie möglichst präzise, um nachträgliche Fehlersuchen zu vermeiden. Achten Sie beim Bearbeiten von Konfigurationsdateien auf die Syntax (häufig xml).

JAVA vorbereiten

sudo su

# Datei: /etc/environment
JAVA_HOME="/usr/lib/jvm/java-11-openjdk-amd64/"

exit
sudo su

Korrektur phpLDAPadmin

$servers->setValue('server','host','127.0.0.2');

Vorbereitung der MySQL-Datenbank

zur Doku: Datenbank-Konfiguration

1. "StorageRecords" für die Speicherung von User Consent und Sessions
2. "shibpid" für die Speicherung von persistentIDs

mariadb -uroot -pshibboleth
SET NAMES 'utf8';
SET CHARACTER SET utf8;
CHARSET utf8;
CREATE DATABASE IF NOT EXISTS shibboleth CHARACTER SET=utf8;
USE shibboleth;

CREATE TABLE IF NOT EXISTS StorageRecords (
    context varchar(255) NOT NULL,
    id varchar(255) NOT NULL,
    expires bigint(20) DEFAULT NULL,
    value longtext NOT NULL,
    version bigint(20) NOT NULL,
  PRIMARY KEY (context, id)
) COLLATE utf8_bin;
 
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)
);
 
CREATE USER 'shibboleth'@'localhost' IDENTIFIED BY 'shibboleth'; 
GRANT ALL PRIVILEGES ON shibboleth.* TO 'shibboleth'@'localhost';
FLUSH PRIVILEGES;
exit;

Shibboleth-Installation

wget -P /opt/install https://shibboleth.net/downloads/identity-provider/archive/4.2.0/shibboleth-identity-provider-4.2.0.tar.gz
wget -P /opt/install https://shibboleth.net/downloads/identity-provider/archive/4.2.0/shibboleth-identity-provider-4.2.0.tar.gz.asc
wget -P /opt/install https://shibboleth.net/downloads/PGP_KEYS
tar -xzf /opt/install/shibboleth-identity-provider-4.2.0.tar.gz -C /opt/install/

/opt/install/shibboleth-identity-provider-4.2.0/bin/install.sh

Source (Distribution) Directory (press  to accept default): [/opt/install/shibboleth-identity-provider-4.2.0] ? 
Installation Directory: [/opt/shibboleth-idp] ? 
Host Name: [10.0.2.15] ? idp.local
### im Folgenden setzen Sie Passwörter, zu Testzwecken z.B. "shibboleth"
Backchannel PKCS12 Password:
Re-enter password: 
Cookie Encryption Key Password:
Re-enter password: 
SAML EntityID: [https://idp.local/idp/shibboleth] ? 
Attribute Scope: [local] ? 

Shibboleth-Konfiguration

Metadaten

zur Doku: Metadaten-Konfiguration

wget --no-check-certificate https://sp1.local/Shibboleth.sso/Metadata -O /opt/shibboleth-idp/metadata/sp1-metadata.xml
wget --no-check-certificate https://sp2.local/Shibboleth.sso/Metadata -O /opt/shibboleth-idp/metadata/sp2-metadata.xml

<!-- Datei: /opt/shibboleth-idp/conf/metadata-providers.xml -->
    <MetadataProvider id="SP1-Metadata"  xsi:type="FilesystemMetadataProvider" metadataFile="/opt/shibboleth-idp/metadata/sp1-metadata.xml"/>
    <MetadataProvider id="SP2-Metadata"  xsi:type="FilesystemMetadataProvider" metadataFile="/opt/shibboleth-idp/metadata/sp2-metadata.xml"/>

1. Die Datei enthält ein Ablaufdatum, das entfernt werden muss. Löschen Sie den String, z.B. validUntil="2022-01-17T09:59:23.071Z".

   <!-- Datei: /opt/shibboleth-idp/metadata/idp-metadata.xml -->
   <EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" 
       xmlns:shibmd="urn:mace:shibboleth:metadata:1.0" xmlns:xml="http://www.w3.org/XML/1998/namespace" xmlns:mdui="urn:oasis:names:tc:SAML:metadata:ui"
       xmlns:req-attr="urn:oasis:names:tc:SAML:protocol:ext:req-attr" entityID="https://idp.local/idp/shibboleth">
         

2. Weiter unten sehen Sie in den Zeilen 123-128 auskommentierte Endpunkte für Single Logout (SSO). Damit Single Logout in der VM funktioniert, entfernen Sie die Kommentarzeichen um die Zeilen 123-128. Sie müssen sowohl das den Kommentar einleitende "<!--" als auch das schließende "-->" entfernen.

   
   <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://idp.local/idp/profile/SAML2/POST/SLO"/>
   <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST-SimpleSign" Location="https://idp.local/idp/profile/SAML2/POST-SimpleSign/SLO"/>
   <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://idp.local/idp/profile/SAML2/Redirect/SLO"/>
   <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" Location="https://idp.local:8443/idp/profile/SAML2/SOAP/SLO"/>
         

LDAP-Anbindung

zur Doku: LDAP-/AD-Anbindung

# Datei: /opt/shibboleth-idp/conf/ldap.properties
idp.authn.LDAP.authenticator                   = bindSearchAuthenticator
idp.authn.LDAP.ldapURL                         = ldap://idp.local:389
idp.authn.LDAP.useStartTLS                     = false
# idp.authn.LDAP.trustCertificates                = %{idp.home}/credentials/ldap-server.crt
idp.authn.LDAP.baseDN                          = dc=users,dc=nodomain
idp.authn.LDAP.bindDN                          = cn=admin,dc=nodomain

root@ubuntu:~# ls -la /opt/shibboleth-idp/credentials/secrets.properties
-rw------- 1 tomcat tomcat 588 Okt  8 16:08 /opt/shibboleth-idp/credentials/secrets.properties

# Datei: /opt/shibboleth-idp/credentials/secrets.properties
idp.authn.LDAP.bindDNCredential                = shibboleth

Zugriff auf das Webinterface regeln

<!-- Datei: /opt/shibboleth-idp/conf/access-control.xml -->
  <util:map id="shibboleth.AccessControlPolicies">
    <entry key="AccessByIPAddress">
      <bean parent="shibboleth.IPRangeAccessControl" p:allowedRanges="#{ {'127.0.0.0/8', '::1/128'} }" />
    </entry>
  </util:map>

Konfiguration des Attribute Resolver

zur Doku: Attribut-Konfiguration

wget https://download.aai.dfn.de/ws/idp2022/idpv4-attribute-resolver.xml -O /opt/shibboleth-idp/conf/attribute-resolver.xml

Attribut-Definitionen

<!-- Datei: /opt/shibboleth-idp/conf/attribute-resolver.xml -->
    <AttributeDefinition xsi:type="Simple" id="organizationalUnit">
        <InputDataConnector ref="myLDAP" attributeNames="ou"/>
    </AttributeDefinition>

Data Connectors

1. einen LDAP-Connector,
2. einen Connector mit statisch definierten Attributen, hier z.B. mit dem hartkodierten Namen der Hochschule
3. einen Connector für die MySQL-Datenbank (mit den persistentIDs)

<!-- Datei: /opt/shibboleth-idp/conf/attribute-resolver.xml -->
    <DataConnector id="staticAttributes" xsi:type="Static">
        <Attribute id="o">
            <Value>Beispiel-Hochschule</Value>
        </Attribute>
    </DataConnector>

opt/shibboleth-idp/conf/attribute-resolver.xml -->
        <DataConnector id="myLDAP" xsi:type="LDAPDirectory"
        ...
        exportAttributes="uid givenName sn mail displayName">
        ...
    </DataConnector>

Transcoding-Regeln

1. Das mail-Attribut kann in SAML1 und SAML2 übergeben werden. SAML1 ist veraltet und in der DFN-AAI nicht mehr erforderlich. Sie können die Zeile <prop key="saml1.name">urn:mace:dir:attribute-def:mail</prop> daher auch getrost entfernen.
2. Das mail-Attribut wird - wie der Spezifikation vorgesehen - in SAML2 als urn:oid:0.9.2342.19200300.100.1.3 übergeben. Dies ist die Information, die SPs für die Zuordnung der Attribute benötigen.
3. Das mail-Attribut hat hier einen Anzeigenamen und eine Kurzbeschreibung in deutsch und englisch. Die Nutzer*innen bekommen dies zu sehen, wenn sie nach der Zustimmung zur Attributfreigabe gefragt werden.

<!-- Datei: /opt/shibboleth-idp/conf/attributes/inetOrgPerson.xml (gekürzt!) -->
        <bean parent="shibboleth.TranscodingProperties">
            <property name="properties">
                <props merge="true">
                    <prop key="id">mail</prop>
                    <prop key="transcoder">SAML2StringTranscoder SAML1StringTranscoder</prop>
                    <prop key="saml2.name">urn:oid:0.9.2342.19200300.100.1.3</prop>
                    <prop key="saml1.name">urn:mace:dir:attribute-def:mail</prop>
                    <prop key="displayName.en">E-mail</prop>
                    <prop key="displayName.de">E-Mail</prop>
                    <prop key="description.en">E-Mail: Preferred address for e-mail to be sent to this person</prop>
                    <prop key="description.de">E-Mail-Adresse</prop>
                </props>
            </property>
        </bean>

Konfiguration von SAML2-NameIDs

1. persistentIDs werden pro Useraccount und pro SP nach einem konfigurierbaren Schema generiert. Sie bleiben dann gleich, das heißt, SPs können anhand dieser Pseudonyme Accounts personalisieren, ohne Realnamen zu kennen. (Es sei denn, die werden auch übermittelt.)
2. transientIDs werden auch pro Useraccount und pro SP generiert. Sie ändern sich aber bei jedem Login.

# Datei: /opt/shibboleth-idp/conf/saml-nameid.properties
idp.persistentId.sourceAttribute = uid
idp.persistentId.generator = shibboleth.StoredPersistentIdGenerator
idp.persistentId.dataSource = shibboleth.MySQLDataSource

# Datei: /opt/shibboleth-idp/credentials/secrets.properties
idp.persistentId.salt = my-very-very-long-hash

<!-- Datei /opt/shibboleth-idp/conf/saml-nameid.xml -->
        <!-- Uncommenting this bean requires configuration in saml-nameid.properties. -->
        <ref bean="shibboleth.SAML2PersistentGenerator" />

<!-- Datei: /opt/shibboleth-idp/conf/c14n/subject-c14n.xml -->
<ref bean="c14n/SAML2Persistent" />

Konfiguration der Datenbank-Anbindung

<!-- Datei /opt/shibboleth-idp/conf/global.xml -->
        <bean id="shibboleth.MySQLDataSource"
              class="%{mysql.class}"
              p:driverClassName="org.mariadb.jdbc.Driver"
              p:url="%{mysql.url}"
              p:username="%{mysql.username}"
              p:password="%{mysql.password}"
              p:maxWait="15000"
              p:testOnBorrow="true"
              p:maxActive="100"
              p:maxIdle="100"
              p:validationQuery="select 1"
              p:validationQueryTimeout="5" />

        <bean id="shibboleth.JPAStorageService"
              class="org.opensaml.storage.impl.JPAStorageService"
              p:cleanupInterval="%{idp.storage.cleanupInterval:PT10M}"
              c:factory-ref="shibboleth.JPAStorageService.EntityManagerFactory" />

        <bean id="shibboleth.JPAStorageService.EntityManagerFactory"
              class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean">
            <property name="packagesToScan" value="org.opensaml.storage.impl"/>
            <property name="dataSource" ref="shibboleth.MySQLDataSource"/>
            <property name="jpaVendorAdapter" ref="shibboleth.JPAStorageService.JPAVendorAdapter"/>
            <property name="jpaDialect">
                <bean class="org.springframework.orm.jpa.vendor.HibernateJpaDialect" />
            </property>
        </bean>

        <bean id="shibboleth.JPAStorageService.JPAVendorAdapter"
              class="org.springframework.orm.jpa.vendor.HibernateJpaVendorAdapter"
              p:generateDdl="true"
              p:database="MYSQL"
              p:databasePlatform="org.hibernate.dialect.MySQL5Dialect" />

# Datei /opt/shibboleth-idp/conf/idp.properties
mysql.class    = org.apache.tomcat.jdbc.pool.DataSource
mysql.url      = jdbc:mysql://localhost:3306/shibboleth
mysql.username = shibboleth

# Datei /opt/shibboleth-idp/conf/idp.properties
idp.session.StorageService = shibboleth.JPAStorageService
idp.consent.StorageService = shibboleth.JPAStorageService
idp.consent.attribute-release.userStorageKey = shibboleth.consent.PrincipalConsentStorageKey
idp.consent.attribute-release.userStorageKeyAttribute = %{idp.persistentId.sourceAttribute}
idp.consent.terms-of-use.userStorageKey = shibboleth.consent.PrincipalConsentStorageKey
idp.consent.terms-of-use.userStorageKeyAttribute = %{idp.persistentId.sourceAttribute}
idp.consent.allowGlobal = false
idp.consent.compareValues = true

# Datei: /opt/shibboleth-idp/credentials/secrets.properties
mysql.password = shibboleth

Konfiguration von Attributfreigaben für die beiden lokalen Service Provider

<!-- Datei: /opt/shibboleth-idp/conf/attribute-filter.xml -->
    <!-- Release to local SPs (1. Schreibweise) -->
    <AttributeFilterPolicy id="SPs_locals">
        <PolicyRequirementRule xsi:type="OR">
            <Rule xsi:type="Requester" value="https://sp1.local/shibboleth" />
            <Rule xsi:type="Requester" value="https://sp2.local/shibboleth" />
        </PolicyRequirementRule>
        <AttributeRule attributeID="eduPersonScopedAffiliation" permitAny="true" />
        <AttributeRule attributeID="surname"                    permitAny="true" />
        <AttributeRule attributeID="givenName"                  permitAny="true" />
        <AttributeRule attributeID="mail"                       permitAny="true" />
        <AttributeRule attributeID="uid"                        permitAny="true" />
    </AttributeFilterPolicy>

<!-- Datei: /opt/shibboleth-idp/conf/attribute-filter.xml -->
    <!-- Release to local SPs (2. Schreibweise) -->
    <AttributeFilterPolicy id="SPs_locals">
        <PolicyRequirementRule xsi:type="OR">
            <Rule xsi:type="Requester" value="https://sp1.local/shibboleth" />
            <Rule xsi:type="Requester" value="https://sp2.local/shibboleth" />
        </PolicyRequirementRule>
        <AttributeRule attributeID="eduPersonScopedAffiliation">
            <PermitValueRule xsi:type="ANY" />
        </AttributeRule>
        <AttributeRule attributeID="surname">
            <PermitValueRule xsi:type="ANY" />
        </AttributeRule>
        <AttributeRule attributeID="givenName">
            <PermitValueRule xsi:type="ANY" />
        </AttributeRule>
        <AttributeRule attributeID="mail">
            <PermitValueRule xsi:type="ANY" />
        </AttributeRule>
        <AttributeRule attributeID="uid">
            <PermitValueRule xsi:type="ANY" />
        </AttributeRule>
    </AttributeFilterPolicy>

Anpassung von Dateirechten

# chown -R tomcat:tomcat /opt/shibboleth-idp/

Neustart von Diensten

# systemctl restart tomcat9.service

# tail -f /var/log/tomcat9/catalina.DATUM.log

# systemctl restart shibd.service

Prüfung des IdP-Status

• /var/log/tomcat9/catalina.DATUM.log
• /opt/shibboleth-idp/logs/idp-process.log

Erstes Login für SP1

username: professorin
password: shibboleth

Untersuchung der Installation

ls /opt/shibboleth-idp/metadata/
less /opt/shibboleth-idp/metadata/idp-metadata.xml
less /opt/shibboleth-idp/metadata/sp1-metadata.xml

mysql
use shibboleth;
select * from StorageRecords\G;
select * from shibpid\G;
exit;

Tipps und Tricks

Neuladen des Shibboleth-IdP

# touch /opt/shibboleth-idp/war/idp.war

# /opt/shibboleth-idp/bin/build.sh

• conf/logback.xml: 5min.
• conf/attribute-resolver.xml, conf/attribute-filter.xml uvm.: 15 min.

# Datei: /opt/shibboleth-idp/conf/services.properties
# Beispiele:
idp.service.logging.checkInterval = PT5M
idp.service.relyingparty.checkInterval = PT15M
idp.service.attribute.resolver.checkInterval = PT15M
idp.service.attribute.filter.checkInterval = PT15M

zur Doku: WebInterfaces

# Beispiele:
# attribute-resolver.xml neu laden
curl https://idp.local/idp/profile/admin/reload-service?id=shibboleth.AttributeResolverService
# attribute-filter.xml neu laden
curl https://idp.local/idp/profile/admin/reload-service?id=shibboleth.AttributeFilterService

Logging

zur Doku: Logging

• Tomcat: /var/log/tomcat9/catalina.DATUM.log
• logs/idp-process.log: alle Logmeldungen von Shibboleth, je nach Loglevel. Die folgenden drei Dateien sind Ausschnitte aus idp-process.log.
• logs/idp-audit.log: nur die Autorisierungen, inkl.übermittelte Attribute
• logs/idp-consent-audit.log: nur Akzeptieren der Nutzungsbedingungen und Attributfreigaben
• logs/idp-warn.log: nur Warnings und Errors

Handler

Identity Provider

Service Provider

• Metadata-Handler eines SP aufrufen: https://sp1.local/Shibboleth.sso/Metadata (im Browser öffnen, Seitenquelltext anzeigen)
• Session-Handler am SP aufrufen: https://sp1.local/Shibboleth.sso/Session
• Logout-Handler am SP aufrufen: https://sp1.local/Shibboleth.sso/Logout

Übungen

Übung 1: IdP-Module - Das User Consent-Modul

zur Doku: Logging

/opt/shibboleth-idp/bin/module.sh -e idp.intercept.Consent
Enabling idp.intercept.Consent...
        conf/intercept/consent-intercept-config.xml created
        views/intercept/attribute-release.vm created
        views/intercept/terms-of-use.vm created
[OK]

• Damit beim SAML2-Login die Zustimmungsseite zur Attributfreigabe angezeigt wird, editieren Sie /opt/shibboleth-idp/conf/relying-party.xml. Suchen Sie den Abschnitt shibboleth.DefaultRelyingParty und ergänzen Sie die bean-parent-Zeile wie folgt, damit beim Profil SAML2.SSO die Zustimmung eingeholt wird:

  <bean parent="SAML2.SSO" p:postAuthenticationFlows="#{{'attribute-release'}}" />

• Laden Sie das Servlet neu und melden Sie sich erneut für den SP1 an.
• Nach erfolgter Zustimmung zur Attibutfreigabe können Sie diese an zwei Stellen nachvollziehen:
  1. Die zuletzt erteilte Zustimmung liegt gehasht in der Datenbank-Tabelle StorageRecords.
  2. Jede erteilte Zustimmung wird außerdem ins Logfile /opt/shibboleth-idp/logs/idp-consent-audit.log geschrieben. Diese Logs sollten Sie aufgrund Ihrer Nachweispflicht dauerhaft wegsichern.

     2021-09-08T09:27:32.754811Z|https://sp1.local/shibboleth|AttributeReleaseConsent|professorin|eduPersonScopedAffiliation|0zLr0bShf2da65PDb/LKkNqM6tpt/cHG7wEScjDkmkw=|true

/opt/shibboleth-idp# bin/module.sh --disable idp.intercept.Consent
Disabling idp.intercept.Consent...
        conf/intercept/consent-intercept-config.xml renamed to conf/intercept/consent-intercept-config.xml.idpsave
        views/intercept/attribute-release.vm removed
        views/intercept/terms-of-use.vm removed
[OK]

Übung 2: Shibboleth-Update

$ curl -s -k https://idp.local/idp/status | grep ^idp_version

# /opt/shibboleth-idp/bin/version.sh

zur Doku: Shibboleth 4.x-Updates

Übung 3

Übung 4

Übung 5

Übung 6

# idp-audit.log (hier umgebrochen)
2020-10-27 14:29:06,676 - 127.0.0.2 - INFO [Shibboleth-Audit.SSO:282] - 127.0.0.2|2020-10-27T13:28:44.440493Z|
2020-10-27T13:29:06.676590Z|professorin|https://sp1.local/shibboleth|_980e6bf465fc4b22c3383ff9499f283a|password|2020-10-27T13:28:56.165603Z|
eduPersonScopedAffiliation|NMTR6SVZOCUWF5MNGDDIYQQBY4QCB76N|persistent|false|false|AES128-GCM|Redirect|POST||
Success||72d4bb621cfde876e106a9fe42369241e253b14d0b300497fbf32c8d8ace8576|
Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:82.0) Gecko/20100101 Firefox/82.0

Übung 7

Übung 8

Übung 9

• eduPersonUniqueId
• samlSubjectID
• samlPairwiseID

• eduPersonUniqueId, samlSubjectID
• samlPairwiseID, persistentID (SAML2 Name ID)

Lösungen zeigen