SAML 2.0 Föderationen

Diese Software kann als zentrale Authentifizierungsstelle (Identity Provider, IdP) und als Dienstanbieter (Service Provider, SP) in eine SAML-2.0-basierte Identity Federation eingebunden werden. Es werden das SAML 2.0 Web Browser SSO Profile (Ausnahme: Artifact Binding) sowie das Enhanced Client and Proxy (ECP) Profile unterstützt.

Bei der Integration dieser Software als IdP können die in der Nutzerverwaltung gepflegten Nutzer mittels SSO-Service-Schnittstelle authentifiziert und entsprechende SAML-2.0-Assertions ausgestellt werden. Die Assertions können ausgewählte Nutzerattribute (z.B. Nutzername) oder Nutzerrollen enthalten, um den Nutzer gegenüber anderen Service Providern der Föderation auszuweisen und ggf. föderierte Identitäten herzustellen.

Wird diese Software als Service Provider eingebunden, können als geschützte Ressourcen abgesicherte Dienste sowie beliebige Java Web Applikationen in der Föderation bereitgestellt werden.

Verwendung als Identity Provider (IdP)

Diese Software kann als Identity Provider in einer SAML-2.0-Föderation eingesetzt werden. Die eigenen Nutzer können sich beim security.manager zentral authentifizieren und Dienste von externen zur Föderation gehörenden Service Providern nutzen oder – je nach vom Service Provider bereitgestellter Funktion – beispielsweise lokal beim Service Provider vorliegende Nutzerkonten mit dem zentralen Account "föderieren".

Gelangt ein Nutzer zum IdP (entweder direkt von einer Client-Anwendung oder durch ein Redirect vom Service Provider), können folgende Situationen entstehen:

Der Nutzer ist bereits angemeldet und hat einen Sicherheitskontext mit dem IdP (eine SSO-Session).
Der Nutzer ist noch nicht angemeldet.

Im ersten Fall wird für den Nutzer eine SAML-Assertion ausgestellt und an den SP weitergeleitet.

Im zweiten Fall wird der Nutzer auf die Login-Seite weitergeleitet, um eine Anmeldung durchzuführen. Bei erfolgreichem Login findet eine Weiterleitung inkl. SAML-Assertion mit den vereinbarten Nutzerattributen an den Service Provider statt. Außerdem wird eine neue SSO-Session erzeugt, so dass der Nutzer für die Dauer der Session beim IdP eingeloggt bleibt.

IdP-Metadaten

Um den security.manager als Identity Provider in eine Föderation zu integrieren, müssen folgende Schritte bzgl. der lokalen IdP-Metadaten durchgeführt werden:

Lokale IdP-Metadaten anpassen
1. URLs der SAML-2.0-Endpunkte an die Installation anpassen
2. In der Installation verwendetes Zertifikat eintragen
IdP-Metadaten und SP-Metadaten lokal registrieren
IdP-Metadaten bei Teilnehmern der Föderation registrieren

Im Abschnitt Metadaten-Konfiguration werden die einzelnen Schritte genauer erläutert.

Verwendung als Service Provider (SP)

Bei einem Einsatz als Service Provider eingesetzt in einer SAML-2.0-Föderation wird der Sicherheitskontext mit dem Client (meist der Browser oder eine ECP-fähige Komponente) über den SSO Domain Cookie Mechanismus (SSO-Session) hergestellt. Dabei gibt es zwei unterschiedliche Ausgangssituationen, wenn ein Client auf eine SSO-Session-geschützte Ressource zugreift:

Der Client besitzt bereits eine gültige SSO-Session, z.B. durch ein vorhergegangenes Login an einer der security.manager-Komponenten (z.B. der Administrationsoberfläche).
Der Client besitzt keine gültige SSO-Session.

Im ersten Fall findete keine weitere SAML-2.0-basierte Kommunikation statt, da der Client bereits einen gültigen Sicherheitskontext besitzt.

