Dies ist eine alte Version des Dokuments!


Basis-Konfiguration des Shibboleth IdP 3.x

Die unten genannten Arbeitsschritte erfolgen innerhalb des bei der Installation erstellten Ziel-Verzeichnisses (default: /opt/shibboleth-idp) und sollten weitestgehend plattform-unabhängig erfolgen. Ausnahmen werden als solche kenntlich gemacht.

NB Bei den Konfigurationsbeispielen bitte nicht die kompletten Dateien mit den Konfigurationsschnipseln ersetzen, i.d.R. handelt es sich nur um Auszüge. Bitte nur die angezeigten Zeilen übernehmen bzw. entsprechend ergänzen!

Wir empfehlen während der Konfiguration permanent zwei Desktop-Fenster offen zu halten in denen Sie den Tomcat- und den IdP-Log mitverfolgen sollten:

root@idp:/opt/shibboleth-idp# tail -f /var/log/tomcat8/catalina.out
root@idp:/opt/shibboleth-idp# tail -f logs/idp-process.log

So sehen Sie sofort falls Sie beim Editiern einer Datei einen Fehler gemacht haben!

Der IdP kann gleichzeitig mehrere Metadatensätze verarbeiten. Um später einen reibungslosen Übergang in die DFN-AAI-Produktivumgebung zu gewährleisten sollten Sie jetzt gleich sowohl die Metadaten der Testumgebung als auch der Produktivumgebung eintragen:

/opt/shibboleth-idp/conf/metadata-providers.xml
<MetadataProvider id="ShibbolethMetadata" xsi:type="ChainingMetadataProvider" ...>
 
    <!-- ... -->
 
    <!-- für den initialen Testbetrieb die Metadaten der Testföderation -->
    <MetadataProvider id="DFN_AAI_Test"
                  xsi:type="FileBackedHTTPMetadataProvider"
                  backingFile="%{idp.home}/metadata/DFN-AAI-Test-metadata.xml"
                  metadataURL="http://www.aai.dfn.de/fileadmin/metadata/DFN-AAI-Test-metadata.xml"
                  maxRefreshDelay="PT2H">
            <MetadataFilter xsi:type="SignatureValidation" requireSignedRoot="true"
                  certificateFile="/etc/ssl/aai/dfn-aai.pem"/>
            <MetadataFilter xsi:type="EntityRoleWhiteList">
                  <RetainedRole>md:SPSSODescriptor</RetainedRole>
            </MetadataFilter>
    </MetadataProvider>
 
    <!-- Die Produktiv-Metadaten können auch sofort aktiviert werden -->
    <MetadataProvider id="DFN_AAI"
                  xsi:type="FileBackedHTTPMetadataProvider"
                  backingFile="%{idp.home}/metadata/DFN-AAI-sp-metadata.xml"
                  metadataURL="http://www.aai.dfn.de/fileadmin/metadata/DFN-AAI-sp-metadata.xml"
                  maxRefreshDelay="PT2H">
            <MetadataFilter xsi:type="SignatureValidation" requireSignedRoot="true"
                  certificateFile="/etc/ssl/aai/dfn-aai.pem"/>
            <MetadataFilter xsi:type="EntityRoleWhiteList">
                  <RetainedRole>md:SPSSODescriptor</RetainedRole>
            </MetadataFilter>
    </MetadataProvider>
 
    ...
 
</MetadataProvider>

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

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

Die IdM-Anbindung ist erfahrungsgemäss der kniffligste Teil der IdP-Konfiguration. Es empfiehlt sich daher den Default-Loglevel der LDAP-Kategorie zu erhöhen:

/opt/shibboleth-idp/conf/logback.xml
    ...
    <!-- aus Datenschutzgründen nur 14 Tage aufbewahren -->
    <variable name="idp.loghistory" value="14" />
 
    <!-- Much higher performance if you operate on DEBUG. -->
    <!-- <variable name="idp.process.appender" value="ASYNC_PROCESS" /> -->
 
    <!-- Logging level shortcuts. -->
    <variable name="idp.loglevel.idp" value="INFO" />
    <!-- Loglevel von "WARN" auf "INFO" ändern -->
    <variable name="idp.loglevel.ldap" value="INFO" />
    ...

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

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

Bei einem Login-Vorgang des Users am IdP macht der IdP im Hintergrund zwei LDAP-Abfragen:

  • Authentisierung des Users
  • Abruf der Attribute des Users

Diese beiden Schritte werden in ldap.properties unabhängig voneinander konfiguriert:

LDAP-Abfrage 1: User-Authentisierung

