cs:tech:sp:shibb-2.3

Konfigurace Shibboleth SP 2 (do verze 2.3.1)

:!: Tento návod je pro Shibboleth SP ve verzi do 2.3.1, doporučujeme použít novější verzi Shibboleth SP 2.4.x.

Předpokládejme, že následující věci jsou splněny:

  • nainstalovaný a funkční Apache 2.x s podporou SSL, konfigurační soubory v adresáři /etc/apache2
  • nainstalovaný Shibboleth SP 2, konfigurační soubory v adresáři /etc/shibboleth

Konfigurace Shibboleth

Hlavní konfigurace je umístěna v souboru shibboleth2.xml.

shibboleth2.xml

RequestMapper

V elementu RequestMapper definujeme mapování URL na aplikace. Běžně si vystačíme s defaultní aplikaci (applicationId=“default”), takže stačí pouze definovat příslušný Host element a pokud je potřeba i Path element:

<RequestMapper type="Native">
    <RequestMap applicationId="default">
        <Host name="www.example.cz" authType="shibboleth" requireSession="false">
            <Path name="secure" requireSession="true" />
        </Host>
    </RequestMap>
</RequestMapper>

Takto definované mapování znamená, že přístup k adrese https://www.example.cz/secure bude chráněn Shibbolethem (requireSession=“true”). Prodrobné informace o možnostech nastavení najdete v oficiální dokumentaci.

ApplicationDefaults

Defaultní nastavení aplikace je definováné v elementu ApplicationDefaults (atribut id=“default” odpovída atributu applicationId v nastaveni elementu RequestMapper).

<ApplicationDefaults id="default" policyId="default"
    entityID="ENTITY_ID"
    homeURL="HOME_URL"
    REMOTE_USER="eppn persistent-id targeted-id"
    signing="true" encryption="true">
 
<!-- [..] -->

Kde:

  • ENTITY_ID - identifikátor SP v rámci federace (pod kterým je veden v metadatech)
  • HOME_URL - URL aplikace

Podrobné informace o nastavení najdete v oficiální dokumentaci.

Sessions

V elementu Sessions lze nastavit různé parametry týkající se sezení (sessions) v Shibbolethu:

<Sessions lifetime="28800" timeout="3600" checkAddress="false" consistentAddress="true"
    handlerURL="/Shibboleth.sso" handlerSSL="true"
    cookieProps="; path=/; secure"
    exportLocation="http://localhost/Shibboleth.sso/GetAssertion"
    idpHistory="false" idpHistoryDays="7">
 
<!-- [..] -->

Element Sessions musí obsahovat alespoň jeden element SessionInitiator, který definuje způsob zahájení session. V kontextu federace je to obvykle přesměrování na tzv. discovery service:

<SessionInitiator type="Chaining" Location="/DS" isDefault="true" id="DS" relayState="cookie">
    <SessionInitiator type="SAML2" defaultACSIndex="1" template="bindingTemplate.html"/>
    <SessionInitiator type="Shib1" defaultACSIndex="5"/>
    <SessionInitiator type="SAMLDS" URL="DS_URL" />
</SessionInitiator>

Kde:

MetadataProvider

V elementu MetadataProvider se definuje způsob získávání federačních metadat. Víc informací najdete v sekci o metadatech.

CredentialResolver

V elementu CredentialResolver definujeme cesty ke klíči a certifikátu, které SP používá při podepisování své komunikace:

<CredentialResolver type="File" 
    key="/etc/ssl/private/www.example.cz.key.pem" 
    certificate="/etc/ssl/certs/www.example.cz.crt.pem" />

Atributy

V souboru attribute-map.xml definujeme mapování příchozích atributů na lokální proměnné. Ve výchozi verzi konfiguračního souboru najdeme zakomentované definice běžných atribitů, stačí pouze odkomentovat ty potřebné. Víc informací v oficiální dokumentaci.

Příchozí atributy lze dodatečně kontrolovat a zpracovávat nastavením ruzných pravidel a filtrů v souboru attribute-policy.xml.

Startovací skript

V distribuci jsou přibaleny startovací skripty pro Debian (shibd-debian) a Red Hat (shibd-redhat). Pokud žádný z nich nevyhovuje, mužou alespoň posloužit jako inspiraci při psaní vlastního skriptu.

Konfigurace Apache