Im zweiten Fall wird je nach Client (Browser oder ECP-Client) der entsprechende SAML-2.0-Workflow initiiert und auf die Login-Seite umgeleitet. Hier kann der Nutzer eine lokale Anmeldung durchführen oder aus einer Liste der in der Föderation verfügbaren IdPs auswählen, um beim ausgewählten IdP eine zentrale Authentifizierung durchzuführen. Über die dort ausgestellte Assertion wird dann ein Sicherheitskontext (die SSO-Session) aufgebaut und im Erfolgsfall zur initial aufgerufenen Ressource umgeleitet.

Übersetzen der Nutzerattribute

Meldet sich der Nutzer an einem zentralen IdP an, liest der security.manager beim Erstellen des Sicherheitskontextes die Nutzerattribute aus der SAML-Assertion des IdP aus und "übersetzt" diese anhand einer konfigurierbaren Mapping-Tabelle in das lokale Nutzermodell. Das so erstellte Nutzer-Objekt wird unter einem vom IdP vergebenen Pseudonym in der Nutzerdatenbank des security.manager gespeichert.

SP-Metadaten

Um den security.manager als Service Provider in eine Föderation zu integrieren, müssen folgende Schritte bzgl. der lokalen SP-Metadaten durchgeführt werden:

Lokale SP-Metadaten anpassen
1. URLs der SAML-2.0-Endpunkte an die Installation anpassen
2. In der Installation verwendetes Zertifikat eintragen
SP-Metadaten und IdP-Metadaten lokal registrieren
SP-Metadaten bei Teilnehmern der Föderation registrieren

Im Abschnitt Metadaten-Konfiguration werden die einzelnen Schritte genauer erläutert.

Nutzerattribut-Mapping

Informationen eines bei einem zentralen IdP eingeloggten Nutzers, die als Attribute Statements mit einer SAML-2.0-Assertion zum SP gelangen, müssen in das interne Nutzerdatenmodell übersetzt werden. Dazu ist in [INSTALL_FOLDER]/webapp/administration/WEB-INF/classes/saml2/spring-saml2-config.xml ein Attribut-Mapping definiert, das ggf. an die tatsächlich vom IdP (oder den IdPs) gelieferten Attribute angepasst werden muss.

Die Property mit dem Namen sourceNameToTargetName legt fest, welche Attribute aus den Attribute Statements die Basis-Nutzerinformationen beinhalten. Im u.g. Beispiel wird das Attribut sn einer Assertion immer auf das Nutzerattribut familyname abgebildet, so dass der Nutzer in der Nutzerverwaltung des security.manager den entsprechenden Wert von sn als Nachname aufweist.

Der roleMapper legt fest, welche Attribute als security.manager Rollen interpretiert werden sollen. Im Beispiel unten sind das alle Attribute mit dem Namen isMemberOf. Dabei wird nicht der komplette Attributwert als Rollenname interpretiert, sondern nur der mittels valueFilterPattern als erste Gruppe markierte Teil des angegebenen regulären Ausdrucks.

Einem Nutzer werden nur die Rollen zugewiesen, die durch den Administrator ebenfalls im security.manager angelegt worden sind.

Mit einem speziellen Role Mapper ist es möglich, den Wert eines einzelnen Attributs auf mehrere Rollen abzubilden. Wenn z.B. das Attribut multirole den Wert Administrator hat, werden im Beispiel dem Nutzer die Rollen sM_Administrator und tc_Administrator zugewiesen. Um dieses Attribut-Mapping zu aktivieren, muss der entsprechende Teil in der XML-Datei einkommentiert werden.

Beispiel eines Attribut-Mappings

