cs:tech:apps:metalib

Implementace podpory pro Shibboleth 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 Dokumentačním Centru Ex Libris a v návodu 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 - Instalace Shibboleth SP 2 z RPMS balíků. Alternativně je možné využít instalaci pomocí yum doporučovanou na stránkách SWITCH - 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í:

yum install shibboleth.i386

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/modules. 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 - 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ř.
      entityID="https://orca.ruk.cuni.cz/shibboleth" 
  • V sekci v <Sessions> upravte:
     handlerSSL="true" 
     cookieProps="; path=/; secure" 
  • v sekci <SSO> upravte:
      entityID="https://cas.cuni.cz/idp/shibboleth"
      discoveryURL="https://ds.eduid.cz/wayf.php" 
  • pro přeskakování WAYF, odmažte entityID z <SSO>
  • v sekci <Errors> doplňte e-mailovou adresu pro hlášení chyb, např.:
      supportContact="shibb@domena.cz" 
  • 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:
      uri="https://metadata.eduid.cz/entities/eduid+idp"
      backingFilePath="/etc/shibboleth/eduid-metadata.xml" 
      reloadInterval="600" 
  • v poduzlu <MetadataFilter type=“Signature”> sekce <MetadataProvider> nastavte:
      certificate="metadata.eduid.cz.crt.pem" 

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:

  wget -O eduid-metadata.xml 'https://metadata.eduid.cz/entities/eduid+idp'

Stáhněte certifikát k ověrování podpisu metadat:

  wget 'https://www.eduid.cz/docs/eduid/metadata/metadata.eduid.cz.crt.pem'

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

Korektnost nastavení konfiguračních souborů ověříte pomocí:

# shibd -t

Konfigurace by měla být korektní, pokud výstup obsahuje řádek:

overall configuration is loadable, check console for non-fatal problems

Démona Shibboleth spustíte:

su -
# service shibd start

Úprava konfigurace Apache

Úprava konfigurace Apache pro základní doplnění autentizace pomocí Shibboleth je popsána na stránkách eduID.cz - 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:

#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

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:

AuthType shibboleth
ShibRequireSession Off
require shibboleth
ShibUseHeaders on

Za sekci <Location /pds> doplňte:

<Location /shib>
 AuthType shibboleth
 ShibRequireSession On
 ShibUseHeaders on
 require valid-user
 Options Indexes MultiViews ExecCGI FollowSymlinks
 ForceType application/x-httpd-cgi
</Location>

Na závěr je potřeba otestovat korektnost konfigurace a restartovat Apache:

# /exlibris/metalib/MLVERSION/apache/bin/apachectl configtest
# /exlibris/metalib/MLVERSION/apache/bin/apachectl stop
# /exlibris/metalib/MLVERSION/apache/bin/apachectl_auto

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 - Vynechání WAYF.

Otestování

Korektnost implementace Service Providera je možné otestovat podle popisu na stránkách eduID.cz - Závěr a testování.

Registrace metadat

Umístění metadat Service providera je popsáno na stránkách eduID.cz - 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é administrativní a technické kontakty.

Celý postup publikace metadat pro eduID.cz je shrnutý na stránce 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:

  use lib "$ENV{metalib_dev}/pds/program";

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]
      program = shib.pl
      params = shib_INSTUTITE.conf 
  • v sekci [BOR_INFO]
      program = shib_bor_info.pl 
  • v sekci [SHIB_LOGOUT] uveďte
      params = http://HOSTNAME/Shibboleth.sso/Logout  
  • 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ř.
      params = https://idp.lib.cas.cz/idp/Logout 

Vzorový tab_service.INSTITUTE může vypadat např. takto:

[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]

Vytvoře soubor shib_INSTITUTE.conf s mapováním atributů, např.:

[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]

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:

  [ATTRIBUTES_MAPPING]
    z312-group,member@lf1.cuni.cz = group,LF1
  [END]

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
Last modified:: 2017/02/10 07:02