Apache musí načíst modul pro Shibboleth. Pokud jste instalovali z RPM, v adresáři /etc/apache2/conf.d by měl být soubor shib.conf. Pokud tam není, zkopírujte soubor /etc/shibboleth/apache22.config na jeho místo, nebo jinak zajistěte, že Apache bude číst direktivy v něm umístěné. V podstatě nejdůležitější je v něm direktiva, která zajistí natažení příslušného modulu:

LoadModule mod_shib /usr/lib64/shibboleth/mod_shib_22.so

Dále je potřeba definovat, pro které dotazy bude Shibboleth “aktivní”. Například:

<Location /secure/>
    AuthType shibboleth
    require shibboleth
</Location>

V tomto případě Shibboleth zpracovává všechny dotazy pro daný adresář. Neznamená to nutně, že je adresář chráněn. K tomu je potřeba vyžádovat vytvoření Shibboleth session a to tak, že v RequestMapper elementu definujeme pro daný adresář atribut requireSession=“true”, viz výše.

Existují různé způsoby, jak řídit přístup k adresářům - na úrovní Apache, na úrovni Shibbolethu nebo na úrovni samotné aplikace. Běžně se používá výše uvedený způsob - v Apachi pouze “označíme” příslušné adresáře a veškerá nastavení pak provádíme v konfiguraci Shibbolethu. Víc informací najdete v oficiální dokumentaci.

Pokročilá nastavení

Lazy sessions

Požadovat autentizaci po všech uživatelích je vhodné například u intranetu, ale u veřejných webserverů je častější případ, kdy si uživatelé mohou stránky anonymně prohlížet, a přihlásit se až v okamžiku, kdy potřebují provést změny nebo získat přístup k privátním informacím. To také umožňuje, aby prohledávací roboti vyhledávacích serverů (Google, Seznam atd.) mohli stránky navštívit a indexovat.

Pro tento případ Shibboleth podporuje tzv. lazy sessions. Uživatelé mohou na stránky anonymně a aktivují autentizaci v případě potřeby kliknutím na speciální odkaz. K tomu je potřeba vypnout požadavek na vytvoření session (ShibRequireSession Off):

  <Location /app/>
    AuthType shibboleth
    ShibRequireSession Off
    require shibboleth
  </Location>

Při tomto nastavení je uživatel vpuštěn na stránku bez nutnosti autentizace. Pokud je potřeba uživatele přihlásit, lze vytvořit “Login” odkaz s URL:

https://sp.example.cz/Shibboleth.sso/Login?target=https://sp.example.cz/app/privatni/

Po kliknutí na odkaz se spustí Login session initiator (definovaný v SessionInitiator elementu). Po úspěšné autentizaci je uživatel přesměrován na URL obsažene v target parametru.

Lze nastavit i další parametry, viz oficiální dokumentace.

Vynechání WAYF

Pro intranetové aplikace je zbytečné obtěžovat uživatele cestou přes WAYF, můžeme je poslat přímo na příslušný IdP. Toho dosáhneme tak, že v konfiguraci Apache uvedeme

     AuthType shibboleth
     ShibRequireSessionWith mujIdP

a v shibboleth2.xml vytvoříme další SessionInitiator s odpovídajícím identifikátorem:

<SessionInitiator id="mujIdP" Location="/WAYF/moje" type="SAML2" relayState="cookie"
  template="bindingTemplate.html" defaultACSIndex="1" 
  entityID="https://idp2.ics.muni.cz/idp/shibboleth"    />

kde atribut id musí odpovídat identifikátoru z direktivy ShibRequireSessionWith, atributem Location volíme speciální odkaz pro aktivaci pokud používáme lazy sessions, a v atributu entityID musí být příslušné entityID uvedé pro IdP v metadatech federace.

Virtuální webservery

Virtuální webservery je možné použít dvěma různými způsoby:

  • více samostatných SP na jedné instalaci Apache
  • jeden sdílený SP pro více DNS jmen
Více samostatných SP na jedné instalaci Apache

Pokud potřebujete mít na jednom Apache více virtuálních webserverů a na nich používat Shibboleth, ale každý je logicky samostatným SP, zaregistrujte každý zvlášt do federace, tj. mějte pro něj samostatný certifikát a přidejte ho do metadat federace.

V souboru shibboleth2.xml pak vytvořte pro druhý a každý další SP další aplikaci. Nejdřív v RequestMap přidejte další server, např.:

        <RequestMap applicationId="default">
            <Host name="www.moje.cz" />
            <Host name="www.druhy.cz" applicationId="druhy" />
        </RequestMap>