/opt/shibboleth-idp/conf/ldap.properties
# bitte entsprechend den Möglichkeiten Ihres IdM-Systems anpassen, im Beispiel
# eine Konfiguration wie Sie für OpenLDAP und auch Active Directory funktionieren kann:
idp.authn.LDAP.authenticator                    = bindSearchAuthenticator
idp.authn.LDAP.ldapURL                          = ldaps://ldap.uni-beispiel.de:636
idp.authn.LDAP.useStartTLS                      = false
idp.authn.LDAP.useSSL                           = true
idp.authn.LDAP.sslConfig                        = certificateTrust
# Pfad zur Zert der Root-CA der verwendeten PKI, z.B. DFN-PKI:
idp.authn.LDAP.trustCertificates                = /etc/ssl/certs/Deutsche_Telekom_Root_CA_2.pem
#
# sofern während der Auth-Phase festgestellt werden  soll, ob der Account aktiv ist, müssen
# hier die entsprechenden Attribute angegeben werden
# (FIXME: konkretes Beispiel für OpenLDAP und AD heraussuchen)
idp.authn.LDAP.returnAttributes                 = passwordExpirationTime,loginGraceRemaining
idp.authn.LDAP.baseDN                           = ou=people,dc=uni-beispiel,dc=de
# statt "(uid={user})" nehmen Sie bei AD üblicherweise "(cn={user})" oder "(sAMAccountName={user})"
idp.authn.LDAP.userFilter                       = (uid={user})
idp.authn.LDAP.bindDN                           = cn=idp,dc=uni-beispiel,dc=de
idp.authn.LDAP.bindDNCredential                 = strengGeheimesPasswort

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

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

Siehe auch im Shibboleth Wiki unter LDAPAuthnConfiguration.

LDAP-Abfrage 2: User-Attribute

/opt/shibboleth-idp/conf/ldap.properties
# wie bei Abfrage 1 muss hier das relevante User-Attribut angegeben werden, für
# MS-AD ist das üblicherweise "(cn=$resolutionContext.principal)" oder "(sAMAccountName=$resolutionContext.principal)"
idp.attribute.resolver.LDAP.searchFilter        = (uid=$resolutionContext.principal)

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

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

Bevor Sie weiter machen müssen Sie unbedingt die LDAP-Verbindung testen!

Es werden Ihnen jetzt noch keine Attribute angezeigt, was aber nicht weiter tragisch ist.

Sollten Sie nicht erfolgreich zum SP zurückgeleitet werden, achten Sie darauf, von welchem System die Fehlermeldung im Browser generiert wird. Entsteht die Fehlermeldung am IdP, schauen Sie bitte in idp-process.log nach, was die Ursache ist. Generiert unser Test-SP die Fehlermeldung, schauen Sie bitte im Online-Log https://testsp2.aai.dfn.de/ShibLogViewer2/SPLogViewer.html des SP. Mithilfe dieser Meldung und des Shib-Wiki unter https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPTroubleshootingCommonErrors sollten Sie in den meisten Fällen die Ursache bestimmen können. Sollten Sie damit nicht weiterkommen, senden Sie uns bitte einen Screenshot der Fehlermeldung und den genauen Zeitpunkt, zu dem der Fehler aufgetreten ist, damit wir mithilfe unseres SP-Logs die Ursache bestimmen können.

Erst wenn der Login funktioniert sollten Sie die Attribute-Konfiguration angehen!

Erzeugung und Freigabe der SAML-Attribute wird weiterhin über die Dateien attribute-resolver.xml und attribute-filter.xml gesteuert. Diese unterscheiden sich syntaktisch und semantisch leicht von den gewohnten Dateien im IdP 2.x.

Mit den folgenden beiden Konfigurationsdateien sollte ein erster Test gegen die DFN-Test-SPs schnell gelingen:

attribute-resolver.xml für die DFN-AAI