<bean id="saml2AssertionAttributeMapper" class="org.n52.security.authentication.saml2.ConfigurableAssertionAttributeMapper">
    <property name="sourceNameToTargetName">
        <map>
            <entry key="sn" value="familyname" />
            <entry key="givenName" value="givenname" />
            <entry key="mail" value="mail" />
            <entry key="gender" value="gender" />
            <entry key="phonenumber" value="phonenumber" />
            <entry key="city" value="city" />
            <entry key="street" value="street" />
            <entry key="country" value="country" />
        </map>
    </property>
    <property name="roleMapper">
        <list>
            <bean class="org.n52.security.authentication.saml2.ConfigurableAssertionAttributeMapper.NameRoleAttributeMapper">
                <property name="roleAttributeName" value="isMemberOf" />
                    <!--
                    value pattern filters a value like 'cn=Users,ou=groups,dc=opensso,dc=java,dc=net' to 'Users'
                    -->
                <property name="valueFilterPattern" value="^cn=([^,]+),.*" />
            </bean>
            <!-- <bean class="org.n52.security.authentication.saml2.ConfigurableAssertionAttributeMapper.NameValueRoleAttributeMapper">
            <property name="roleAttributeName" value="multirole" />
            <property name="sourceValueToRoles">
            <map>
            <entry key="Administrator">
            <list>
            <value>sM_Administrator</value>
            <value>tc_Administrator</value>
            </list>
            </entry>
            </map>
            </property>
            </bean> -->
        </list>
    </property>
    <!--<property name="userIdMapper"></property> -->
</bean>

Alle Nutzer, die mittels eines zentralen IdP authentifiziert wurden, werden einer Gruppe zugeordnet, deren Name der issuerId der SAML-Assertion entspricht. Ist diese noch nicht angelegt, wird sie erstellt.

Geschützte Ressourcen des SP

Maßgeblich für den Zugriff auf geschützte Ressourcen ist, dass es einen "Sicherheitskontext" zwischen Client und security.manager-Komponente, z.B. einem geschützten Dienst, gibt. Dieser kann zustande kommen, indem beispielsweise eine SSO-Session durch ein lokales Login erzeugt wird – oder aber durch eine SAML-2.0-basierte Anmeldung bei einem zentralen IdP, wodurch wiederum eine SSO-Session erzeugt wird. Das bedeutet, dass jeweils auf die SSO-Endpunkte von abgesicherten Ressourcen zugegriffen werden muss, um einen solchen Sicherheitskontext zu nutzen.

Bei geschützten Diensten ist dies üblicherweise der mit /sso gekennzeichnete Endpunkt, z.B.

http://maps.example.org/wss/services/MyWMS/sso?SERVICE=WMS&REQUEST=GetCapabilities

Bei allgemeinen Web Applikationen, die mittels des Domain Cookie Mechanismus abgesichert werden, ergibt sich der Endpunkt aus der Konfiguration der abgesicherten Applikationspfad.

Unmittelbare Weiterleitung an einen IdP

In manchen Fällen ist es gewünscht, dass beim erstmaligen Zugriff auf eine geschützte Ressource des Clients nicht auf die security.manager Anmeldeseite umgeleitet wird, sondern direkt zu einem bestimmten (externen) IdP. Dazu muss die der Parameter security.login.service.url in der Datei [INSTALL_FOLDER]/webapp/wss/WEB-INF/classes/application.properties so angepasst werden, dass er folgenden Wert besitzt: <your host>/administration/saml2/init?idpEntityId=<entity Id of the external idp>

Direkte Umleitung an den IdP mit der Entity ID 'testIdp'

security.login.service.url=http://host.example.com/administration/saml2/init?idpEntityId=testIdp

Metadaten-Konfiguration

Lokale Metadaten anpassen

Die lokalen SP- und IdP-Metadaten werden über das entsprechende Template unter [INSTALL_FOLDER]/webapp/administration/WEB-INF/classes/saml2/metadata/local-[sp|idp]-metadata.xml angepasst. Erstellen Sie vorab eine Sicherheitskopie der Datei.

Service URLs

Die Templates enthalten im Auslieferungszustand Referenzen auf die URL https://localhost:8443/secman/… Diese müssen entsprechend der Installation durch den korrekten Hostnamen, Port und Pfad ersetzt werden, üblicherweise etwa https://[myhost]/administration/…

EntityID

Das Attribut entityID in der ersten Zeile der Metadaten-Datei gibt den föderationsweit eindeutigen Namen der Organisation an, die als SP/IdP auftritt. Dieses muss auf einen passenden Wert geändert werden. Er muss übereinstimmen mit dem Wert der Eigenschaft saml2.local.entityid in [INSTALL_FOLDER]/webapp/administration/WEB-INF/classes/application.properties.

