Následující návod popisuje instalaci a konfiguraci Shibboleth SP verze 2.6.0. Jako poskytovatele služby (Service Provider, SP) můžeme také použít SimpleSAMLphp, jehož instalace a konfigurace je na našich stránkách také zdokumentována.

V návodu budeme používat linuxovou distribuci Debian v jeho poslední verzi 9 s kódovým označením 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.

Návod provází kompletní instalací a konfigurací SimpleSAMLphp včetně zdrojů metadat federace eduID.cz, Hostel IdP a Social IdPs (Facebook, GitHub, Google, LinkedIn, ORCID)..

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

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

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

# Instalace Apache
apt-get install apache2

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.

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

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 https://sp.example.org/shibboleth, doporučuji změnit pouze hodnotu sp.example.org na DNS název serveru.

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

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):

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

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í.

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

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.

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

Standardní metadata služby, která si můžete nechat vygenerovat po přístupu na https://HOSTNAME/Shibboleth.sso/Metadata, 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:

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

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.

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

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.

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

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

<?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>

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

Metadata federace se nastavují v elementu <MetadataProvider>. V následujících příkladech si ukážeme konfiguraci metadat federace eduID.cz, služby Hostel IdP pro uživatele z organizací bez vlastního IdP 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íč.

# 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

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:

<!-- 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>

Konfigurace služby Hostel IdP jako zdroje metadat:

<!-- Metadata služby Hostel IdP -->
<MetadataProvider type="XML" uri="https://metadata.eduid.cz/entities/hostel"
    backingFilePath="hostel.xml" reloadInterval="600">
    <MetadataFilter type="Signature" certificate="metadata.eduid.cz.crt.pem"/>
</MetadataProvider>

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

<!-- 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>

Význam atributů elementu <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 <MetadataFilter>:

• type='Signature' – ověří XML podpis v metadatech,
• certificate – certifikát obsahující veřejný klíč použitý k ověření podpisu metadat.

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>:

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

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 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.

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

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.

Nyní je potřeba službu zaregistrovat do federace eduID.cz.

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í křestní jméno a příjmení (v SAML1 i SAML2 kódování), budou dostupné v proměnných givenName a sn.

# 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"/>

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:

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

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

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

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:

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

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í.

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

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

# Aktivace modulu pro Shibboleth SP v Apache
a2enmod shib2

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.

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

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.

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

Bližší možnosti nastavení jsou k dispozici na oficiálních stránkách Shibbolethu (NativeSPApacheConfig, NativeSPhtaccess).