tj. první SP je pojmenován “default” a druhý “druhy”. Pak na konci tagu ApplicationDefaults vytvořte druhou aplikaci definováním rozdílů oproti první:

        <ApplicationOverride id="druhy" entityID="https://www.druhy.cz/shibboleth/eduid/sp" homeURL="http://www.druhy.cz/">
            <CredentialResolver type="File" key="/etc/apache2/ssl/druhykey.pem" certificate="/etc/apache2/ssl/druhycert.pem"/>
        </ApplicationOverride>
Jeden sdílený SP pro více DNS jmen

Pokud máte pro stejné stránky zaregistrováno více DNS jmen, např. www.moje.cz, moje.cz, moje.cesnet.cz, ale na všech chcete použít stejný SP, pak v konfiguraci Apache vytvořte virtuální webserver s příslušnými aliasy, tj.:

<VirtualHost 147.251.9.183:443>
    ServerName www.moje.cz
    ServerAlias moje.cz
    ServerAlias moje.cesnet.cz

a do metadat federace je třeba zaregistrovat jen jeden SP, ale ten musí mít pro každé DNS jméno definovaný tag AssertionConsumerService. Nejjednodušší jak taková metadata vyrobit je využít šablony metadat. Tedy do shibboleth2.xml přidejte:

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

a do souboru sablona_moje.xml přidejte to, co chcete přidat do metadat, tedy určitou variaci na:

<?xml version="1.0" encoding="utf-8" ?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">
  <md:SPSSODescriptor>
    <!-- pridani endpointu pro alternativni DNS jmena -->
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://moje.cz/Shibboleth.sso/SAML2/POST" index="1"/>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://moje.cesnet.cz/Shibboleth.sso/SAML2/POST" index="2"/>
  </md:SPSSODescriptor>
 
  <md:Organization>
    <md:OrganizationName xml:lang="en">My organization</md:OrganizationName>
    <md:OrganizationName xml:lang="cs">Moje organizace</md:OrganizationName>
    <md:OrganizationDisplayName xml:lang="en">My organization</md:OrganizationDisplayName>
    <md:OrganizationDisplayName xml:lang="cs">Moje organizace</md:OrganizationDisplayName>
    <md:OrganizationURL xml:lang="en">http://www.moje.cz/en</md:OrganizationURL>
    <md:OrganizationURL xml:lang="cs">http://www.moje.cz/cs</md:OrganizationURL>
  </md:Organization>
  <md:ContactPerson contactType="technical">
    <md:GivenName></md:GivenName>
    <md:SurName>První</md:SurName>
    <md:EmailAddress>mailto:ja@moje.cz</md:EmailAddress>
  </md:ContactPerson>
</md:EntityDescriptor>

a nechte si metadata vygenerovat přístupem na https://www.moje.cz/Shibboleth.sso/Metadata .To DNS jméno v URL generujícím metadata je důležité, protože automaticky bude do metadat vygenerována AssertionConsumerService pro toto DNS jméno. Ostatní DNS jména je třeba přidat přes šablonu.

Závěr a testování

Po ukončení konfigurace je potřeba restartovat Apache a nastartovat Shibboleth daemon. Instalaci otestujte přístupem na adresu

https://HOSTNAME/Shibboleth.sso/Status

a pokud je vše v pořádku, mělo by se zobrazit “ok”. V opačném případě je možné, že SP sice funguje správně, ale v konfiguraci existuje omezení na IP adresu, z které je možné se dotázat, viz oficiální dokumentace.

Zkuste zadat do prohlížeče “chráněnou” adresu:

https://HOSTNAME/secure

V případě, že máte vše v pořádku budete přesměrováni k WAYF/DS stránce, kde můžete vybrat svou domovskou organizaci a dokončit přihlašení. Po přihlášení budete vpuštěni do chráněné oblasti. Nezapoměňte do adresáře /secure vložit nějaký soubor, nejlépe index.html s nějakým textem anebo pokud web server podporuje PHP - index.php s obsahem:

<?php
phpinfo();
?>

Pokud chcete zjistit další informace, použijte handler Session:

https://HOSTNAME/Shibboleth.sso/Session

Zobrazuje informace o aktuální session. Je možné zobrazit i hodnoty atributu, ale k tomu je potřeba v shibboleth2.xml nastavit atribut showAttributeValues u příslušnýho Handler elementu:

<!-- Session diagnostic service. -->
<Handler type="Session" Location="/Session" showAttributeValues="true" />

:!: U obou handlerů - status a session - je možné omezit přístup přes seznam IP adres, víc informací najdete v oficiální dokumentaci.

Last modified:: 2017/02/10 07:02