====== Implementace federativní autentizace u MetaLib ======

U systému MetaLib vyvíjeného firmou Ex Libris je implementována podpora autentizace v prostředí Shibboleth/SAML. Využívá se Shibboleth Service Provider, doporučováno je použití jeho aktuální verze. 

Implementace autentizace pomocí Shibboleth probíhá v těchto krocích:
  * instalace a konfigurace Shibboleth Service Providera
  * úprava konfigurace u autentizačního modulu Patron Directory Services (PDS)

Nastavení je zkodumentováno v manuálu //Patron Directory Services Guide// dostupném v [[http://docs.exlibrisgroup.com/docportal/logon.php|Dokumentačním Centru Ex Libris]] a v návodu [[http://www.exlibrisgroup.org/display/MetaLib/Building+and+Configuring+Shibboleth+2.3+in+MetaLib+4+(Solaris+10)|Building and Configuring Shibboleth 2.3 in MetaLib 4]] od Ere Maijala v El Commons. V následujícím textu jsou ještě doplněny podrobnosti.

Implementace autentizace Shibboleth vyžaduje běh MetaLib na standardních HTTP, HTTPS portech 80, 443. Resp. při provozu MetaLib na nestandardních portech jsou nutné rozsáhlé úpravy v programových souborech modulu PDS. 

Autentizační modul PDS podporuje zařazení uživatele pouze do jedné skupiny uživatelů, nepodporuje vícenásobné afiliace uživatelů. U organizací, kde uživatelé mají vícenásobné afiliace, je problém možné částečně řešit uživatelsky nastavitelnou primární afiliací na úrovni Identity Providera organizace. Při autorizaci pak MetaLib používá primární afiliaci nastavenou uživatelem u IdP.

MetaLib u jednoho zdroje podporuje pouze jeden způsob autorizace - buď na základě IP adres nebo na základě skupiny uživatelů v rámci Shibboleth. Kombinace autorizace podle IP adresy a pomocí Shibboleth je možná jedině zkopírováním IRD zdroje - u jednoho zdroje se pak použije IP filtr a u druhého uživatelská skupina (Secondary Affiliation v IRD) v rámci Shibboleth.

Na straně Identity Providera budete pro Service Providera u MetaLib potřebovat nastavit uvolňování atributů: 
  * ''eduPersonPrincipalName''
  * ''cn''
  * ''eduPersonScopedAffiliation'' nebo ''eduPersonEntitlement''
  * volitelně a optimálně také ''mail''

Popisovaná konfigurace PDS je kompatibilní s PDS verze 2.0.1.00001 před provedením upgrade popsaným v dokumentu //Patron Directory Services Upgrade Guide// (spuštění skriptu ''pds_upgrade_kit'').


 

===== Instalace a konfigurace Shibboleth Service Providera =====

Pro instalaci shibbolethového Service Providera je potřeba mít u Apache MetaLib zprovozněný HTTPS.

