====== WAYF/DS - návod pro správce SP ======

<WRAP tip>
Je-li služba **v interní federaci** (např. //CESNET-int//), která obsahuje pouze jediné IdP, **nemá smysl používat WAYF**! V takovém případě **je potřeba nastavit autentizaci vůči tomu jednomu konkrétnímu IdP** a vyhnout se použití WAYFu.

Skript, který kontroluje parametr ''return'', nestahuje metadata interních federací, a proto kontrola končí chybou!
</WRAP>

Obecný popis služby WAYF/DS najdete na [[:cs:tech:wayf|této stránce]]. Tento návod popisuje, jakým způsobem je možné ovlivnit chování služby WAYF/DS tak, aby ještě lépe vyhovovala individuálním potřebám právě Vaší služby. Služba WAYF/DS v základním nastavení zobrazuje seznam všech institucí, se kterými je samotná služba registrována ve stejné federaci. Pokud chcete zobrazit jiný výběr institucí, je potřeba využít generátor filtrů.

===== Generátor filtrů =====

Generátor filtrů je aplikace, která Vám umožní změnit seznam zobrazených poskytovatelů identit (Identity Provider, IdP). Na výstupu této aplikace získate textový řetězec, tzv. filtr, který je nutné zakomponovat do konfigurace služby (Service Provider, SP). Existují dvě možnosti, jak filtr aplikovat, buď jako jednoduchý filtr nebo jako externí filtr.

Generátor filtrů naleznete na stránce [[https://ds.eduid.cz/filter.php]]. 

==== Jednoduchý filtr ====
K volání služby WAYF/DS přidáme parametr //filter// a jako hodnotu dosadíme filtr z generátoru. Tento jednoduchý způsob je vhodný pro kratší filtry. Starší prohlížeče podporovaly URL dlouhé okolo 2000 znaků. Různé bezpečnostní moduly mohou více omezovat maximální délku URL (např. PHP rozšíření Suhosin zkracuje v základním nastavení délku URL na 255 znaků).

Příklad přímého filtru:
<code>
https://ds.eduid.cz/wayf.php?filter=eyAgImFsbG93SG9zdGVsIjogdHJ1ZSwgImFsbG93SG9zdGVsUmVnIjogZmFsc2V9
</code>

==== Externí filtr ====
Vygenerovaný filtr si uložíme do souboru, který umístíme na vhodný webový server (ideálně webový server samotné služby). URL tohoto souboru předáme službě jako hodnotu parametru //efilter//.

Příklad externího filtru:
<code>
https://ds.eduid.cz/wayf.php?efilter=https://www.example.com/wayf-filter.txt
</code>

Soubor ''wayf-filter.txt'' obsahuje filtr vytvořený generátorem:
<code>
eyAgImFsbG93SG9zdGVsIjogdHJ1ZSwgImFsbG93SG9zdGVsUmVnIjogZmFsc2V9
</code>

==== Filtrování skupin organizací/IdP ====

Pole zaškrtávacích tlačítek "Vyberte skupiny" slouží ke zobrazení poskytovatelů identit z organizací registrovaných v uvedených federacích ([[:|eduID.cz]], [[http://www.edugain.org|eduGAIN]], atd.). Pokud nezvolíte žádnou skupinu, bude WAYF/DS zobrazovat pouza ta IdP, která jsou ve federaci s Vaší službou (ve většině případů tedy IdP z federace eduID.cz). Tuto skupinu je možné dále omezit zobrazením pouze vybraných IdP vizte dále.

==== Filtrování pomocí entity kategorií ====

Zobrazený seznam lze filtrovat podle hodnoty entity kategorie. Ze šedého rámečku přetáhněte příslušnou entity kategorii do zeleného nebo červeného rámečku. Zelený rámeček funguje jako pozitivní filtr. Zobrazená IdP musí mít nastaveny všechny entity kategorie v zeleném rámečku. Červený filtr funguje jako negativní filtr. Zobrazená IdP nesmí mít žádnou entity kategorii z červeného rámečku. 

==== Filtrování jednotlivých organizací/IdP ====

Pole zaškrtávacích tlačítek "Vyberte IdP" slouží k jemnějšímu nastavení povolených organizací na Vaší službě. Můžete buď vybrat jednotlivá IdP, která se zobrazí, nebo nechat zobrazit všechna IdP kromě vybraných.Tento seznam lze generovat pro každou skupinu IdP zvlášť.



===== Nastavení přihlašování =====

WAYF/DS umožňuje pracovat se stránkami, které pro svůj přístup vyžadují přihlášeného uživatele, nebo
se stránkami, které umožňují přístup i nepřihlášenému uživateli a přihlášení se děje až na vyžádání.

==== Nastavení nutnosti přihlášení ====

=== Shibboleth SP ===

V souboru ''shibboleth2.xml'' nastavte atribut ''discoveryProtocol'' u elementu ''<SSO>'' na URL služby WAYF/DS.

V případě zjednodušeného zápisu u novějších verzí SP:
<code xml>
<SSO discoveryProtocol="SAMLDS" 
    discoveryURL="https://ds.eduid.cz/wayf.php?filter=eyJhbGxvd0hvc3RlbCI6dHJ1ZSwiYWxsb3dIb3N0ZWxSZWciOnRydWV9Cg==&amp;lang=en">
    SAML2 SAML1
</SSO>
</code>

Konfigurace v //Apachi//:

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

Musíte u Apache povolit modul //shib2//:

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

A následně nahrát znovu konfiguraci //Apache//:

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

To je vše. Při vstupu na stránku vyžadující autentizaci bude uživatel přesměrován na novou službu DS.

==== Přihlášení až na vyžádání (lazy session) ====

=== Shibboleth SP ===

U Shibboleth SP se přihlášení na vyžádání zařídí pouze změnou hodnoty ''requireSession'' z ''1'' na ''0'':

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

''<SSO>'' nastavte stejně jako v případě nucené autentizace. Do stránky, která obsahuje odkaz na přihlášení, vložte odkaz ke stažení javascriptové knihovny DS (soubor //ds.js//):

<code html>
<head>
 ...
 <script type="text/javascript" src="https://ds.eduid.cz/ds.js"></script>
 ...
</head>
</code>

U Shibbolethu se standardně používá pro přihlášení ''/Shibboleth.sso/Login'' a odkaz na přihlášení ve stránce tedy vypadá takto:

<code html>
<a href="/Shibboleth.sso/Login" onclick="startOverlay(event)">Přihlásit</a>
</code>

=== SimpleSAMLphp ===

U SimpleSamlPhP musí cíl odkazu ukazovat na stejnou hodnotu jako parametr ''discoURL'' v konfiguračním souboru ''authsources.php''.

Ukázka konfigurace ''authsources.php'':
<code>
'default-sp' => array(
    'saml:SP',
    'entityID' => 'https://sp.example.com/simplesaml/',
    'idp' => NULL,
    'discoURL' => 'https://ds.eduid.cz/wayf.php',
    'privatekey' => 'example.key'
),
</code>

a příklad příslušného odkazu na přihlášení pro SimpleSamlPhP:
<code>
<a href="/simplesaml/module.php/core/authenticate.php" onclick="startOverlay(event)">Přihlásit</a>
</code>

===== Kontrola parametru return =====

<WRAP info>
**NEPOUŽÍVAT WAYF PRO INTERNÍ FEDERACE S JEDNÍM IDP!**

Pro interní federace (např. CESNET-int) se nezpracovávají metadata pro kontrolu parametru ''return'', takže daná kontrola končí vždy chybou.
</WRAP>

Z bezpečnostních důvodů kontroluje WAYF hodnotu parametru return. Je to URL, na které je přesměrován prohlížeč uživatele po vybrání IdP. Hodnota parametru musí odpovídat údaji v metadatech pro dané SP. Pokud se liší, vypíše WAYF chybové hlášení a neumožní uživateli pokračovat v přihlašování.

Jak kontrola probíhá:
  - Pokud služba v metadatech definuje elementy <idpdisc:DiscoveryResponse /> musí hodnota parametru return odpovídat jedné z hodnot uvedené v attributu Location.
  - Jinak prochází všechny elementy <md:AssertionConsumerService />, doména uvedená v atributu Location musí být shodná s hodnotou v parametru return.