====== Shibboleth SP ======

===== Installation und allgemeine Dokumentation =====
Siehe hierzu die betreffenden Seiten  
  * im [[https://wiki.shibboleth.net/confluence/display/SP3/Home|Shibboleth Wiki]] und
  * bei [[https://www.switch.ch/aai/guides/sp/|SWITCH]]; dort auch viele [[https://www.switch.ch/aai/guides/sp/access-rules/|Konfigurationsbeispiele für Autorisierung und Zugriffskontrolle (Access Rules)]]

===== Konfigurationsbeispiel =====

**Vorbemerkung:** In den folgenden Beispielen wird davon ausgegangen, dass zur Einrichtungsauswahl der [[de:shibsp#shibboleth_eds_embedded_discovery_service|Shibboleth Embedded Discovery Service]] (EDS) zum Einsatz kommt (siehe unten). Ein solcher SP-seitiger Discovery Service ist in den meisten Fällen das Mittel der Wahl, da er die "User-Experience" verbessert - insbesondere in Szenarien, in denen ein SP-Betreiber die Liste für die IdP-Auswahl über bestimmte Filter modifizieren/einschränken möchte. Da dieser sehr einfach zu konfigurierenden EDS quasi als Zubehör zum Shibboleth SP mitgeliefert wird, sei er an dieser Stelle besonders empfohlen. \\
Sollten Sie aus bestimmten Gründen doch bevorzugt den zentralen, vom DFN betriebenen DS/WAYF verwenden wollen, finden Sie einige Konfigurationsbeispiele [[de:production#discovery_service|hier]].

====Shibboleth SP (3.x)====

Editieren Sie die Haupt-Configdatei des SP an folgenden Stellen:

<file xml /etc/shibboleth/shibboleth2.xml>
<SPConfig ... >
  ...
  <!-- "sp.example.org" durch den SP-Vhost-Namen ersetzen -->
  <ApplicationDefaults entityID="https://myvhost.mydomain.de/shibboleth" ... >
  ...
   <!-- handerSSL auf "true" und cookieProps auf "https" -->
   <Sessions lifetime="28800" timeout="3600" relayState="ss:mem"
             checkAddress="false" consistentAddress="true"  
             handlerSSL="true" cookieProps="https" redirectLimit="host">
      ...
      <!-- "sp.example.org" durch den SP-Vhost-Namen ersetzen -->
      <SSO discoveryProtocol="SAMLDS" discoveryURL="https://myvhost.mydomain.de/shibboleth-ds/index.html">
         SAML2
      </SSO>
      ...
   </Sessions>       
   ...
   <!-- valide (Admin-/Hotline-) eMail-Adresse und korrekte URLs/Pfade einfügen-->
   <Errors supportContact="helpdesk@example.org"
           helpLocation="/about.html"
           styleSheet="/shibboleth-sp/main.css"/>
   ...
   <!-- Metadaten der Test-Föderation aktivieren -->
   <!-- den Pfad zum Zertifikat zur Signaturüberprüfung den lokalen Gegebenheiten anpassen! -->
   <MetadataProvider type="XML" url="http://www.aai.dfn.de/metadata/dfn-aai-test-metadata.xml"
         validate="true" backingFilePath="dfn-aai-test-metadata.xml" reloadInterval="3600">
       <MetadataFilter type="Signature" certificate="/etc/ssl/aai/dfn-aai.pem" verifyBackup="false"/>
   </MetadataProvider>
   ...
   <!-- Pfadangaben zu den Zertifikat-Dateien -->
   <CredentialResolver type="File" key="/etc/ssl/private/myvhost.mydomain.de.key.pem" 
          certificate="/etc/ssl/localcerts/myvhost.mydomain.de.crt.pem"/>
   ...
  </ApplicationDefaults>
  ...
</SPConfig>
</file>

Zur MetadataProvider-Konfiguration für die Produktivumgebung der DFN-AAI siehe unter [[de:production#beispiel_sp|Produktivbetrieb]]. 

<callout type="danger" title="Wichtig: Im Sessions-Element unbedingt redirectLimit auf 'host' oder 'exact' setzen!">
Achten Sie bitte unbedingt darauf, dass in **''shibboleth2.xml''** in allen **''<Sessions>''**-Elementen das XML-Attribut **''redirectLimit''** 
  - gesetzt wird und
  - den Wert **''host''** oder **''exact''** erhält! (ggf. in Kombination mit ''allow'')
Auf diese Weise wird ein Problem mit offenen Weiterleitungen ("Open Redirect") verhindert, das bspw. Phishing-Angriffe wirkungsvoller machen kann, vgl. https://shibboleth.atlassian.net/browse/SSPCPP-714. 
Weitere Informationen zu Konfigurationsmöglichkeiten für das ''<Sessions>''-Element sind im [[https://shibboleth.atlassian.net/wiki/spaces/SP3/pages/2065334342/Sessions|Shibboleth-Wiki dokumentiert]].
</callout>


===Filtermechanismen===

Wenn der vom SP geschützte Dienst nur von Angehörigen bestimmter Einrichtungen genutzt werden soll, können anhand bestimmter Kriterien sogenannte [[https://shibboleth.atlassian.net/wiki/spaces/SP3/pages/2063696193/MetadataFilter|Metadata Filter]] im SP konfiguriert werden. Dies hat zwei Vorteile:
  - Der SP arbeitet intern nur mit dem gefilterten, in der Regel deutlich reduzierten Metadatensatz
  - der Embedded Discovery Service zeigt nur diejenigen IdPs bzw. Einrichtungen an, welche in diesen gefilterten Metadaten enthalten sind. In shibboleth2.xml muss ''<Handler type="DiscoveryFeed" Location="/DiscoFeed"/>'' aktiv sein, bitte überprüfen sie das zur Sicherheit!).

Die Whitelist wird dann folgendermaßen konfiguriert:

<file xml /etc/shibboleth/shibboleth2.xml>

...
   <MetadataProvider type="XML" 
         url="http://www.aai.dfn.de/metadata/dfn-aai-idp-metadata.xml"
         validate="true" backingFilePath="dfn-aai-idp-metadata.xml" reloadInterval="3600">
      <MetadataFilter type="Signature" certificate="/etc/ssl/aai/dfn-aai.pem" verifyBackup="false" />
      <MetadataFilter type="Include">
         <Include>https://idp.uni-beispiel1.de/idp/shibboleth</Include>
         <Include>https://idp.uni-beispiel2.de/idp/shibboleth</Include>
         <Include>https://idp.uni-beispiel3.de/idp/shibboleth</Include>
      </MetadataFilter>
   </MetadataProvider>
   ...

</file>

Für ein Beispiel eines Metadata Filters anhand einer [[de:entity_attributes#entity_categories|Entity Category]] siehe die Dokumentation des bwIDM-Projekts unter https://www.bwidm.de/teilnahme/dienstanbieter/ (Abschnitt 1.2 - Technische Voraussetzungen).

Weiter Beispiele für Include- und Exclude-Filter anhand von Entity Attributen siehe unter [[https://doku.tid.dfn.de/de:entity_attributes#beispiele_filter|Entity Attributes]].

Im folgenden zwei Beispiele für Metadata Filter, die anhand der **Registration Authority** (also der jeweiligen Heimatföderation) auf die eduGAIN-Metadaten angewandt werden:

**Nur Identity Provider aus der SWITCHaai (CH) und ACOnet Identity Federation (AT) zulassen:**

<file xml /etc/shibboleth/shibboleth2.xml>
...
   <MetadataProvider type="XML" 
         url="http://www.aai.dfn.de/metadata/dfn-aai-edugain+idp-metadata.xml"
         validate="true" backingFilePath="dfn-aai-edugain+idp-metadata.xml" reloadInterval="3600">
      <MetadataFilter type="Signature" certificate="/etc/ssl/aai/dfn-aai.pem" verifyBackup="false" />
      <MetadataFilter type="Include" matcher="RegistrationAuthority">
         <registrationAuthority>http://rr.aai.switch.ch/</registrationAuthority>
         <registrationAuthority>http://eduid.at</registrationAuthority>
      </MetadataFilter>
   </MetadataProvider>
   ...
</file>

**Identity Provider aus zwei fiktiven Föderationen ausschließen:**

<file xml /etc/shibboleth/shibboleth2.xml>
...
   <MetadataProvider type="XML" 
         url="http://www.aai.dfn.de/metadata/dfn-aai-edugain+idp-metadata.xml"
         validate="true" backingFilePath="dfn-aai-edugain+idp-metadata.xml" reloadInterval="3600">
      <MetadataFilter type="Signature" certificate="/etc/ssl/aai/dfn-aai.pem" verifyBackup="false" />
      <MetadataFilter type="Exclude" matcher="RegistrationAuthority">
         <registrationAuthority>http://xyz.qq</registrationAuthority>
         <registrationAuthority>http://zyx.ww</registrationAuthority>
      </MetadataFilter>
   </MetadataProvider>
   ...
</file>

<callout type="primary" title="Hinweis">
Die Werte für **registrationAuthority** sind unter https://technical.edugain.org/status dokumentiert. Ein Klick auf den jeweiligen Föderationsnamen öffnet ein Fenster mit allen relevanten Informationen.
</callout>

\\

Nach allen Änderungen in ''shibboleth2.xml'' muss der shibd Service neu gestartet werden:

Funktioniert die überarbeitete Konfiguration?
<code bash>root@host:~# shibd -t</code>

Dann ab dafür:
<code bash>root@host:~# systemctl restart shibd</code>

Fallweise kann es passieren, dass der Webserver aus dem Tritt kommt, z.B. nach mehreren shibd-Restarts. In solchen Fällen muss auch dieser neu gestartet werden:
<code bash>root@host:~# systemctl restart apache2</code>

==== Shibboleth EDS (Embedded Discovery Service)====

=== Installation ===

(Im Folgenden eine Kurzanleitung zur Installation, eine ausführlichere finden Sie auf den [[https://wiki.shibboleth.net/confluence/display/EDS10/2.+Installation|Seiten im Shibboleth Wiki]].)

  * CentOS/RedHat/SuSE

Für RPM-basierte Linux-Varianten bieten die Shibboleth-Entwickler ein [[https://wiki.shibboleth.net/confluence/display/EDS10/2.+Installation|RPM-Paket]] an.

  * Debian/Ubuntu/etc.

Laden Sie das aktuelle [[https://shibboleth.net/downloads/embedded-discovery-service/latest/|tar-File]] herunter, packen Sie es aus und installieren Sie es:

<code>
root@server:~# wget https://shibboleth.net/downloads/embedded-discovery-service/latest/shibboleth-embedded-ds-1.2.2.tar.gz
root@server:~# tar -xzf shibboleth-embedded-ds-1.2.2.tar.gz
root@server:~# cd shibboleth-embedded-ds-1.2.2 ; make install
</code>

\\

=== Konfiguration ===

Damit der EDS die Arbeit aus Sicherheitsgründen nicht verweigert, muss der eigene Vhost-Namen in die "Return White List" eingetragen werden:

<file javascript /etc/shibboleth-ds/idpselect_config.js>
  ...
  this.returnWhiteList = [ "^https:\/\/meinvhost\.meinedomain\.de\/Shibboleth\.sso\/Login.*$" ];
  ...
</file>
<wrap warning>Achten Sie auf die korrekte Syntax, der Eintrag muss in Form einer Regular Expression gemacht werden!</wrap>

Verifizieren Sie in der gleichen Datei, daß der Parameter ''this.dataSource'' den Wert '''/Shibboleth.sso/DiscoFeed''' hat damit das Zusammenspiel zwischen SP und EDS funktioniert.

\\
Damit ist der EDS grundsätzlich einsatzbereit. Weitere Hinweise und Informationen (z.B. zur Anpassung des Layouts) finden sich in den Kommentaren der Konfigurationsdatei(en) sowie im 
[[https://wiki.shibboleth.net/confluence/display/EDS10/Embedded+Discovery+Service|Shibboleth-Wiki]].

=== Konfiguration für den Produktivbetrieb ===
   * das Layout des EDS muss in /etc/shibboleth-ds/index.html angepasst werden, in der die JavaScript-Aufrufe eingebettet werden, siehe hierzu die Kommentare in dieser Datei.
   * Für das <noscript>-Element empfiehlt sich der Link auf einen zentralen WAYF/DS, z.B.
<code>https://wayf.aai.dfn.de/DFN-AAI-Basic/wayf?entityID=https%3A%2F%2Fmyvhost.mydomain.de%2Fshibboleth&return=https%3A%2F%2Fmyvhost.mydpmain.de%2FShibboleth.sso%2FLogin%3FSAMLDS%3D1</code>


====Apache Webserver====

<file apache /etc/apache2/sites-enabled/myvhost.mydomain.de.conf>
<VirtualHost SP-IP-ADRESSE:443 [SP-IPv6-ADRESSE]:443>
  ServerName              myvhost.mydomain.de
  SSLEngine on
  SSLCertificateFile      /etc/ssl/localcerts/myvhost.mydomain.de.crt.pem
  SSLCertificateKeyFile   /etc/ssl/private/myvhost.mydomain.de.key.pem

  # siehe https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPApacheConfig
  UseCanonicalName On
  # EDS einbinden
  Include /etc/shibboleth-ds/shibboleth-ds.conf
 
  # einige SAML/AAI-Conventionen befolgen:
  Redirect seeother /shibboleth https://myvhost.mydomain.de/Shibboleth.sso/Metadata
  RedirectMatch /start-session$ /Shibboleth.sso/Login

  #######################################################
  # Dieser Block kann unter Debian/Ubuntu weggelassen
  # werden, da die Anweisungen automatisch beim Laden
  # des Moduls aktiv werden.
  #
  # Bei anderen Linuxen sind diese aber vielleicht nötig!
  #
  <Location /Shibboleth.sso>
    AuthType None
    Require all granted
  </Location>
  <Location /shibboleth-sp>
    AuthType None
    Require all granted
  </Location>
  Alias /shibboleth-sp/main.css /usr/share/shibboleth/main.css
  #######################################################
  #
  # Vom SP zu schützende Location
  #
  <Location /secure>
    AuthType shibboleth
    ShibRequestSetting requireSession true
    Require valid-user
  </Location>  
</VirtualHost>
</file>

<code bash>root@host:~# systemctl reload apache2</code>

Um sicherzustellen, dass die Webserver-Konfiguration den aktuellen Sicherheitsstandards entspricht, informieren Sie sich bitte z.B. bei [[https://ssl-config.mozilla.org/|Mozilla]], dem [[https://www.dfn-cert.de/|DFN-CERT]], der [[https://blog.pki.dfn.de/|DFN-PKI]] oder [[https://www.ssllabs.com/|SSL LABS]]. Das letztgenannte Portal bietet auch einen Online-Test der Webserver-Konfiguration an.

<callout type="primary" title="Ergänzende Hinweise">
  * **Zu den Änderungen gegenüber der alten Version 2.x** 
    * Siehe im Shibboleth Wiki unter [[https://wiki.shibboleth.net/confluence/display/SP3/UpgradingFromV2|UpgradingFromV2]].
  * **Zertifikate** ''CredentialResolver''
    * Siehe unter [[de:certificates|Zertifikate]]
  * **Metadaten** (und dfn-aai.pem zur Verifikation der Signatur) ''MetadataProvider''
    * Siehe unter [[de:metadata|Metadaten]] und [[de:production#metadataprovider|Produktivbetrieb]]
  * **Discovery Service** ''SSO/@discoveryURL''
    * Siehe unter [[de:discovery|Discovery]] und [[de:production#discovery_service|Produktivbetrieb]]
  * Grundlegende Dokumentation im [[https://wiki.shibboleth.net/confluence/display/SP3/Home|Shibboleth Wiki]]
  * Installations- und Konfigurationsanleitungen der [[https://www.switch.ch/aai/guides/sp/|SWITCHaai]]:
    * [[https://www.switch.ch/aai/guides/sp/installation/|Installation]]
    * [[https://www.switch.ch/aai/guides/sp/access-rules/|Access Control]]
</callout>

{{tag>sp}}