Zertifikat

Des weiteren muss das von der Installation genutzte Zertifikat in die Metadaten-Datei übernommen werden, damit andere Teilnehmer der Föderation von dieser Instanz signierte Inhalte validieren können. Das Zertifikat befindet sich in der der Datei .keystore im "data home"-Verzeichnis, das während der Installation angelegt worden ist. Standardmäßig wird der Ordner [INSTALL_FOLDER]/data verwendet. Um das Zertifkat im benötigten PEM-Format aus dem Keystore zu exportieren, kann das keytool-Kommando des JDK benutzt werden:

[SECMAN_DATA_DIR]> [JAVA_HOME]/bin/keytool -export -alias ct-security -keystore .keystore -storepass changeit -rfc

Der zwischen -----BEGIN CERTIFICATE----- und -----END CERTIFICATE----- ausgegebene Text muss in die Metadatendatei in das Element ds:x509Certificate kopiert werden.

Angepasste local-sp-metadata.xml

<EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" entityID="example.org">
    <SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol" WantAssertionsSigned="true">
        <KeyDescriptor>
            <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
                <ds:X509Data>
                <ds:X509Certificate>MIICLjCCAZcCBEirSywwDQYJKoZIhvcNAQEEBQAwXjELMAkGA1UEBhMCREUxETAP
                BgNVBAcTCE11ZW5zdGVyMRcwFQYDVQQKEw5jb24gdGVycmEgR21iSDEPMA0GA1UE
                CxMGc2VydmVyMRIwEAYDVQQDEwljb24tdGVycmEwHhcNMDgwODE5MjIzNzMyWhcN
                MTMwNzI0MjIzNzMyWjBeMQswCQYDVQQGEwJERTERMA8GA1UEBxMITXVlbnN0ZXIx
                FzAVBgNVBAoTDmNvbiB0ZXJyYSBHbWJIMQ8wDQYDVQQLEwZzZXJ2ZXIxEjAQBgNV
                BAMTCWNvbi10ZXJyYTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEAj0/qvXMZ
                mogeZgcvpysZxAOieFHuCknOsJ1iSe/n+leuoVqmgvfwfI0BEocT3TrGK1189nAa
                MRdZFq2Dy0hdmsnKsKR0dDtArMpmzhHHsFOTKzupbdixa2RmJq845b8BxVUC92h4
                55rnV2QMIYqAh/88ArBLe4HeyjyKMM7VgicCAwEAATANBgkqhkiG9w0BAQQFAAOB
                gQBLM9auhRWmfTCfYEuQLXs40OC/i/byYzWJ4Dz7ZUZPxMfSraGy+vyVkCbxw2JL
                +194wEGpAY7giI08NwvKRAQkH+qV/XeklUs9a9Qx3WKw7ZtUcoTCodpfA61YlmWT
                DZ24m6MJtdVIBccBzFyfeA1LfAFdaouGXLLgHIN/+rr3nw==</ds:X509Certificate>
                </ds:X509Data>
            </ds:KeyInfo>
        </KeyDescriptor>
        <NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</NameIDFormat>
        <!--<NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</NameIDFormat>
        <NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</NameIDFormat>
        <NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</NameIDFormat>-->
        <!-- <AssertionConsumerService
        Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact"
        Location="https://www.example.org/administration/saml2/acs/Artifact"
        index="1" /> -->
        <AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://www.example.org/administration/saml2/acs/POST" index="2"/>
        <AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://www.example.org/administration/saml2/acs/Redirect" index="9"/>
        <AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:PAOS" Location="https://www.example.org/administration/saml2/acs/ECP" index="10"/>
    </SPSSODescriptor>
</EntityDescriptor>

Angepasste local-idp-metadata.xml

