====== Shibboleth SP 2 ======

<WRAP center round important 100%>
**Tento dokument popisuje Shibboleth SP řady 2, který byl dostupný jako balíček v repozitářích Debianu 9 (Stretch). Jak Shibboleth SP řady 2, tak Debian 9 (Stretch) jsou zastaralé a neměly by být používány. Prosím, přejděte na [[:cs:tech:sp:shibboleth|aktuální verzi návodu]].**
</WRAP>

Následující návod popisuje instalaci a konfiguraci [[https://shibboleth.net/products/service-provider.html|Shibboleth SP]] verze 2.6.0. Jako poskytovatele služby (Service Provider, SP) můžeme také použít [[https://simplesamlphp.org/|SimpleSAMLphp]], jehož instalace a konfigurace je na našich stránkách také [[:cs:tech:sp:simplesamlphp|zdokumentována]].

V návodu budeme používat linuxovou distribuci [[https://www.debian.org/|Debian]] v jeho poslední verzi 9 s kódovým označením [[https://www.debian.org/releases/stretch/|Stretch]]. Používáte-li jinou distribuci, některé kroky (např. instalace balíčků) se u vás budou odpovídajícím způsobem lišit.

<WRAP center round alert 100%>
**Problém s instalací na Ubuntu 18.04 LTS (Bionic Beaver)!**

//Ivan Masár// z Univerzity Tomáše Bati ve Zlíně narazil na problém s instalací balíčku **libapache2-mod-shib2** na Ubuntu 18.04 LTS (Bionic Beaver). Ten vyžaduje balíček **libcurl3**, nicméně ostatní balíčky povětšinou vyžadují **libcurl4**. Způsobuje to, že balíček **libapache2-mod-shib2** blokuje další mnohdy potřebné balíčky, např. //php-curl//.

Problém je v Ubuntu [[https://bugs.launchpad.net/ubuntu/+source/xmltooling/+bug/1776489|zdokumentován]] a existuje i [[https://depts.washington.edu/bitblog/2018/06/libcurl3-libcurl4-shibboleth-php-curl-ubuntu-18-04/|řešení]].
</WRAP>

Návod provází kompletní instalací a konfigurací SimpleSAMLphp včetně zdrojů metadat federace [[https://www.eduid.cz/cs/tech/summary|eduID.cz]] a Social IdPs (Facebook, GitHub, Google, LinkedIn, ORCID)..

===== Instalace =====

Balíček Shibboleth SP v Debianu včetně modulu pro HTTP server Apache nainstalujeme následujícím příkazem:

<code bash>
# Instalace Shibboleth SP včetně modulů pro Apache HTTP server
apt-get install libapache2-mod-shib2
</code>

Pokud na serveru chybí Apache, je třeba ho doinstalovat následujícím příkazem:

<code bash>
# Instalace Apache
apt-get install apache2
</code>

===== Konfigurace =====

Máme-li nainstalovaný Shibboleth SP z balíčků v Debianu, konfigurace je uložena v adresáři ''/etc/shibboleth''. Nejdůležitějším souborem je pak ''shibboleth2.xml''.

<code bash>
# Nejdůležitější nastavení Shibboleth SP se provádí v shibboleth2.xml
vi /etc/shibboleth/shibboleth2.xml
</code>

==== entityID ====

Služba se musí ve federaci nějak identifikovat a k tomuto účelu se používá //entityID//. V atributu ''entityID'' u elementu ''<ApplicationDefaults>'' definujeme //entityID// naší služby. Výchozí hodnota je nastavena na //<nowiki>https://sp.example.org/shibboleth</nowiki>//, doporučuji změnit pouze hodnotu //sp.example.org// na DNS název serveru.

<code xml>
<!-- Nastavení entityID -->
<ApplicationDefaults entityID="https://sp.example.org/shibboleth"
    REMOTE_USER="eppn persistent-id targeted-id">
</code>
==== Sezení ====

V elementu ''<Sessions>'' je možné nastavit několik důležitých voleb. Pro zvýšení bezpečnosti nastavíme u tohoto elementu atributy ''handlerSSL'', resp. ''cookieProps'' na hodnoty //true//, resp. //https// následujícím způsobem (ostatní atributy a hodnoty můžeme ponechat na výchozích hodnotách):

<code xml>
<!-- Nastavení handlerSLL a cookieProps -->
<Sessions lifetime="28800" timeout="3600" relayState="ss:mem"
    checkAddress="false" handlerSSL="true" cookieProps="https">
</code>

==== WAYF ====

Přihlášení ke službě jde nastavit buď vůči jednomu konkrétnímu IdP anebo vůči více IdP pomocí WAYFu. Použití WAYFu je častější případ. Obojí se provádí v elementu ''<SSO>''.

Chcete-li použít WAYF a dát tak uživatelům možnost si vybrat svou domovskou organizaci pro ověření, musíte z elementu ''<SSO>'' odstranit atribut ''entityID'', následně můžete v atributu ''discoveryURL'' nastavit URL adresu WAYFu. V následujícím příkladu použijeme WAYF federace eduID.cz, avšak můžete použít svůj vlastní.

<code xml>
<!-- Autentizace vůči IdP vybranému z WAYF/DS -->
<SSO discoveryProtocol="SAMLDS" discoveryURL="https://ds.eduid.cz/wayf.php">
    SAML2 SAML1
</SSO>
</code>

Budete-li chtít nastavit ověření vůči jednomu konkrétnímu IdP, nechte v elementu ''<SSO>'' pouze atribut ''entityID'' s hodnotou odpovídající //entityID// danému IdP.

<code xml>
<!-- Autentizace vůči jednomu konkrétnímu IdP -->
<SSO entityID="https://idp.example.org/idp/shibboleth">
    SAML2 SAML1
</SSO>
</code>

==== Metadata služby ====

Standardní metadata služby, která si můžete nechat vygenerovat po přístupu na ''<nowiki>https://HOSTNAME/Shibboleth.sso/Metadata</nowiki>'', je potřeba doplnit šablonou o určité údaje (např. organizace, kontakt atd.) než je možné službu zaregistrovat do federace. Korektní metadata tedy vygenerujeme následujícím postupem.

V ''shibboleth2.xml'' najdeme element ''<Handler>'' týkající se metadat:

<code xml>
<!-- Extension service that generates "approximate" metadata based on SP configuration. -->
<Handler type="MetadataGenerator" Location="/Metadata" signing="false"/>
</code>

a doplníme do něj atribut ''template="metadata-template.xml"'', kterým Shibbolethu sdělíme, odkud (''metadata-template.xml'') má číst dodatečné informace pro metadata.

<code xml>
<!-- Extension service that generates "approximate" metadata based on SP configuration. -->
<Handler type="MetadataGenerator" Location="/Metadata" signing="false" template="metadata-template.xml"/>
</code>

Soubor ''metadata-template.xml'' s doplňujícími informacemi o službě neexistuje, takže si ho musíme vytvořit a to ideálně v adresáři ''/etc/shibboleth''.

<code bash>
# Vytvoříme si XML dokument s doplňujícími informacemi o službě
vi /etc/shibboleth/metadata-template.xml
</code>

Obsah souboru ''metadata-template.xml'' upravíme tak, aby odpovídal skutečnosti.

<code xml>
<?xml version="1.0" encoding="utf-8" ?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">

  <md:SPSSODescriptor>
  
    <md:Extensions>
      <mdui:UIInfo xmlns:mdui="urn:oasis:names:tc:SAML:metadata:ui">
        <mdui:DisplayName xml:lang="en">Software Database</mdui:DisplayName>
        <mdui:DisplayName xml:lang="cs">Databáze software</mdui:DisplayName>
        <mdui:Description xml:lang="en">Software available for download.</mdui:Description>
        <mdui:Description xml:lang="cs">Seznam software ke stažení.</mdui:Description>
        <mdui:InformationURL xml:lang="en">https://sp.example.org/en/info</mdui:InformationURL>
        <mdui:InformationURL xml:lang="cs">https://sp.example.org/cs/info</mdui:InformationURL>
        <mdui:Logo height="128" width="128">https://sp.example.org/logo.png</mdui:Logo>
      </mdui:UIInfo>
    </md:Extensions>

    <md:AttributeConsumingService index="0">
      <md:ServiceName xml:lang="en">Software Database</md:ServiceName>
      <md:ServiceName xml:lang="cs">Databáze software</md:ServiceName>
      <md:ServiceDescription xml:lang="en">Software available for download.</md:ServiceDescription>
      <md:ServiceDescription xml:lang="cs">Seznam software ke stažení.</md:ServiceDescription>
      <md:RequestedAttribute FriendlyName="eppn" Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" isRequired="true"/>
      <md:RequestedAttribute FriendlyName="givenName" Name="urn:oid:2.5.4.42" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" isRequired="true"/>
      <md:RequestedAttribute FriendlyName="mail" Name="urn:oid:0.9.2342.19200300.100.1.3" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" isRequired="true"/>
      <md:RequestedAttribute FriendlyName="sn" Name="urn:oid:2.5.4.4" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" isRequired="true"/>
    </md:AttributeConsumingService>

  </md:SPSSODescriptor>
 
  <md:Organization>
    <md:OrganizationName xml:lang="en">Organizace, a. l. e.</md:OrganizationName>
    <md:OrganizationName xml:lang="cs">Organizace, z. s. p. o.</md:OrganizationName>
    <md:OrganizationDisplayName xml:lang="en">Organizace</md:OrganizationDisplayName>
    <md:OrganizationDisplayName xml:lang="cs">Organizace</md:OrganizationDisplayName>
    <md:OrganizationURL xml:lang="en">https://www.example.org/en</md:OrganizationURL>
    <md:OrganizationURL xml:lang="cs">https://www.example.org/cs</md:OrganizationURL>
  </md:Organization>

  <md:ContactPerson contactType="technical">
    <md:GivenName>Kryštof</md:GivenName>
    <md:SurName>Šáteček</md:SurName>
    <md:EmailAddress>mailto:krystof.satecek@example.org</md:EmailAddress>
  </md:ContactPerson>

</md:EntityDescriptor>
</code>

=== Finální metadata ===

Metadata jsou teď k dispozici na adrese ''<nowiki>https://sp.example.org/Shibboleth.sso/Metadata</nowiki>''.

==== Metadata federace ====

Metadata federace se nastavují v elementu ''<MetadataProvider>''. V následujících příkladech si ukážeme konfiguraci metadat federace eduID.cz a také služeb sociálních IdP jako Facebook, GitHub, Google, LinkedIn a ORCID.

Jelikož jsou metadata obou zmíněných federací digitálně podepsána, budeme tento podpis kontrolovat. Pro to si musíme nejprve stáhnout veřejný klíč.

<code bash>
# Stažení veřejného klíče pro kontrolu autentičnosti metadat
cd /etc/shibboleth && \
  wget https://www.eduid.cz/docs/eduid/metadata/metadata.eduid.cz.crt.pem
</code>

Nyní zbývá nastavit zdroj metadat a nezapomenout na ověření pravosti metadat (kontrola vůči veřejnému klíči).

Konfigurace federace eduID.cz jako zdroje metadat:

<code xml>
<!-- Metadata federace eduID.cz -->
<MetadataProvider type="XML" uri="https://metadata.eduid.cz/entities/eduid+idp"
    backingFilePath="eduid+idp.xml" reloadInterval="600">
    <MetadataFilter type="Signature" certificate="metadata.eduid.cz.crt.pem"/>
</MetadataProvider>
</code>

Konfigurace služby Social IdP (Facebook, GitHub, Google, LinkedIn, ORCID) jako zdroje metadat:

<code xml>
<!-- Metadata služby Social IdP (Facebook, GitHub, Google, LinkedIn, ORCID) -->
<MetadataProvider type="XML" uri="https://metadata.eduid.cz/entities/socialidps"
    backingFilePath="socialidps.xml" reloadInterval="600">
    <MetadataFilter type="Signature" certificate="metadata.eduid.cz.crt.pem"/>
</MetadataProvider>
</code>

Význam atributů elementu [[https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPMetadataProvider|<MetadataProvider>]]:

  * type='XML' -- metadata jsou načtena z lokálního nebo vzdáleného XML dokumentu,
  * uri -- URI metadat,
  * backingFilePath -- název (a případně i adresář, výchozí /var/cache/shibboleth/), kam se metadata uloží,
  * reloadInterval -- maximální doba mezi načtením nových metadat (v sekundách).

 Význam atributů elementu [[https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPMetadataFilter|<MetadataFilter>]]:

  * type='Signature' -- ověří XML podpis v metadatech,
  * certificate -- certifikát obsahující veřejný klíč použitý k ověření podpisu metadat.
==== Kontakt na správce služby ====

Je také vhodné nastavit kontakt na správce služby. Pokud přihlášení z nějakého důvodu selže, obvykle se zobrazí i e-mailová adresa, ne které je možné informovat správce.

E-mailová adresa správce se nastavuje v atributu ''supportContact'' u elementu ''<Errors>'':

<code xml>
<Errors supportContact="root@example.org"
    helpLocation="/about.html"
    styleSheet="/shibboleth-sp/main.css"/>
</code>

==== Vygenerování self-sign certifikátu ====

Komunikace ve federaci se šifruje, proto SP musí v metadatech uvádět svůj veřejný klíč, pomocí něhož IdP bude moci zašifrovanou zprávu (XML assertion) rozšifrovat. Jelikož ve federaci máme určitá pravidla pro publikaci metadat, je možné v metadatech používat [[:cs:tech:certificates|self-sign certifikát]] s platností např. 10 nebo více let. Není nutné používat certifikát od důvěryhodné certifikační autority, u něhož je platnost omezena na maximálně 3 roky.

V linuxové distribuci Debian je pro generování self-sign certifikátu pro Shibboleth SP přítomný shellovský skript ''shib-keygen'', který stačí spustit s odpovídajícími parametry.

<code bash>
# Vygenerování self-sign certifikátu pro Shibboleth SP
shib-keygen -h sp.example.org -y 10 -e https://sp.example.org/shibboleth
</code>

Význam jednotlivých přepínačů:

  * -h -- hostname serveru, kde služba běží,
  * -y -- platnost certifikátu v rocích,
  * -e -- entityID, pro které certifikát vystavujeme.

===== Registrace služby v metadatech federace eduID.cz =====

Nyní je potřeba službu zaregistrovat do federace [[cs:tech:metadata-publication|eduID.cz]].

===== Použití u Apache =====

==== Uživatelské atributy ====

Uživatelské atributy získá web server v proměnných, které se definují v konfiguračním souboru ''attribute-map.xml''. Například níže uvedené mapování zajistí, že proměnné obsahující [[cs:tech:attributes:givenname|křestní jméno]] a [[cs:tech:attributes:sn|příjmení]] (v SAML1 i SAML2 kódování), budou dostupné v proměnných //[[cs:tech:attributes:givenname]]// a //[[cs:tech:attributes:sn]]//.

<code xml>
# SAML1
<Attribute name="urn:mace:dir:attribute-def:givenName" id="givenName"/>
<Attribute name="urn:mace:dir:attribute-def:sn" id="sn"/>

# SAML2
<Attribute name="urn:oid:2.5.4.42" id="givenName"/>
<Attribute name="urn:oid:2.5.4.4" id="sn"/>
</code>

==== REMOTE_USER ====

V proměnné ''REMOTE_USER'' bude po přihlášení uživatele uloženo jeho uživatelské jméno. V konfiguračním souboru (''shibboleth2.xml'') lze nadefinovat mezerou oddělený seznam atributů, z nichž se Shibboleth SP pokusí uživatelské jméno získat. První proměnná (ve výchozím nastavení je: //eppn persistent-id targeted-id//), která bude obsahovat nějakou hodnotu, se použije a uloží se do proměnné ''REMOTE_USER'':

<code xml>
<ApplicationDefaults entityID="https://attributes.eduid.cz/shibboleth"
    metadataAttributePrefix="md_"
    REMOTE_USER="eppn persistent-id targeted-id">
</code>

=== eduPersonUniqueId ===

Pokud byste chtěli namísto hodnoty atributu [[cs:tech:attributes:edupersonprincipalname]] použít hodnotu uloženou v [[cs:tech:attributes:edupersonuniqueid]], bude-li k dispozici, stačí v konfiguraci Shibbolethu (''shibboleth2.xml'') přidat //uniqueId// na začátek proměnné ''REMOTE_USER'':

<code xml>
<ApplicationDefaults entityID="https://attributes.eduid.cz/shibboleth"
    metadataAttributePrefix="md_"
    REMOTE_USER="uniqueId eppn persistent-id targeted-id">
</code>

V takovém případě je ale ještě potřeba zajistit mapování atributu eduPersonUniqueId na proměnnou //uniqueId// v Shibboleth SP. To se nastavuje v konfiguračním souboru ''attribute-map.xml'':

<code xml>
<Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.13" id="uniqueId">
    <AttributeDecoder xsi:type="ScopedAttributeDecoder"/>
</Attribute>
</code>

==== Přístup po přihlášení ====

V níže uvedeném příkladu si pomocí Shibbolethu zpřístupníme adresář (''/shibbloleth'') ve webovém serveru Apache. Podle konfigurace v souboru ''/etc/shibboleth/shibboleth2.xml'' budeme následně při přístupu k danému adresáři přesměrování na WAYF anebo na konkrétní IdP, vůči kterému budou moci uživatelé provést své přihlášení.

<code apache>
<Location /shibboleth>
    AuthType            shibboleth
    Require             shibboleth
    ShibRequestSetting  requireSession  1
</Location>
</code>

Aby výše uvedená konfigurace byla funkční, je potřeba v HTTP serveru Apache aktivovat modul pro Shibboleth.

<code bash>
# Aktivace modulu pro Shibboleth SP v Apache
a2enmod shib2
</code>

Po aktivaci modulu je nutné restartovat Apache, aby si načetl nejen nově povolený modul, ale také aby si přečetl novou konfiguraci s přístupem k adresáři ''/shibboleth''.

<code bash>
# Restartování Apache pro načtení všech povolených modulů
service apache2 restart
</code>

=== Lazy sessions ===

Chceme-li u webové aplikace povolit přístup anonymním uživatelům a přihlášení vyžadovat až pro přístup k nějaké specifické části anebo pro zpřístupnění úprav, můžeme použít tzv. //lazy sessions//. To se hodí zejména pro wiki stránky, které je možné bez přihlášení bez omezení prohlížet, ale upravovat použe po přihlášení. Zároveň to umožňuje indexovat web vyhledávacím robotům různých vyhledávačů (Seznam.cz, Google atd.). Stačí //requireSession// nastavit na hodnotu //0// (nula) namísto //1// jako v předchozí části.

<code apache>
<Location /shibboleth>
    AuthType            shibboleth
    Require             shibboleth
    ShibRequestSetting  requireSession  0
</Location>
</code>

Bližší možnosti nastavení jsou k dispozici na oficiálních stránkách Shibbolethu ([[https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPApacheConfig|NativeSPApacheConfig]], [[https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPhtaccess|NativeSPhtaccess]]).