/opt/shibboleth-idp/conf/attribute-resolver.xml
?xml version="1.0" encoding="UTF-8"?>
<AttributeResolver
        xmlns="urn:mace:shibboleth:2.0:resolver"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="urn:mace:shibboleth:2.0:resolver http://shibboleth.net/schema/idp/shibboleth-attribute-resolver.xsd">
 
    <!-- ========================================== -->
    <!--      Attribute Definitions                 -->
    <!-- ========================================== -->
 
    <!-- für uid das nehmen was der User eingetippt hat -->
    <AttributeDefinition id="uid" xsi:type="PrincipalName">
        <DisplayName xml:lang="en">User Name</DisplayName>
        <DisplayName xml:lang="de">Nutzerkennung</DisplayName>
        <DisplayDescription xml:lang="en">Local User Id</DisplayDescription>
        <DisplayDescription xml:lang="de">Nutzerkennung der Heimateinrichtung</DisplayDescription>
        <AttributeEncoder xsi:type="SAML1String" name="urn:mace:dir:attribute-def:uid" encodeType="false" />
        <AttributeEncoder xsi:type="SAML2String" name="urn:oid:0.9.2342.19200300.100.1.1" friendlyName="uid" encodeType="false" />
    </AttributeDefinition>
 
    <!--- eduPersonPrincipalName aus uid generieren -->
    <AttributeDefinition id="eduPersonPrincipalName" xsi:type="Scoped" scope="%{idp.scope}" sourceAttributeID="uid">
        <Dependency ref="uid" />
        <DisplayName xml:lang="en">Principal name</DisplayName>
        <DisplayName xml:lang="de">Netz-Id</DisplayName>
        <DisplayDescription xml:lang="en">A unique identifier for a person, mainly for inter-institutional user identification</DisplayDescription>
        <DisplayDescription xml:lang="de">Eindeutige, einrichtungsübergreifende Nutzerkennung</DisplayDescription>
        <AttributeEncoder xsi:type="SAML1ScopedString" name="urn:mace:dir:attribute-def:eduPersonPrincipalName" encodeType="false" />
        <AttributeEncoder xsi:type="SAML2ScopedString" name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6" friendlyName="eduPersonPrincipalName" encodeType="false" />
    </AttributeDefinition>
 
    <!--- mail aus LDAP holen -->
    <AttributeDefinition id="mail" xsi:type="Simple" sourceAttributeID="mail">
        <Dependency ref="myLDAP" />
        <DisplayName xml:lang="en">E-mail</DisplayName>
        <DisplayName xml:lang="de">E-Mail</DisplayName>
        <DisplayDescription xml:lang="en">E-Mail address</DisplayDescription>
        <DisplayDescription xml:lang="de">E-Mail Adresse</DisplayDescription>
        <AttributeEncoder xsi:type="SAML1String" name="urn:mace:dir:attribute-def:mail" encodeType="false" />
        <AttributeEncoder xsi:type="SAML2String" name="urn:oid:0.9.2342.19200300.100.1.3" friendlyName="mail" encodeType="false" />
    </AttributeDefinition>
 
   <!-- ========================================== -->
    <!--      Data Connectors                       -->
    <!-- ========================================== -->
 
    <DataConnector id="myLDAP" xsi:type="LDAPDirectory"
        ldapURL="%{idp.attribute.resolver.LDAP.ldapURL}"
        baseDN="%{idp.attribute.resolver.LDAP.baseDN}"
        principal="%{idp.attribute.resolver.LDAP.bindDN}"
        principalCredential="%{idp.attribute.resolver.LDAP.bindDNCredential}"
        useStartTLS="%{idp.attribute.resolver.LDAP.useStartTLS:true}"
        connectTimeout="%{idp.attribute.resolver.LDAP.connectTimeout}"
        trustFile="%{idp.attribute.resolver.LDAP.trustCertificates}"
        responseTimeout="%{idp.attribute.resolver.LDAP.responseTimeout}">
        <FilterTemplate>
            <![CDATA[
                %{idp.attribute.resolver.LDAP.searchFilter}
            ]]>
        </FilterTemplate>
        <ConnectionPool
            minPoolSize="%{idp.pool.LDAP.minSize:3}"
            maxPoolSize="%{idp.pool.LDAP.maxSize:10}"
            blockWaitTime="%{idp.pool.LDAP.blockWaitTime:PT3S}"
            validatePeriodically="%{idp.pool.LDAP.validatePeriodically:true}"
            validateTimerPeriod="%{idp.pool.LDAP.validatePeriod:PT5M}"
            expirationTime="%{idp.pool.LDAP.idleTime:PT10M}"
            failFastInitialize="%{idp.pool.LDAP.failFastInitialize:false}" />
    </DataConnector>
 
</AttributeResolver>

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

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

attribute-filter.xml für die DFN-AAI

/opt/shibboleth-idp/conf/attribute-filter.xml
<?xml version="1.0" encoding="UTF-8"?>
<AttributeFilterPolicyGroup id="ShibbolethFilterPolicy"
        xmlns="urn:mace:shibboleth:2.0:afp"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="urn:mace:shibboleth:2.0:afp http://shibboleth.net/schema/idp/shibboleth-afp.xsd">
 
   <!-- Attribute an die DFN-Test-IdPs freigeben -->
   <AttributeFilterPolicy id="dfn-test-sps">
        <PolicyRequirementRule xsi:type="OR">
            <Rule xsi:type="Requester" value="https://testsp.aai.dfn.de/shibboleth" />
            <Rule xsi:type="Requester" value="https://testsp2.aai.dfn.de/shibboleth" />
        </PolicyRequirementRule>
 
        <AttributeRule attributeID="uid"                    permitAny="true"/>
        <AttributeRule attributeID="eduPersonPrincipalName" permitAny="true"/>
        <AttributeRule attributeID="mail"                   permitAny="true"/>
  </AttributeFilterPolicy>
 