MetaLib je typicky provozován na Linux Red Hat OS. Instalace a konfigurace Shibboleth Service Providera (SP) v prostředí Linux Red Hat je popsána na stránce - [[https://www.eduid.cz/wiki/eduid/admins/howto/deploy/sp/install/rpms/index|Instalace Shibboleth SP 2 z RPMS balíků]]. Alternativně je možné využít instalaci pomocí yum doporučovanou na stránkách SWITCH - [[https://www.switch.ch/aai/docs/shibboleth/SWITCH/2.3/sp/deployment/linux-rpm.html|Deployment of Shibboleth Service Provider (SP) 2.3.1 on Linux with RPM packages]].


Při instalaci pomocí yum z repozitáře
''http://download.opensuse.org/repositories/security:/shibboleth/'' vyberte
balíček pro verzi Vašeho Red Hatu, ale musíte použít 32bitovou verzi. 32bitový Shibboleth SP nainstalujete pomocí:
<code>
yum install shibboleth.i386
</code>

Ex Libris u MetaLib používá 32bitový Apache 2.0. Z balíčku pro 32-bitový Red Hat 4 na adrese
''http://download.opensuse.org/repositories/security:/shibboleth/RHEL_4/i386/''
vytáhněte modul ''mod_shib_20.so'' (třeba pomocí mc nebo rpm2cpio) a umístěte jej do adresáře ''/exlibris/metalib/m4_1/product/local/apache/module''s. Knihovny, které
modul ''mod_shib_20.so'' potřebuje, už jsou v systému z shibboleth.i386 balíčku pro verzi Vašeho Red Hatu.

Novější verze a aktualizace používají už Apache 2.2. Potom už není třeba stahovat balíček pro starší Red Hat, ale do adresáře s moduly pro Apache překopírujte modul ''/usr/lib/shibboleth/mod_shib_22.so''.

==== Nastavení konfiguračních souborů ====

Po instalaci SP je třeba upravit nastavení v konfiguračních souborech //shibboleth2.xml, attribute-map.xml//. Nastavení popisuje návod na stránce eduID.cz - [[https://www.eduid.cz/wiki/eduid/admins/howto/deploy/sp/config/common/index|Konfigurace Shibboleth SP 2.4.x]]. Zde uvádíme shrnutí návodu se specifiky pro MetaLib.

V ''shibboleth2.xml'' proveďte následující úpravy:

  * V sekci ''<ApplicationDefaults>'' nastavte entity ID, např. 
    <code>
      entityID="https://orca.ruk.cuni.cz/shibboleth" </code>

  * V sekci v ''<Sessions>'' upravte: 
    <code>
     handlerSSL="true" 
     cookieProps="; path=/; secure" </code>

  * v sekci ''<SSO>'' upravte:
    <code>
      entityID="https://cas.cuni.cz/idp/shibboleth"
      discoveryURL="https://ds.eduid.cz/wayf.php" </code>

  * pro přeskakování WAYF, odmažte ''entityID'' z ''<SSO>''

  * v sekci ''<Errors>'' doplňte e-mailovou adresu pro hlášení chyb, např.:
    <code>
      supportContact="shibb@domena.cz" </code>

  * odkomentujte sekci ''<MetadataProvider>'' uvedenou poznámkou "Example of remotely suplied ... metadata"

  * v sekci ''<MetadataProvider>'' zakomentujte nebo smažte ''<MetadataFilter type="RequireValidUntil" ... >''

  * v sekci ''<MetadataProvider>'' nastavte:
    <code>
      uri="https://metadata.eduid.cz/entities/eduid+idp"
      backingFilePath="/etc/shibboleth/eduid-metadata.xml" 
      reloadInterval="600" </code>

  * v poduzlu ''<MetadataFilter type="Signature">'' sekce ''<MetadataProvider>'' nastavte:
    <code>
      certificate="metadata.eduid.cz.crt.pem" </code>

Do souboru ''sp-cert.pem'' nahrajte certifikát serveru a do souboru ''sp-key.pem'' nahrajte privátní klíč k certifikátu serveru.

Stáhněte metadata federace:
<code>
  wget -O eduid-metadata.xml 'https://metadata.eduid.cz/entities/eduid+idp'
</code>

Stáhněte certifikát k ověrování podpisu metadat:
<code>
  wget 'https://www.eduid.cz/docs/eduid/metadata/metadata.eduid.cz.crt.pem'
</code>


V případě potřeby upravte ''attribute-map.xml''. 


Korektnost nastavení konfiguračních souborů ověříte pomocí:
<code>
# shibd -t
</code>

Konfigurace by měla být korektní, pokud výstup obsahuje řádek:
<code>
overall configuration is loadable, check console for non-fatal problems
</code>

Démona Shibboleth spustíte:
<code>
su -
# service shibd start
</code>

==== Úprava konfigurace Apache ====

Úprava konfigurace Apache pro základní doplnění autentizace pomocí Shibboleth je popsána na stránkách eduID.cz - [[https://www.eduid.cz/wiki/eduid/admins/howto/deploy/sp/config/common/index#konfigurace_apache|Konfigurace Apache]].

V případě MetaLib je Apache umístěn typicky v adresáři ''/exlibris/metalib/MLVERSION/apache'', kde ''MLVERSION'' je kód verze a instance MetaLib, např. ''m4_1'', či ''m4_3''. 


Do konfiguračního souboru httpd.conf přidejte sekci:
<code>
#Shibbleth mod_shib
LoadModule mod_shib "/exlibris/metalib/MLVERSION/product/local/apache/modules/mod_shib_20.so"
ShibConfig /etc/shibboleth/shibboleth2.xml
<Files *.sso>
   SetHandler shib-handler
</Files>

Alias /shibboleth-sp/main.css /usr/share/doc/shibboleth-2.4/main.css
Alias /shibboleth-sp/logo.jpg /usr/share/doc/shibboleth-2.4/logo.jpg
</code>


Pokud používáte už Apache 2.2, použijete v konfiguraci modul ''mod_shib_22.so'' místo ''mod_shib_20.so''.


Pro aktivaci shibbolethové autentizace u PDS je pořeba v sekci ''<Location /pds>'' konfiguračního souboru ''httpd.conf'' doplnit:
<code>
AuthType shibboleth
ShibRequireSession Off
require shibboleth
ShibUseHeaders on
</code>

Za sekci <Location /pds> doplňte:
<code>
<Location /shib>
 AuthType shibboleth
 ShibRequireSession On
 ShibUseHeaders on
 require valid-user
 Options Indexes MultiViews ExecCGI FollowSymlinks
 ForceType application/x-httpd-cgi
</Location>
</code>


Na závěr je potřeba otestovat korektnost konfigurace a restartovat Apache:
<code>
# /exlibris/metalib/MLVERSION/apache/bin/apachectl configtest
# /exlibris/metalib/MLVERSION/apache/bin/apachectl stop
# /exlibris/metalib/MLVERSION/apache/bin/apachectl_auto
</code>

==== Vynechání WAYF ====

V případě instalace MetaLib pro uživatele jedné organizace je vhodné nastavit přihlašování uživatelů s vynecháním WAYF. Nastavení je popsáno na stránkách eduID.cz - [[https://www.eduid.cz/wiki/eduid/admins/howto/deploy/sp/config/common/index#vynechani_wayf|Vynechání WAYF]].

==== Otestování ====

Korektnost implementace Service Providera je možné otestovat podle popisu na stránkách eduID.cz - [[https://www.eduid.cz/wiki/eduid/admins/howto/deploy/sp/config/common/index#zaver_a_testovani|Závěr a testování]].
==== Registrace metadat ==== 

Umístění metadat Service providera je popsáno na stránkách eduID.cz - [[https://www.eduid.cz/wiki/eduid/admins/howto/metadata/index#shibboleth_sp_2.x|Jak vytvořit metadata pro Shibboleth SP 2.x]].

U MetaLib, který je využíván uživateli více organizací, je Service Provider vhodný připojit do federace. Na otestování je možné využít federaci
czTestFed, pro ostrý provoz pak federaci eduID.cz. Pro registraci Service Providera je potřeba, aby organizace měla jmenované [[https://www.eduid.cz/wiki/eduid/join/join-admin-contact|administrativní]]
a [[https://www.eduid.cz/wiki/eduid/join/tc_org|technické kontakty]]. 

Celý postup publikace metadat pro eduID.cz je shrnutý na stránce [[https://www.eduid.cz/wiki/eduid/admins/metadata/index|Správa a publikace metadat]].
===== Konfigurace PDS a závěrečná nastavení =====

V konfiguraci PDS se nastaví jako autentizační metoda Shibboleth. Typicky se autentizační metoda změní z LDAP na Shibboleth. Podle potřeby se upraví nastavení mapovaní uživatelských skupin pro autorizaci. Konfigurační soubory PDS jsou v adresáři //~metalib/MLVERSION/pds/conf_tables//. Nastavení je zkodumentováno v manuálu //Patron Directory Services Guide//.

V programových souborech PDS (adresář /exlibris/metalib/m4_x/pds/service_proc) je potřeba provést následující úpravy:

  * v ''shib.pl'' upravit ''Shib_Application_ID'' na ''Shib-Application-ID''
  * v ''MLVERSION/ins01/www_v_cze/navigation-guest'' a ''/www_v_eng/navigation-guest'' upravit odkaz pro přihlášení ze ''&server_pds'' na ''https://HOSTNAME/shib/INSTITUTION/pds_main'' , kde HOSTNAME je hostname serveru a INSTITUTION je kód metalibové instituce, např. LAS //(Od verze Metalib 4.4.1 (685) není třeba tuto úpravu provádět.)//

V adresáři ''htdocs'' Apache pro MetaLib vytvořte adreář ''shib''. V tomto adresáři vytvořte podadresář s názvem metalibové instituce. 
Do adresáře s názvem metalibové instituce nalinkujte soubor ''/exlibris/metalib/MLVERSION/pds/program/pds_main''.
//Pro verze Metalib starší než 4.4.1 (685)// do adresáře s názvem metalibové instituce nakopírujte soubor ''/exlibris/metalib/MLVERSION/pds/program/pds_main'' a na začátek zkopírovaného souboru přidejte řádek:
<code>
  use lib "$ENV{metalib_dev}/pds/program";
</code>






V konfiguračních souborech PDS proveďte následující úpravy. Namísto ''INSTITUTE'' uveďte vždy kód metalibové instituce.

V souboru ''tab_service.INSTITUTE'' upravte:
  * v sekci ''[LOAD_LOGIN]''
    <code>
      program = shib.pl
      params = shib_INSTUTITE.conf </code>
  * v sekci ''[BOR_INFO]''
    <code>
      program = shib_bor_info.pl </code>
  * v sekci ''[SHIB_LOGOUT]'' uveďte
    <code>
      params = http://HOSTNAME/Shibboleth.sso/Logout  </code>
  * pokud je u IdP Vaší organizace implementovaný Single Logout plug-in, můžete v sekci ''[SHIB_LOGOUT]'' uvést adresu IdP pro Single Logout, např.
    <code>
      params = https://idp.lib.cas.cz/idp/Logout </code>

Vzorový ''tab_service.INSTITUTE'' může vypadat např. takto:
<code>
[LOAD_LOGIN]
 program = shib.pl
 params = shib_las.conf
[END]
[BOR_INFO]
 program = shib_bor_info.pl
[END]
[INSTITUTE_DISPLAY]
 code = LAS
 desc = Akademie v&#283;d &#268;R
 lang = ENG
[END]
[SHIB_LOGOUT]
 params = http://metalib.lib.cas.cz/Shibboleth.sso/Logout
[END]
</code>


Vytvoře soubor ''shib_INSTITUTE.conf'' s mapováním atributů, např.:
<code>
[SHIB_ATTRIBUTES]
 HTTP_CN = z312_name
 HTTP_MAIL = z312_email_address
 HTTP_EPPN = source_id
 HTTP_ENTITLEMENT = z312-group
[END]
[DEFAULTS]
 portal_name,LAS
 z312_con_lng,CZE
 expiry_date,today+2y
 z312-resource-status,A
[END]
</code>

Všimněte si mapování ''HTTP_ENTITLEMENT = z312-group'', které slouží pro nastavení přístupu oprávněných uživatelů k placeným zdrojům. Konkrétní mapování se řeší v samostatném souboru, který si vytvořte v adresáři ''conf_table'': ''INSTITUTE.tags'' (např. ''LAS.tags''), který vypadá třeba takto:
<code>
  [ATTRIBUTES_MAPPING]
    z312-group,member@lf1.cuni.cz = group,LF1
  [END]
</code>

V tomto příkladu hledá MetaLib hodnotu ''member@lf1.cuni.cz'' a v případě, že ji nalezne, nastaví uživateli skupinu ''LF1''. Tuto skupinu pak stačí nastavit u MetaLib zdroje do pole ''Secondary Affiliation''. Právo prohledávat tento zdroj má pak pouze uživatel s touto skupinou. Detaily k mapování a nastavení naleznete v dokumentu //Patron Directory Services Guide// a //MetaLib Resource Management Guide//.

===== Shrnutí nadstandardních úprav =====


  * úprava ''Shib_Application_ID'' na ''Shib-Application-ID'' ve skriptu ''shib.pl''
  * úprava skriptu ''apachectl'' pro korektní spouštění Apache