<EntityDescriptor entityID="example.org" xmlns="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:xsi="http://www.w3.org /2001/XMLSchema-instance">
    <IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
        <KeyDescriptor>
            <ds:KeyInfo>
                <ds:X509Data>
                    <ds:X509Certificate>MIICLjCCAZcCBEirSywwDQYJKoZIhvcNAQEEBQAwXjELMAkGA1UEBhMCREUxETAP
                        BgNVBAcTCE11ZW5zdGVyMRcwFQYDVQQKEw5jb24gdGVycmEgR21iSDEPMA0GA1UE
                        CxMGc2VydmVyMRIwEAYDVQQDEwljb24tdGVycmEwHhcNMDgwODE5MjIzNzMyWhcN
                        MTMwNzI0MjIzNzMyWjBeMQswCQYDVQQGEwJERTERMA8GA1UEBxMITXVlbnN0ZXIx
                        FzAVBgNVBAoTDmNvbiB0ZXJyYSBHbWJIMQ8wDQYDVQQLEwZzZXJ2ZXIxEjAQBgNV
                        BAMTCWNvbi10ZXJyYTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEAj0/qvXMZ
                        mogeZgcvpysZxAOieFHuCknOsJ1iSe/n+leuoVqmgvfwfI0BEocT3TrGK1189nAa
                        MRdZFq2Dy0hdmsnKsKR0dDtArMpmzhHHsFOTKzupbdixa2RmJq845b8BxVUC92h4
                        55rnV2QMIYqAh/88ArBLe4HeyjyKMM7VgicCAwEAATANBgkqhkiG9w0BAQQFAAOB
                        gQBLM9auhRWmfTCfYEuQLXs40OC/i/byYzWJ4Dz7ZUZPxMfSraGy+vyVkCbxw2JL
                        +194wEGpAY7giI08NwvKRAQkH+qV/XeklUs9a9Qx3WKw7ZtUcoTCodpfA61YlmWT
                        DZ24m6MJtdVIBccBzFyfeA1LfAFdaouGXLLgHIN/+rr3nw==</ds:X509Certificate>
                </ds:X509Data>
            </ds:KeyInfo>
        </KeyDescriptor>
        <NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</NameIDFormat>
        <!--<NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</NameIDFormat>
        <NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</NameIDFormat>
        <NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</NameIDFormat>-->
        <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://www.example.org/administration/saml2/idp/profile/SAML2/POST/SSO"/>
        <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://www.example.org/administration/saml2/idp/profile/SAML2/Redirect/SSO"/>
        <!-- <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" Location="https://www.example.org/administration/saml2/idp/profile/SAML2/SOAP/ECP" />-->
    </IDPSSODescriptor>
</EntityDescriptor>

Lokale Registrierung der Metadaten

Sämtliche Metadaten der Teilnehmer der Föderation müssen in [DATA_DIR]/saml2metadata abgelegt werden. Damit die lokale SP/IdP-Konfiguration wirksam wird, muss die angepasste Metadatendatei in dieses Verzeichnis kopiert werden. Außerdem müssen alle Metadaten akzeptierter, d.h. vertrauenswürdiger IdPs und SPs dort abgelegt werden.

Es muss sichergestellt sein, dass für eine spezifische entityId nur maximal eine Metadaten-Datei in dem Verzeichnis [DATA_DIR]/saml2metadata existiert. Soll beispielsweise der security.manager gleichzeitig als Identity Provider und als Service Provider fungieren, müssen die Inhalte der beiden Matadaten-Vorlage-Dateien in einer einzelnen .xml Datei zusammengefasst werden:

local-sp-and-idp-metadata.xml

<EntityDescriptor entityID="example.org" xmlns="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:xsi="http://www.w3.org /2001/XMLSchema-instance">
    <IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
        ...
    </IDPSSODescriptor>
    <SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
        ...
    </SPSSODescriptor>
</EntityDescriptor>

Registrierung der Metadaten in der Föderation

Für die Integration in eine Föderation als Service Provider oder Identity Provider müssen die lokalen Metadaten bei den teilnehmenden SPs und IdPs registriert werden. Die konkrete Durchführung der Registrierung bei Dritt-IdP/-SP ist produktabhängig und der jeweiligen Produktdokumentation zu entnehmen.