</AttributeFilterPolicy>

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

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

Bitte testen Sie jetzt die Attribute-Freigabe gegen unsere Test-SPs, siehe dazu https://www.aai.dfn.de/teilnahme/funktionstest/

Erst wenn diese Tests erfolgreich sind uns Sie die Attribute 'uid', 'eduPersonPrincipalName' und 'mail' angezeigt bekommen, sollten Sie mit der IdP-Konfiguration weiter machen!

Mit dem Resolvertest (aacli) besteht die Möglichkeit, die Attributfreigabe für eine(n) bestimmte(n) Nutzer(in) gegenüber einem bestimmten SP zu testen. Der Aufruf von bin/aacli.sh generiert einen URL, der dann z.B. im Browser eingegeben werden kann (auch hier Zugriffskontrolle über conf/access-control.xml):

root@idp# ./aacli.sh -n test-clt -r https://testsp3.aai.dfn.de/shibboleth

(-n principal = user id; -r requester = entityId des anfragenden SP)

Sofern Sie erfolgreich Attribute übertragen konnten sollten Sie jetzt als nächstes auf DFN-PKI-Zertifikate wechseln.

Die bei der Installation erzeugten Private Keys und zugehörigen selbst-signierten Zertifikate müssen für den späteren Produktionsbetrieb gegen DFN-PKI-Zertifikate ausgetauscht werden. Wir empfehlen die Verwendung der selben Key- und Zertifikats-Files, die bereits für den Webserver verwendet werden, damit das Key-Handling nicht zu unübersichtlich wird.

Unter Debian/Ubuntu liegen diese Files typischerweise unter /etc/ssl, bei anderen Systemen bitte entsprechend anpassen:

/opt/shibboleth-idp/conf/idp.properties
# ...
# Settings for public/private signing and encryption key(s)
# During decryption key rollover, point the ".2" properties at a second
# keypair, uncomment in credentials.xml, then publish it in your metadata.
idp.signing.key= /etc/ssl/private/idp-dev.uni-beispiel.de.key.pem
idp.signing.cert= /etc/ssl/localcerts/idp-dev.uni-beispiel.de.crt.pem
idp.encryption.key= /etc/ssl/private/idp-dev.uni-beispiel.de.key.pem
idp.encryption.cert= /etc/ssl/localcerts/idp-dev.uni-beispiel.de.crt.pem
#idp.encryption.key.2 = /etc/ssl/private/idp-dev.uni-beispiel.de.key.pem.old
#idp.encryption.cert.2 = /etc/ssl/localcerts/idp-dev.uni-beispiel.de.crt.pem.old
# ...

Bitte darauf achten, dass die PEM-Files vom Tomcat-User gelesen werden dürfen!

Auf Debian/Ubuntu-Systemen sind die Private Keys nur für Mitglieder der Gruppe 'ssl-cert' lesbar. Der Tomcat-User muss also Mitglied dieser Gruppe sein, siehe die entsprechenden Hinweise zur Vorbereitung der Systemumgebung in diesem Wiki und auch im Shibboleth Wiki unter SecurityConfiguration.

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

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

Wichtig:

  • Denken Sie daran, das neue Zertifikat in der DFN-AAI-Metadatenverwaltung einzutragen. Dort sind zunächst die bei der Installation generierten selbst-signierten Zertifikate eingetragen worden. Am besten löschen Sie dort alle (sechs!) Zertifikatsinstanzen und tragen danach das neue Zertifikat nur noch zweimal ein: einmal im Abschnitt „IdP Single Sign On Descriptor“ und einmal im Abschnitt „Attribute Authority Descriptor“. In beiden Fällen lassen Sie dabei das Feld „Verwendungszweck“ leer. Dieses wird nur für Spezialfälle gebraucht.
  • Warten Sie dann zwei Stunden bis die neuen Zertifkate in die DFN-AAI-Test-Metadaten aufgenommen worden sind und testen Sie nochmal die Attribut-Freigaben wie oben beschrieben!
  • Die Datei./metadata/idp-metadata.xml enthält nach wie vor die selbst-signierten Zertifikate, die bei der Installation automatisch generiert werden. Diese Datei wird nicht automatisch aktualisiert. Allerdings ist das insofern kein Problem, als sie für den Betrieb des IdP nicht erforderlich ist, sondern lediglich als Hilfsmittel zur Registrierung des IdP in einer Föderation gedacht ist.

Weiter geht's mit dem Webseiten-Layout auf der Layout-Seite.

  • Zuletzt geändert: vor 7 Jahren