### Operating Environment Information
operating_system: Linux
operating_system_version: 5.4.0-64-generic
[...]
### Identity Provider Information
idp_version: 4.0.1
Der IdP loggt nach ''/opt/shibboleth-idp/logs/''. In ''idp-process.log'' finden Sie u.a. die SAML-Assertions, der der IdP herausschickt.
===== Installation des Shibboleth SP =====
sudo su
Die Schweizer Föderation bietet ein Debian-Paket an, das dann die eigentliche Paketquelle in APT hinzufügt.
# Apt-Source als eigenes Paket herunterladen...
wget https://pkg.switch.ch/switchaai/ubuntu/dists/focal/main/binary-all/misc/switchaai-apt-source_1.0.0~ubuntu20.04.1_all.deb -O /root/switchaai-apt-source_1.0.0~ubuntu20.04.1_all.deb
# ... und installieren
dpkg -i /root/switchaai-apt-source_1.0.0~ubuntu20.04.1_all.deb
# ... prüfen
cat /etc/apt/sources.list.d/SWITCHaai-swdistrib.list
apt update
apt install -y --install-recommends shibboleth
# Sicherstellen, dass keine veralteten, inzwischen umbenannten, Shib SP-Pakete mehr installiert sind:
apt autoremove
===== Untersuchung der SP-Installation I =====
* User und Gruppe ''_shibd''
* In der Schulungs-VM ist der ''_shibd'' zudem in der Gruppe ''ssl-cert'' und darf daher private Schlüssel im Verzeichnis ''/etc/ssl/private'' lesen.
* Das Verzeichnis ''/etc/shibboleth'' enthält die Konfigurationsdateien.
* Ins Verzeichnis ''/var/log/shibboleth'' werden die Logs geschrieben.
* Im Verzeichnis ''/run/shibboleth'' werden PID- und Socket-Dateien abgelegt.
* In ''/var/cache/shibboleth'' werden die heruntergeladenen Metadaten gecached.
===== Hauptkonfigurationsdatei /etc/shibboleth/shibboleth2.xml =====
[[https://wiki.shibboleth.net/confluence/display/SP3/SPConfig | Dokumentation im Shibboleth-Wiki: shibboleth2.xml]]
Die zentrale Konfigurationsdatei des Shibboleth SP heißt ''/etc/shibboleth/shibboleth2.xml''. Laden Sie sich folgende Beispieldatei zum Start herunter:wget https://download.aai.dfn.de/ws/2021/sp-schulung/shibboleth2.xml -O /etc/shibboleth/shibboleth2.xml
Schauen Sie in die Datei: Für eine einfache, funktionierende Konfiguration sind nur wenige Stellen zu ändern. **Dies ist hier bereits geschehen.** In Ihrer eigenen Installation müssen Sie darauf achten, die SWITCHaai-spezifischen URLs und Zertifikate für die DFN-AAI anzupassen.
==== EntityID und User Identifier ====
Hier sind die EntityID, eine Home-URL (hier: der Session Handler) des SPs, sowie der/die Identifier (Details s.u.) eingestellt:
Die Session-Einstellungen bleiben auf den Standardeinstellungen.
==== Discovery Service ====
Danach finden Sie die Konfiguration des Discovery Service: Innerhalb der VM werden die SPs direkt mit dem lokal laufenden IdP verbandelt:
SAML2
Darunter ist ein auskommentiertes Beispiel für die Einbindung eines Discovery Service zur Einrichtungsauswahl, nämlich unseres öffentlichen WAYFs für die DFN-AAI-Test.
==== IdP-Metadaten ====
Ähnlich ist es bei den einzulesenden Metadaten: In der VM nutzen wir den Metadatensatz des lokalen IdP statt - wie sonst - die Föderationsmetadaten:
==== Attribut-Verarbeitung am SP ====
Das ''
==== Erweiterte Konfiguration ====
Vor dem schließenden ''''-Element steht ein Kommentar für ApplicationOverrides. Hier werden Abweichungen definiert, z.B. für einen zweiten SP (siehe unten).
==== shibd startklar machen ===
Bitte löschen Sie die mitgelieferten Beispieldateien ''/etc/shibboleth/example-metadata.xml'' und ''/etc/shibboleth/example-shibboleth2.xml'' und starten Sie den SP neu:
root@sp:~ # rm /etc/shibboleth/example-*.xml
root@sp:~ # systemctl restart shibd.service
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
==== Der User-Identifier: REMOTE_USER ====
Über die Variable REMOTE_USER wird in ''/etc/shibboleth/shibboleth2.xml'' der primäre Identifier der Browser-Nutzer*innen übergeben. Jedes in ''attribute-map.xml'' (s.u.) genannte Attribute kann als Quelle angegeben werden. Dazu wird die ''id'' referenziert, die in der Attribute Map steht. Bei Mehrfachnennung (mit Leerzeichen getrennt) wird das erste mit Werten befüllte Attribut verwendet.
Bei der **Wahl des Identifiers** für Nutzer*innen sollten verschiedene Punkte bedacht werden:
* Der Attributwert sollte (idealerweise global) eindeutig sein. ''uid'' oder ''sAMAccountName'' können z.B. dieselben Werte annehmen, wenn der SP mit mehreren Hochschulen zusammenarbeitet.
* Der Attributwert sollte für dieselbe Person permanent gleich bleiben.
* Über die Zeit sollte derselbe Wert nicht für andere Nutzer*innen übermittelt werden.
* Das Attribut sollte nur //einen// Wert liefern. ''mail'' eignet sich deshalb nicht.
* **Aus Datenschutzsicht ist ein Identifier zu bevorzugen, der kein SP-übergreifendes User-Tracking erlaubt** wie z.B. ''SAML Pairwise ID'' oder ''persistentID'' (beide pseudonym und targeted, also pro User*in //pro SP// generiert und persistiert).
* ''SAML Subject ID'' und''eduPersonUniqueID'' sind zwar pseudonym, werden aber nicht pro SP generiert. Daher ist ein SP-übergreifendes User-Tracking möglich (was ja in bestimmten Fällen auch erwünscht sein kann). ''eduPersonPrincipalName'' ist in sehr vielen Fällen nicht pseudonym, sondern basiert auf Namen oder uids. Daher geht der Trend weg von der Nutzung des ''eduPersonPrincipalName'' als User Identifier.
==== attribute-map.xml ====
Alle Attribute, die der SP entgegennehmen soll, müssen in ''/etc/shibboleth/attribute-map.xml'' aufgeführt sein. Einige gängige Attribute sind in der Datei bereits als SAML 1.1- und SAML 2.0-Attribute aufgelistet. Dabei gilt für die SAML 2.0-Attribute:
* ''name'' ist jeweils die URN, die vom IdP übermittelt wird.
* ''id'' ist der BEzeichner, über den das Attribut SP-intern bekannt gemacht wird.
* Weitere Angaben definieren ggf., wie das Attribute dekodiert wird, ob Groß-/Kleinschreibung berücksichtigt werden muss. Hier ein paar Beispiele (nur SAML 2.0):
==== Konformitätsprüfung eingehender Attributwerte ====
Die Datei ''/etc/shibboleth/attribute-policy.xml'' enthält einige Regeln, anhand derer der SP prüft, ob die vom IdP übermittelten Attributwert zulässig sind. Dort ist z.B. die Liste der acht möglichen Werte von ''eduPersonAffiliation'' hinterlegt:
===== Apache Webserver mit mod_shib =====
[[https://wiki.shibboleth.net/confluence/display/SP3/Apache | Zur Doku im Shibboleth-Wiki: Apache]]
Mit dem Debian-Paket für den Shibboleth SP wurde u.a. ein Modul für den Apache Webserver mitinstalliert: Das Paket heißt ''libapache2-mod-shib'' und das Modul ist im Apache als ''mod_shib'' ladbar. Mit diesem Modul ist es möglich, direkt in der Konfiguration eines virtuellen Hosts Zugriffsbeschränkungen anzugeben. Dies ist die einfachste Möglichkeit, eine Ressource mit WebSSO zu schützen. Das Modul bringt diverse Dateien mit, hier die wichtigsten: root@sp:~# dpkg -L libapache2-mod-shib
# [AUSZUG!]
/etc/apache2/conf-available/shib.conf
/etc/apache2/mods-available/shib.load
/usr/lib/apache2/modules/mod_shib.so
Das shib-Modul sollte bei der Installation automatisch geladen werden. Prüfen Sie dies:root@sp:~# apache2ctl -M | grep shib
mod_shib (shared)
# bei Bedarf laden Sie das Modul selbst nach:
root@sp:~# a2enmod shib
root@sp:~# cat /etc/apache2/mods-enabled/shib.load
# Inhalt:
LoadModule mod_shib /usr/lib/apache2/modules/mod_shib.so
root@sp:~# cat /etc/apache2/conf-enabled/shib.conf
# Turn this on to support "require valid-user" rules from other
# mod_authn_* modules, and use "require shib-session" for anonymous
# session-based authorization in mod_shib.
ShibCompatValidUser Off
# Ensures handler will be accessible.
AuthType None
Require all granted
# Used for example style sheet in error templates.
AuthType None
Require all granted
Alias /shibboleth-sp/main.css /usr/share/shibboleth/main.css
AuthType shibboleth
ShibRequestSetting requireSession 1
Require valid-user
Ein anderes Beispiel aus der Dokumentation: So können Sie eine globale Regel für einen Server oder VHost erstellen. Das Modul ist dann grundsätzlich aktiv, blockiert aber keine Zugriffe. ''Require shibboleth'' bewirkt dies. Unterhalb des Gültigkeitsbereiches können Sie dann ausdifferenzieren.
AuthType shibboleth
Require shibboleth
Anders herum: Wenn Sie eine ''
AuthType Shibboleth
ShibRequestSetting requireSession false
Require shibboleth
**Um bestimmte Attribute auszuwerten, verwenden Sie ''Require shib-attr'', gefolgt von dem Attribut und den zulässigen Werten oder einer regular expression.** Alle in ''/etc/shibboleth/attribute-map.xml'' definierten Attribut-IDs können hier verwendet werden.
AuthType shibboleth
ShibRequestSetting requireSession true
Require shib-attr affiliation staff@local employee@local
Require shib-attr o Beispiel-Hochschule
root@sp~: shibd -t
So finden Sie eventuelle Fehler in der Konfiguration des Apache Webservers:
root@sp~: apache2ctl -t
==== Logging ====
Die relevanten Meldungen des shibd, also Probleme, die mit SAML, Metadaten oder Sicherheit zu tun haben, landen im shibd.log unter ''/var/log/shibboleth/shibd.log''. Das Loglevel wird in ''/etc/shibboleth/shibd.logger'' konfiguriert, am einfachsten global ganz oben in der Datei ([[https://wiki.shibboleth.net/confluence/display/SP3/Logging | Dokumentation im Shibboleth-Wiki]]).
Im Transaction-Log (''/var/log/shibboleth/transaction.log'') finden Sie nur die eigentlichen Transaktion, die am SP eingehen:
root@sp:~# tail -f /var/log/shibboleth/shibd.log /var/log/shibboleth/transaction.log
Setzen Sie das Loglevel des ''shibd'' auf DEBUG.
root@sp:~# systemctl restart shibd.service
==== 2. Auffüllen der Attribute Map ====
.
==== 3. Location schützen ====
root@sp:~# systemctl reload apache2.service
Loggen Sie sich im Browser der VM am SP1 ein, z.B. mit dem Account "professorin" (Passwort: shibboleth). Beobachten Sie die Logdateien:
Im ''shibd.log'' sehen Sie zuerst den Authentication Request an ''idp.local''. Weiter unten sehen Sie nach dem Login die am SP eingegangene SAML-Assertion:2021-02-03 16:55:27 DEBUG Shibboleth.SSO.SAML2 [3] [default]: decrypted Assertion: https://idp.local/idp/shibboleth https://sp1.local/shibboleth urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport urn:mace:dir:entitlement:common-lib-terms member@local
Hier sind v.a. die Attribute und Attributwerte interessant:
* Für ''eduPersonEntitlement'' wurde (gemäß der Filterregeln im IdP) der Wert ''urn:mace:dir:entitlement:common-lib-terms'' übertragen.
* Für ''eduPersonScopedAffiliation'' kam der Wert ''member@local''.
Danach sehen Sie, dass der ''shibd'' die Attribute gemäß seiner Attribute Map von URNs in Attribute umwandelt:2021-02-03 16:55:27 DEBUG Shibboleth.AttributeDecoder.String [3] [default]: decoding SimpleAttribute (entitlement) from SAML 2 Attribute (urn:oid:1.3.6.1.4.1.5923.1.1.1.7) with 1 value(s)
2021-02-03 16:55:27 DEBUG Shibboleth.AttributeDecoder.Scoped [3] [default]: decoding ScopedAttribute (affiliation) from SAML 2 Attribute (urn:oid:1.3.6.1.4.1.5923.1.1.1.9) with 1 value(s)
2021-02-03 16:55:27 DEBUG Shibboleth.AttributeFilter [3] [default]: filtering 2 attribute(s) from (https://idp.local/idp/shibboleth)
2021-02-03 16:55:27 DEBUG Shibboleth.AttributeFilter [3] [default]: applying filtering rule(s) for attribute (affiliation) from (https://idp.local/idp/shibboleth)
2021-02-03 16:55:27 DEBUG Shibboleth.AttributeFilter [3] [default]: applying filtering rule(s) for attribute (entitlement) from (https://idp.local/idp/shibboleth)
Rufen Sie im Browser das Lesezeichen "SP1 Session Handler" auf. Hier können Sie jetzt Informationen über die SP-Session einsehen, inklusive der Attributwerte.
Schließen Sie den Browser in der VM, öffnen Sie ihn erneut und melden Sie sich mit dem Useraccount "extern" an. Vergleichen Sie den Session Handler: Hier wurden keine Attribute übermittelt, es existiert nur die Session. In diesem Fall reicht das trotzdem zur Autorisierung.
==== 4. Locations mit unterschiedlichen Regeln ====
# IdP-Session reicht, um https://sp1.local aufzurufen.
AuthType shibboleth
ShibRequestSetting requireSession 1
Require valid-user
# Die Location https://sp1.local/members-only nur mit der Affiliation member aufgerufen werden.
AuthType shibboleth
ShibRequestSetting requireSession 1
Require shib-attr affiliation member@local
# Die Location https://sp1.local/library darf nur mit dem Entitlement für Bibliotheksbenutzung besucht werden.
AuthType shibboleth
ShibRequestSetting requireSession 1
Require shib-attr entitlement urn:mace:dir:entitlement:common-lib-terms
Laden Sie den Apache neu und testen Sie: In der Lesenzeichenleiste finden Sie die beiden Locations im Ordner "SP1". Der Account "extern" darf auf ''https://sp1.local'' zugreifen, aber nicht auf ''https://sp1.local/members-only'' und ''https://sp1.local/library''. Der Webserver gibt bei den beiden einen Fehler "401 Unauthorized" zurück. Gegenprobe. Der Account "professorin" darf auf die beiden neuen Locations zugreifen.
==== 5. Zweiten VHost schützen ====
Sie konfigurieren damit eine zusätzliche "Application" mit der ID "sp2", einer eigenen EntityID, einem eigenen Handler und Zertifikat.
Speichern Sie die Datei und starten Sie den ''shibd'' neu:root@sp:~ # systemctl restart shibd.service
Editieren Sie den dazugehörigen Apache-VHost ''/etc/apache2/sites-enabled/sp2.conf'' und fügen Sie in das ''
AuthType shibboleth
# Hier geben Sie die oben gesetzte ID des 2. SP an:
ShibRequestSetting applicationId sp2
ShibRequestSetting requireSession 1
Require shib-attr affiliation staff@local employee@local faculty@local
Require shib-attr entitlement https://sp2.local/entitlement/politologie
Speichern Sie die Datei und laden Sie den Apache neu:root@sp:~ # systemctl reload apache2.service
Der einzige Account, der sich jetzt am SP2 anmelden kann, ist "professorin".
==== 6. REMOTE_USER an Tomcat übergeben ====
Die nachfolgende Anleitung basiert auf der offiziellen Dokumentation unter
''https://wiki.shibboleth.net/confluence/display/SP3/JavaHowTo''
und nimmt hierzu einige Ergänzungen vor.
=== Systemaufbau ===
Für dieses Szenario wird ein Apache Webserver mit einem shibd als Reverse Proxy zu einem Tomcat Webserver verwendet. Die Kommunikation zwischen dem Apache und Tomcat erfolgt über AJP (Apache JServ Protocol). Da hierbei der Tomcat die Authentifizierungsverantwortung an den Apache abgibt, sollte bereits auf Netzwerkebene sichergestellt werden, dass ein direkter Zugriff auf den Tomcat nur von dem Apache Webserver möglich ist. Das einfachste Setup besteht aus einem Apache- und einer Tomcat-Instanz gemeinsam auf einem Server. Dabei wird der Connector für den Tomcat AJP nur an localhost gebunden.
=== Konfiguration Shibboleth Service Provider ===
Möchte man nur den Username des angemeldeten Benutzers an einen Tomcat übergeben, so reicht es, in der ''shibboleth2.xml'' in dem Element ''
Starten Sie wieder den shibd neu:root@sp:~# systemctl restart shibd.service
=== Konfiguration Tomcat ===
Damit der Tomcat die Authentifizierungsverantwortung abgibt, muss im Connector für AJP das Attribut ''tomcatAuthentication="false"'' gesetzt werden.
Ab der Tomcat Version 8.5 müssen die zusätzlichen Attribute, die man an einen Tomcat aus dem Apache Shibboleth Environment weitergeben möchte, explizit angegeben werden. Hierfür muss im Connector für AJP im Attribut ''allowedRequestAttributesPattern'' ein regulärer Ausdruck angegeben werden, der die gewünschten Attributnamen abdeckt. ''allowedRequestAttributesPattern=".*"'' erlaubt alles, sollte aber aus Sicherheitsgründen nur für Tests angewendet werden.
Es kann vorkommen, dass die Standard packetSize mit 8192 Bytes für die Gesamtmenge an zu übertragenden Environment-Daten nicht ausreicht. In diesem Fall kann das Attribut mit ''packetSize="65536"'' auf das Maximum im Connector für AJP gesetzt werden.
Die offizielle Dokumentation zum Connector für AJP finden Sie unter:
https://tomcat.apache.org/tomcat-9.0-doc/config/ajp.html
In der Schulungs-VM führen Sie bitte folgende Kommandos aus, um den Connector für AJP gemäß den zuvor genannten Ausführungen anzupassen und eine Testseite anzulegen:root@sp:~# systemctl restart tomcat9.service
Die Mini-Anwendung, die Ihnen die übergebenen Attribute anzeigt, ist bereits vorbereitet:REMOTE_USER: <%= request.getRemoteUser() %>
givenName: <%= request.getAttribute("givenName") %>
sn: <%= request.getAttribute("sn") %>
mail: <%= request.getAttribute("mail") %>
entitlement: <%= request.getAttribute("entitlement") %>
affiliation: <%= request.getAttribute("affiliation") %>
persistent-id: <%= request.getAttribute("persistent-id") %>
Shib-Application-ID: <%= request.getAttribute("Shib-Application-ID") %>
Shib-Session-ID: <%= request.getAttribute("Shib-Session-ID") %>
Shib-Identity-Provider: <%= request.getAttribute("Shib-Identity-Provider") %>
Shib-Authentication-Instant: <%= request.getAttribute("Shib-Authentication-Instant") %>
Shib-Authentication-Method: <%= request.getAttribute("Shib-Authentication-Method") %>
Shib-AuthnContext-Class: <%= request.getAttribute("Shib-AuthnContext-Class") %>
Shib-AuthnContext-Decl: <%= request.getAttribute("Shib-AuthnContext-Decl") %>
Shib-Handler: <%= request.getAttribute("Shib-Handler") %>
root@sp:~# a2enmod proxy
root@sp:~# a2enmod proxy_ajp
2. testapp vom Tomcat in der VHost-Konfiguration von sp2 einbinden:
root@sp:~# systemctl reload apache2.service
4. Überprüfen des Konfigurationserfolgs
Rufen Sie https://sp2.local/testapp/ auf und Sie sollten die Attribute aus Ihrer index.jsp sehen.
Alternativ zu mod_proxy_ajp kann auch mod_jk verwendet werden. Siehe hierzu:
http://tomcat.apache.org/connectors-doc/\\ \\
=== Problem mehrerer Sessions / Session Cookies ===
Wenn nach einer erfolgreichen Authentifizierung am Shibboleth Service Provider in einer Java Webanwendung im Tomcat eine weitere Session anhand des REMOTE_USER initiert wird, entsteht mindestens ein weiteres Session Cookie. Hiermit kann eine personalisierte Session und Contexte verbunden sein. Bei einem Logout oder anderen Vorgängen werden die Informationen unter Umständen nicht vollständig invalidiert. Wenn sich an einem Browser dann nachfolgend ein anderer Nutzer anmeldet, können problematische Personalisierungs- und Rechtesituationen entstehen. Dies sollte in jedem Fall geprüft werden. Man kann z.B. den REMOTE_USER oder die Shib-Session-ID in alle zugehörigen Session- und Contextcontainer hineinschreiben. Bei jedem Request kann man dann mit einem Servlet Filter prüfen, ob übermittelter REMOTE_USER/Shib-Session-ID mit den Werten in den Containern übereinstimmen und bei negativen Ergebnis alles invalidieren.
==== 7. Showcase Moodle-Anbindung ====
AuthType shibboleth
ShibRequestSetting requireSession 1
Require shib-attr affiliation student@local
* der Einfachheit halber eigene ''shibboleth2.xml'' (nicht dieselbe wie in den obigen Übungen) mit REMOTE_USER eduPersonUniqueId und ohne ApplicationOverrides