====== Shibboleth IdP ======

**Na této stránce se nachází návod, jak do linuxové distribuce Debian nainstalovat Shibboleth IdP. Před instalací musíme zprovoznit [[jetty]].**

<WRAP important>
**Podpora pro Shibboleth IdP řady 3 bude ukončena k 31. 12. 2020. Tento návod se tedy týká již nové řady 4.**
</WRAP>

<WRAP tip>
Dne 11. 9. 2023 byl návod aktualizován pro Shibboleth IdP verze 4.3.1.

Dne 16. 6. 2022 byl návod aktualizován pro Shibboleth IdP verze 4.2.1.

Dne 21. 1. 2022 byl návod aktualizován pro Shibboleth IdP verze 4.1.5.

Dne 30. 7. 2021 byl návod aktualizován pro Shibboleth IdP verze 4.1.4.

Dne 25. 6. 2021 byl návod aktualizován pro Shibboleth IdP verze 4.1.2.

Dne 12. 5. 2020 byl návod rozšířen o úpravy konfiguračního souboru [[#metadata-providersxml|metadata-providers.xml]] pro využívání primárně AES-GCM šifrování před starým AES-CBC.

V případě potíží nebo nejasností se neváhejte obrátit na [[info@eduid.cz]].
</WRAP>

----

===== Instalace =====

Zdrojové kódy stáhneme ručně [[https://shibboleth.net/downloads/identity-provider/4.3.1/|ze stránky projektu]] a nahrajeme na server do adresáře ''/opt'' anebo použijeme program //wget// následujícím způsobem. __Následně nezapomeneme ověřit SHA256 otisk a GPG podpis!__

<code bash>
# Stažení zdrojového kódu Shibboleth IdP
wget -P /opt \
     https://shibboleth.net/downloads/identity-provider/4.3.1/shibboleth-identity-provider-4.3.1.tar.gz \
     https://shibboleth.net/downloads/identity-provider/4.3.1/shibboleth-identity-provider-4.3.1.tar.gz.asc \
     https://shibboleth.net/downloads/identity-provider/4.3.1/shibboleth-identity-provider-4.3.1.tar.gz.sha256

# Přepnutí do adresáře /opt
cd /opt

# Kontrola SHA256 otisku
sha256sum -c shibboleth-identity-provider-4.3.1.tar.gz.sha256

# Kontrola GPG podpisu
gpg --verify shibboleth-identity-provider-4.3.1.tar.gz.asc
</code>

Nyní přistoupíme k samotné instalaci, na jejímž začátku si ještě vygenerujeme dvě hesla, která budeme potřebovat v průběhu instalace.

<code bash>
# Vygenerování dvou bezpečných hesel potřebných během instalace
openssl rand -hex 20
openssl rand -hex 20

# Instalace Shibboleth IdP
tar -xzf shibboleth-identity-provider-4.3.1.tar.gz
cd shibboleth-identity-provider-4.3.1/
./bin/install.sh
</code>

Po spuštění instalačního skriptu:
  - potvrdíme zdrojový instalační adresář,
  - potvrdíme cílový instalační adresář,
  - vyplníme hostname serveru (pokud není vyplněn správně),
  - vložíme opakovaně dvě hesla (//Backchannel PKCS12 Password// a //Cookie Encryption Key Password//), která jsme si před instalací vygenerovali pomocí příkazu //openssl//,
  - potvrdíme entityID,
  - zadáme scope organizace (pokud není vyplněn správně).

Zde je vyobrazen průběh instalačního skriptu ''install.sh''.

<code bash>
Buildfile: /opt/shibboleth-identity-provider-4.3.1/bin/build.xml

install:
Source (Distribution) Directory (press <enter> to accept default): [/opt/shibboleth-identity-provider-4.3.1] ? 

Installation Directory: [/opt/shibboleth-idp] ? 

INFO [net.shibboleth.idp.installer.V4Install:158] - New Install.  Version: 4.3.1
Host Name: [idp.example.org] ? 

INFO [net.shibboleth.idp.installer.V4Install:601] - Creating idp-signing, CN = idp.example.org URI = https://idp.example.org/idp/shibboleth, keySize=3072
INFO [net.shibboleth.idp.installer.V4Install:601] - Creating idp-encryption, CN = idp.example.org URI = https://idp.example.org/idp/shibboleth, keySize=3072
Backchannel PKCS12 Password:
Re-enter password: 
INFO [net.shibboleth.idp.installer.V4Install:644] - Creating backchannel keystore, CN = idp.example.org URI = https://idp.example.org/idp/shibboleth, keySize=3072
Cookie Encryption Key Password:
Re-enter password: 
INFO [net.shibboleth.idp.installer.V4Install:685] - Creating backchannel keystore, CN = idp.example.org URI = https://idp.example.org/idp/shibboleth, keySize=3072
INFO [net.shibboleth.utilities.java.support.security.BasicKeystoreKeyStrategyTool:166] - No existing versioning property, initializing...
SAML EntityID: [https://idp.example.org/idp/shibboleth] ? 

Attribute Scope: [example.org] ? 

INFO [net.shibboleth.idp.installer.V4Install:474] - Creating Metadata to /opt/shibboleth-idp/metadata/idp-metadata.xml
INFO [net.shibboleth.idp.installer.BuildWar:103] - Rebuilding /opt/shibboleth-idp/war/idp.war, Version 4.3.1
INFO [net.shibboleth.idp.installer.BuildWar:113] - Initial populate from /opt/shibboleth-idp/dist/webapp to /opt/shibboleth-idp/webpapp.tmp
INFO [net.shibboleth.idp.installer.BuildWar:92] - Overlay from /opt/shibboleth-idp/edit-webapp to /opt/shibboleth-idp/webpapp.tmp
INFO [net.shibboleth.idp.installer.BuildWar:125] - Creating war file /opt/shibboleth-idp/war/idp.war

BUILD SUCCESSFUL
Total time: 58 seconds
</code>

Tím je instalace hotová a přesuneme se ke konfiguraci.

===== Konfigurace =====

Konfigurace může být dost různorodá a vše závisí na tom, zda-li chceme IdP používat pouze pro přístup ke službám federace anebo ho chceme používat i pro přístup k našim interním službám.

<WRAP info>
**Konfigurace uvedená v tomto návodu slouží jako naprostý základ, na kterém lze do budoucna stavět. Není možné sepsat specifičtější návod, protože Shibboleth IdP je velmi komplexní software s nepředstavitelnou škálou možností.**
</WRAP>

==== idp.properties ====

V souboru ''/opt/shibboleth-idp/conf/idp.properties'' nastavíme podporu pro tzv. //consent// (dříve //uApprove//), což je ukládání souhlasů s vydáváním uživatelských informací (atributů) do databáze. Dále zde máme možnost ovlivnit, zda se budou používat cookies anebo lokální úložiště HTML ("HTML Local Storage"). A v neposlední řadě zde můžeme ovlivnit výchozí šifrovací algoritmus pro šifrování XML.

<WRAP tip>
IdP řady 2 uměla využívat pouze cookies. IdP řady 3 přinesla možnost používání lokálního úložiště, ale tato volba byla standardně vypnuta. V IdP řady 4 je tato volba standardně zapnuta, takže pokud instalujete novou verzi (myšleno neaktualizujete stávající IdP V3 na novou verzi), bude povoleno použití lokálního úložiště, pokud ho prohlížeč podporuje.

**Povolení lokálního HTML úložiště s sebou nese dopad na vzhled během přihlašování (probliknutí stránky) a vyžaduje v prohlížeči zapnutý JavaScript!**

Chcete-li zachovat chování jako v předchozích verzích IdP, musíte volbu //idp.storage.htmlLocalStorage// nastavit na hodnotu //false//.

Bližší informace naleznete v oficiální [[https://wiki.shibboleth.net/confluence/display/IDP4/StorageConfiguration#StorageConfiguration-ClientStorageService|dokumentaci]].
</WRAP>

<WRAP alert>
Od Shibboleth IdP 4.0.0 se jako výchozí šifrovací algoritmus pro šifrování XML používá [[https://wiki.shibboleth.net/confluence/display/IDP4/GCMEncryption|AES-GCM]].

Starší verze IdP používaly AES-CBC. Nový algoritmus AES-GCM podporují aktuální operační systémy, na kterých je provozována aktuální verze Shibboleth SP anebo SimpleSAMLphp 1.19.0+. Nicméně ostatní implementace SAML protokolu tento protokol nepodporují a nebudou tedy fungovat.

Existuje více způsobů, jak k tomuto problému přistoupit v závislosti na potřebách konkrétního IdP. Ten nejvhodnější je samozřejmě tlačit na ostatní služby (a jimi používané implementace), aby podporu pro nový algoritmus zařadili. Nejjednodušší způsob je zakomentovat volbu //idp.encryption.config//, ale **správné řešení naleznete v [[https://wiki.shibboleth.net/confluence/display/IDP4/GCMEncryption|dokumentaci]] po jejím přečtení a pochopení**.
</WRAP>

<code bash>
# Otevřeme konfigurační soubor idp.properties
vim /opt/shibboleth-idp/conf/idp.properties
</code>

Nastavíme ''idp.consent.StorageService'' na hodnotu ''shibboleth.JPAStorageService'' a případně i ''idp.storage.htmlLocalStorage'' na ''false''. V případě, že potřebujeme, aby IdP komunikovalo i se službami nepodporující šifrovací algoritmus AES-GCM, můžeme **po přečtení a pochopení [[https://wiki.shibboleth.net/confluence/display/IDP4/GCMEncryption|dokumentace]]** zakomentovat ''idp.encryption.config'', **pokud opravdu chceme vypnout a zakázat nový způsob bezpečného šifrování**:

<code ini>
idp.consent.StorageService = shibboleth.JPAStorageService
idp.storage.htmlLocalStorage = false
#idp.encryption.config=shibboleth.EncryptionConfiguration.GCM
</code>

==== ldap.properties ====

V souboru ''/opt/shibboleth-idp/conf/ldap.properties'' nastavíme konektor do LDAP serveru, pomocí něhož budeme získávat uživatelské atributy.

<code bash>
# Otevřeme konfigurační soubor ldap.properties
vim /opt/shibboleth-idp/conf/ldap.properties
</code>

Důležité jsou především následující volby:

<code ini>
idp.authn.LDAP.authenticator     = bindSearchAuthenticator
idp.authn.LDAP.ldapURL           = ldaps://ldap.example.org:636
idp.authn.LDAP.useStartTLS       = false
idp.authn.LDAP.sslConfig         = certificateTrust
idp.authn.LDAP.trustCertificates = %{idp.home}/credentials/ldap-server.crt
idp.authn.LDAP.baseDN            = ou=people,dc=example,dc=org
idp.authn.LDAP.subtreeSearch     = true
idp.authn.LDAP.bindDN            = uid=shibboleth,ou=users,dc=example,dc=org
</code>

První konfigurační parametr ''idp.authn.LDAP.authenticator'' určuje, jak se bude přistupovat k LDAP serveru. Výchozí (zakomentovaná) hodnota je //anonSearchAuthenticator//, takže se k LDAPu přistupuje anonymně. My však chceme, aby se dotazování LDAP serveru provádělo až po přihlášení, je potřeba nastavit volbu na hodnotu //bindSearchAuthenticator//.

Volba ''idp.authn.LDAP.ldapURL'' určuje, ke kterému LDAP serveru se bude Shibboleth připojovat. Ve výše uvedeném příkladu se připojuje pomocí zabezpečeného SSL (<nowiki>ldaps://</nowiki>) na stadardním portu ''636''.

<WRAP important>
**V ldapURL nesmíme uvést koncové lomítko, např. ''[[ldaps://ldap.example.org:636/]]'', jinak nebude Shibboleth fungovat a v logu najdeme ''java.lang.NumberFormatException: For input string: "636/"''.**
</WRAP>

Konfigurační volba ''idp.authn.LDAP.useStartTLS'' určuje, jestli budeme používat StartTLS. Následující volba ''idp.authn.LDAP.trustCertificates'' udává cestu ke kořenovému certifikátu CA, která vydala SSL certifikát pro LDAP server ''ldap.example.org''. **Je nutné nezapomenout nakopírovat tento soubor na odpovídající místo!**

Volba ''idp.authn.LDAP.baseDN'' určuje tzv. "base DN" v LDAPu. Volby ''idp.authn.LDAP.bindDN'' určuje uživatelské jméno, které se použije při přístupu k LDAP serveru pro získání uživatelských atributů.

==== secrets.properties ====

V souboru ''/opt/shibboleth-idp/credentials/secrets.properties'', který nově existuje v Shibboleth IdP od verze 4.0.0, nastavíme heslo k LDAP serveru a sůl pro //persistentní NameID identifikátor// / atribut //eduPersonTargetedID//, kterou si vygenerujeme.

<code bash>
# Vygenerování soli
openssl rand -base64 36

# Otevřeme konfigurační soubor secrets.properties
vim /opt/shibboleth-idp/credentials/secrets.properties
</code>

Volba ''idp.authn.LDAP.bindDNCredential'' obsahuje heslo, které se použije při přístupu k LDAPu. Heslo je pro uživatelský účet definovaný v ''idp.authn.LDAP.bindDN'' v ''/opt/shibboleth-idp/conf/ldap.properties'' souboru. Volba ''idp.persistentId.salt'' definuje sůl pro persistentní NameID identifikátor, kterou jsme si právě vygenerovali.

<WRAP important>
Nikdy neměňte hodnotu v ''idp.persistentId.salt'', pokud již máte v současné produkční verzi IdP nějakou sůl vygenerovanou.
</WRAP>

<code ini>
idp.authn.LDAP.bindDNCredential = ___HESLO_PRO_BIND_K_LDAP_SERVERU___
idp.persistentId.salt = ___SŮL_PRO_GENEROVÁNÍ_IDENTIFIKÁTORŮ___
</code>

==== metadata-providers.xml ====

V konfiguračním souboru ''/opt/shibboleth-idp/conf/metadata-providers.xml'' se nastavují zdroje metadat. V následujícím příkladu je jako zdroj metadat použita federace //eduID.cz// i mezinárodní federace //eduGAIN//. Metadata se stáhnou a lokálně uloží.

<code bash>
# Otevřeme konfigurační soubor metadata-providers.xml
vim /opt/shibboleth-idp/conf/metadata-providers.xml
</code>

<code xml>
<!-- eduID.cz -->
<MetadataProvider
    id="eduidcz"
    xsi:type="FileBackedHTTPMetadataProvider"
    backingFile="%{idp.home}/metadata/eduidcz.xml"
    metadataURL="https://metadata.eduid.cz/entities/eduid+sp"
    maxRefreshDelay="PT30M">

    <MetadataFilter
        xsi:type="SignatureValidation"
        requireSignedRoot="true"
        certificateFile="%{idp.home}/credentials/metadata.eduid.cz.crt.pem" />

    <MetadataFilter
        xsi:type="RequiredValidUntil"
        maxValidityInterval="P30D" />

</MetadataProvider>

<!-- eduGAIN -->
<MetadataProvider
    id="edugain"
    xsi:type="FileBackedHTTPMetadataProvider"
    backingFile="%{idp.home}/metadata/edugain.xml"
    metadataURL="https://metadata.eduid.cz/entities/edugain+sp"
    maxRefreshDelay="PT30M">

    <MetadataFilter
        xsi:type="SignatureValidation"
        requireSignedRoot="true"
        certificateFile="%{idp.home}/credentials/metadata.eduid.cz.crt.pem" />

    <MetadataFilter
        xsi:type="RequiredValidUntil"
        maxValidityInterval="P30D" />

</MetadataProvider>
</code>

<WRAP important>
Blok kódu výše, tedy element __<MetadataProvider>__ se všemi atributy a potomky, je nutné umístit do //kořenového// elementu __<MetadataProvider>__ v konfiguračním souboru //metadata-providers.xml//! Sice to působí podivně, ale bez toho nebude XML dokument validní a konfigurace nebude fungovat.
</WRAP>

Pokud by vás zajímal význam atributů v elementu ''<MetadataProvider>'', naleznete vše [[https://wiki.shibboleth.net/confluence/display/IDP4/FileBackedHTTPMetadataProvider|v oficiální dokumentaci]]. Vše okolo ''<MetadataFilter>'' elementu naleznete také [[https://wiki.shibboleth.net/confluence/display/IDP4/MetadataFilterConfiguration|v oficiální dokumentaci]].

<WRAP tip>
Pokud jsme se v sekci [[#idpproperties|idp.properties]] správně rozhodli využívat primárně nový bezpečnější způsob šifrování pomocí AES-GCM, je velice vhodné vytvořit sekci pro služby, které toto šifrování nepodporují a povolit u nich starší způsob šifrování pomocí AES-CBC, jinak nebude možné se k nim přihlásit.

Níže uvedený seznam výjimek (složený z entityID služeb podporujících pouze AES-CBC) zajistí, že IdP bude primárně používat nové šifrování a staré pouze pro vyjmenované služby. Seznam níže uvedených služeb by měl být kompletní. Pokud byste narazili na problém, oznamte ho, prosím, na [[info@eduid.cz]].

Jelikož je z kapacitních důvodů velice komplikované otestovat podporu pro AES-GCM, tak pro eduGAIN je zvolen jiný přístup. Primárně se používá AES-CBC, pokud služba v metadatech sama neuvádí podporu pro AES-GCM. Bližší vysvětlení je nad rámec tohoto návodu, proto je zde uvedeno pouze aktuálně nejvhodnější řešení k 12. 5. 2020.

<code xml>
<!-- eduID.cz -->
<MetadataProvider
    id="eduidcz"
    xsi:type="FileBackedHTTPMetadataProvider"
    backingFile="%{idp.home}/metadata/eduidcz.xml"
    metadataURL="https://metadata.eduid.cz/entities/eduid+sp"
    maxRefreshDelay="PT30M">

    <MetadataFilter
        xsi:type="SignatureValidation"
        requireSignedRoot="true"
        certificateFile="%{idp.home}/credentials/metadata.eduid.cz.crt.pem" />

    <MetadataFilter
        xsi:type="RequiredValidUntil"
        maxValidityInterval="P30D" />

    <MetadataFilter
        xsi:type="Algorithm">

        <md:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc" />
        <Entity>ccm.net.cvut.cz</Entity>
        <Entity>https://adfs-ext.w2lan.cesnet.cz/adfs/services/trust</Entity>
        <Entity>https://adfs.w2lan.cesnet.cz/adfs/services/trust</Entity>
        <Entity>https://auth.eidas.cesnet.cz/sp</Entity>
        <Entity>https://camelot.lf2.cuni.cz/shibboleth</Entity>
        <Entity>https://cawi.fsv.cuni.cz/simplesaml/module.php/saml/sp/metadata.php/default-sp</Entity>
        <Entity>https://collector-metacentrum.liberouter.org/simplesaml/module.php/saml/sp/metadata.php/collector</Entity>
        <Entity>https://cz-online.aliveplatform.com/simplesaml/module.php/saml/sp/metadata.php/cz-online.aliveplatform.com</Entity>
        <Entity>https://digi.law.muni.cz</Entity>
        <Entity>https://digitool.is.cuni.cz/shibboleth</Entity>
        <Entity>https://dspace.vsb.cz/sp/shibboleth</Entity>
        <Entity>https://dspace2.zcu.cz/dspace</Entity>
        <Entity>https://edu.ista.tacr.cz/ISTA</Entity>
        <Entity>https://filesender.cesnet.cz/saml/sp</Entity>
        <Entity>https://gc3.cesnet.cz/shibboleth</Entity>
        <Entity>https://index.bbmri.cz/shibboleth</Entity>
        <Entity>https://iptel.cesnet.cz/shibboleth/cesnet-internal/sp</Entity>
        <Entity>https://ista.tacr.cz/ISTA</Entity>
        <Entity>https://itmulti.cz/simplesaml/module.php/saml/sp/metadata.php/portal4</Entity>
        <Entity>https://journals.bmj.com/shibboleth</Entity>
        <Entity>https://login.bbmri-eric.eu/proxy/</Entity>
        <Entity>https://login.ceitec.cz/proxy/</Entity>
        <Entity>https://login.elixir-czech.org/proxy/</Entity>
        <Entity>https://login.ezproxy.is.cuni.cz/sp/shibboleth</Entity>
        <Entity>https://login.ezproxy.uochb.cas.cz:2443/sp/shibboleth</Entity>
        <Entity>https://login.ezproxy.vscht.cz/sp/shibboleth</Entity>
        <Entity>https://mefanet-motol.cuni.cz/sp/shibboleth</Entity>
        <Entity>https://meta.cesnet.cz/sp/shibboleth</Entity>
        <Entity>https://mooc.cuni.cz/sp/shibboleth</Entity>
        <Entity>https://nfsmon.ics.muni.cz/</Entity>
        <Entity>https://odevzdej.cz/shibboleth/</Entity>
        <Entity>https://orca.ruk.cuni.cz/shibboleth</Entity>
        <Entity>https://pentest.cesnet.cz/sp/shibboleth</Entity>
        <Entity>https://portal.lf3.cuni.cz/shibboleth/sp</Entity>
        <Entity>https://postudium.cz/auth/saml2/sp/metadata.php</Entity>
        <Entity>https://proxy.lifescienceid.org/metadata/backend.xml</Entity>
        <Entity>https://repozitar.cz/shibboleth/</Entity>
        <Entity>https://seth.ics.muni.cz/shibboleth</Entity>
        <Entity>https://softweco.cz/shibboleth-sp</Entity>
        <Entity>https://su-dev.fit.vutbr.cz/kis</Entity>
        <Entity>https://su-int.fit.vutbr.cz/kis</Entity>
        <Entity>https://teleinform.cz/simplesaml/module.php/saml/sp/metadata.php/portal1</Entity>
        <Entity>https://telekomunikace-tit.cz/simplesaml/module.php/saml/sp/metadata.php/portal3</Entity>
        <Entity>https://test.ista.tacr.cz/ISTA</Entity>
        <Entity>https://thalamoss-data.ics.muni.cz/shibboleth</Entity>
        <Entity>https://theses.cz/shibboleth/</Entity>
        <Entity>https://vut-vsb.cz/simplesaml/module.php/saml/sp/metadata.php/portal2</Entity>
        <Entity>https://vvvd.vsb.cz/shibboleth</Entity>
        <Entity>https://wikisofia.cz/shibboleth</Entity>
        <Entity>https://www.bookport.cz/</Entity>
        <Entity>https://www.cistbrno.cz/</Entity>
        <Entity>https://www.citacepro.com/simplesaml/module.php/saml/sp/metadata.php/eduid-sp</Entity>
        <Entity>https://www.eunis.cz/simplesamlphp/module.php/saml/sp/metadata.php/eunis</Entity>
        <Entity>https://www.jib.cz/shibboleth</Entity>
        <Entity>https://www.levna-knihovna.cz/simplesamlphp/module.php/saml/sp/metadata.php/default-sp</Entity>
        <Entity>https://www.liberouter.org/simplesamlphp/module.php/saml/sp/metadata.php/liberouter</Entity>
        <Entity>https://www.mecenat.eu/sp</Entity>
        <Entity>https://www.vutbr.cz/SSO/saml2/sp</Entity>

    </MetadataFilter>

</MetadataProvider>

<!-- eduGAIN -->
<MetadataProvider
    id="edugain"
    xsi:type="FileBackedHTTPMetadataProvider"
    backingFile="%{idp.home}/metadata/edugain.xml"
    metadataURL="https://metadata.eduid.cz/entities/edugain+sp"
    maxRefreshDelay="PT30M">

    <MetadataFilter
        xsi:type="SignatureValidation"
        requireSignedRoot="true"
        certificateFile="%{idp.home}/credentials/metadata.eduid.cz.crt.pem" />

    <MetadataFilter
        xsi:type="RequiredValidUntil"
        maxValidityInterval="P30D" />

    <MetadataFilter
        xsi:type="Algorithm">

        <md:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc"/>
        <ConditionRef>shibboleth.Conditions.TRUE</ConditionRef>

    </MetadataFilter>

</MetadataProvider>
</code>

</WRAP>

Metadata federací //eduID.cz// i //eduGAIN// jsou podepsána. **Důrazně doporučujeme tedy jejich autenticitu ověřovat pomocí kontroly podpisu!** Veřejný klíč je k dispozici na adrese https://www.eduid.cz/docs/eduid/metadata/metadata.eduid.cz.crt.pem. Stáhneme si ho a uložíme do adresáře ''/opt/shibboleth-idp/credentials''.

<code bash>
# Stažení veřejného klíče metadata.eduid.cz.crt.pem
wget -P /opt/shibboleth-idp/credentials \
    https://www.eduid.cz/docs/eduid/metadata/metadata.eduid.cz.crt.pem
</code>

==== attribute-resolver.xml ====

Chceme-li si konfigurační soubor ''/opt/shibboleth-idp/conf/attribute-resolver.xml'' nakonfigurovat od začátku a naprosto sami, využijeme k tomu soubor ''/opt/shibboleth-idp/conf/examples/attribute-resolver-ldap.xml'', který v sobě zahrnuje i konektor do LDAP serveru.

Doporučujeme však vyjít z připraveného souboru na adrese [[https://www.eduid.cz/shibboleth-idp/attribute-resolver.xml]]. [[cs:tech:attributes]] naleznete v dokumentaci. Podle tohoto seznamu si ''attribute-resolver.xml'' můžeme upravit.

<WRAP alert>
**Návod v následujících krocích předpokládá, že jsme použili připravenou šablonu!**

Navíc se předpokládá, že pro generování persistentního NameID identifikátoru používáte atribut ''uid''. Tento SAML atribut nesmí mít v ''attribute-resolver.xml'' XML atribut //dependencyOnly="true"//, jinak nebude pro generování persistentního NameID k dispozici a persistentní NameID se nevygeneruje.

**Některé služby bez persistentního NameID nebudou fungovat!**
</WRAP>

<code bash>
# Stažení attribute-resolver.xml
wget -O /opt/shibboleth-idp/conf/attribute-resolver.xml \
    https://www.eduid.cz/shibboleth-idp/attribute-resolver.xml
</code>

Potřebujeme-li si definovat své vlastní atributy, pak bližší informace ke konfiguraci nalezneme [[https://wiki.shibboleth.net/confluence/display/IDP4/AttributeResolverConfiguration|v oficiální dokumentaci]].

<WRAP info>
Budete-li sledovat logy (//idp-process.log// a //idp-warn.log//), objevíte tam varování týkající se zastaralého "SAML2NameID". To můžete ignorovat. Než bude nová majoritní verze Shibboleth IdP, budeme mít hotovou revizi používání tohoto atributu na službách ve federaci a tento atribut bude možné eliminovat.
</WRAP>

==== cesnetAttributes.xml ====

Sdružení CESNET definuje pro federaci eduID.cz několik atributů, které jsou definovány právě v souboru ''cesnetAttributes.xml'', čímž se zjednoduší konfigurační soubor ''attribute-resolver.xml''. Doporučujeme tedy tento soubor stáhnout z našeho weby.

<code bash>
# Stažení cesnetAttributes.xml
wget -O /opt/shibboleth-idp/conf/attributes/cesnetAttributes.xml \
    https://www.eduid.cz/shibboleth-idp/cesnetAttributes.xml
</code>

==== default-rules.xml ====

Aby si Shibboleth IdP načetl soubor ''cesnetAttributes.xml'', který obsahuje definice atributů pro federaci eduID.cz (vizte výše), je nutné přidat jeho načtení do souboru ''default-rules.xml'' ideálně ihned za import ostatních konfiguračních souborů s atributy:

<code xml>
<import resource="cesnetAttributes.xml" />
</code>

Pro jednoduchost je možné tento konfigurační soubor stáhnout z našeho webu.

<code bash>
# Stažení default-rules.xml
wget -O /opt/shibboleth-idp/conf/attributes/default-rules.xml \
    https://www.eduid.cz/shibboleth-idp/default-rules.xml
</code>

==== eduPerson.xml ====

Aby se v českém prostředí (závisí na nastavení webového prohlížeče) v přehledu uvolňovaných atributů zobrazovaly české popisy atributů z rodiny "eduPerson", je nutné doplnit překlady do souboru ''eduPerson.xml''. To lze nejsnadněji udělat tak, že si tento soubor stáhnete z našeho webu.

<code bash>
# Stažení eduPerson.xml
wget -O /opt/shibboleth-idp/conf/attributes/eduPerson.xml \
    https://www.eduid.cz/shibboleth-idp/eduPerson.xml
</code>

==== inetOrgPerson.xml ====

Aby se v českém prostředí (závisí na nastavení webového prohlížeče) v přehledu uvolňovaných atributů zobrazovaly české popisy atributů z rodiny "inetOrgPerson", je nutné doplnit překlady do souboru ''inetOrgPerson.xml''. To lze nejsnadněji udělat tak, že si tento soubor stáhnete z našeho webu.

<code bash>
# Stažení inetOrgPerson.xml
wget -O /opt/shibboleth-idp/conf/attributes/inetOrgPerson.xml \
    https://www.eduid.cz/shibboleth-idp/inetOrgPerson.xml
</code>

==== attribute-filter.xml ====

Mít definované atributy z předchozího kroku nestačí. Ještě je potřeba nadefinovat, které atributy budeme vydávat a komu je budeme vydávat. To se nastavuje v konfiguračním souboru ''/opt/shibboleth-idp/conf/attribute-filter.xml''.

Z důvodu zjednodušení doporučujeme uvolňovat atributy dle našeho doporučení na adrese [[https://www.eduid.cz/shibboleth-idp/attribute-filter.xml]].

Filtr uvolňuje atributy podle kategorií entit [[cs:tech:categories:rs]], [[cs:tech:categories:coco]] a dále do federací [[cs:tech:summary|eduID.cz]] a [[cs:tech:edugain|eduGAIN]].

<code bash>
wget -O /opt/shibboleth-idp/conf/attribute-filter.xml \
    https://www.eduid.cz/shibboleth-idp/attribute-filter.xml
</code>

Chcete-li si nastavit uvolňování atributů dle svého, tak bližší informace naleznete [[https://wiki.shibboleth.net/confluence/display/IDP4/AttributeFilterConfiguration|v oficiální dokumentaci]].

==== idp-metadata.xml ====

Soubor ''/opt/shibboleth-idp/metadata/idp-metadata.xml'' obsahuje metadata IdP, která je potřeba po instalaci doplnit o další informace jako například element ''<UIInfo>'', který se zapisuje do "rozšíření" (element ''<Extensions>''), např. za ''<Scope>'':

<code bash>
# Otevřeme konfigurační soubor idp-metadata.xml
vim /opt/shibboleth-idp/metadata/idp-metadata.xml
</code>

<code xml>
<Extensions>
    <shibmd:Scope regexp="false">example.org</shibmd:Scope>
    <mdui:UIInfo>
        <mdui:DisplayName xml:lang="en">EXAMPLE</mdui:DisplayName>
        <mdui:DisplayName xml:lang="cs">EXAMPLE</mdui:DisplayName>
        <mdui:Description xml:lang="en">EXAMPLE's Identity Provider.</mdui:Description>
        <mdui:Description xml:lang="cs">Poskytovatel identity pro EXAMPLE.</mdui:Description>
        <mdui:InformationURL xml:lang="en">http://www.example.org/en/</mdui:InformationURL>
        <mdui:InformationURL xml:lang="cs">http://www.example.org/cs/</mdui:InformationURL>
        <mdui:Logo height="200" width="200">https://img.example.org/logo-200.gif</mdui:Logo>
    </mdui:UIInfo>
</Extensions>
</code>

Dále je nutno doplnit název organizace v elementu ''<Organization>'' (patří do elementu ''<EntityDescriptor>'' za element ''</IDPSSODescriptor>''):

<code xml>
<Organization>
    <OrganizationName xml:lang="en">EXAMPLE, a. l. e.</OrganizationName>
    <OrganizationName xml:lang="cs">EXAMPLE, z. s. p. o.</OrganizationName>
    <OrganizationDisplayName xml:lang="en">EXAMPLE</OrganizationDisplayName>
    <OrganizationDisplayName xml:lang="cs">EXAMPLE</OrganizationDisplayName>
    <OrganizationURL xml:lang="en">http://www.example.org/en/</OrganizationURL>
    <OrganizationURL xml:lang="cs">http://www.example.org/cs/</OrganizationURL>
</Organization>
</code>

Chybět nesmí ani kontaktní osoby v elementu ''<ContactPerson>'' (opět v elementu ''<EntityDescriptor>'' za element ''<Organization>''):

<code xml>
<ContactPerson contactType="technical">
    <GivenName>Kryštof</GivenName>
    <SurName>Šáteček</SurName>
    <EmailAddress>mailto:krystof.satecek@example.org</EmailAddress>
</ContactPerson>
</code>

==== global.xml ====

Nyní je potřeba v souboru ''global.xml'' definovat některé "<bean>y". Tato konfigurace zajistí správnou konektivitu na //MariaDB// databázi pro ukládání persistentních identifikátorů a zároveň pro ukládání souhlasů s vydáváním atributů (tzv. uApprove).


<code bash>
# Úpravy v konfiguračním souboru global.xml
vim /opt/shibboleth-idp/conf/global.xml
</code>

V prvním bloku kódu nahradíme ''___SILNE_HESLO___'' heslem pro uživatele //shibboleth// k databázi //shibboleth//.

<code xml>
<bean id="shibboleth.MySQLDataSource"
    class="org.apache.commons.dbcp2.BasicDataSource"
    p:driverClassName="org.mariadb.jdbc.Driver"
    p:url="jdbc:mysql://localhost:3306/shibboleth"
    p:username="shibboleth"
    p:password="___SILNE_HESLO___" />

<bean id="shibboleth.JPAStorageService"
    class="org.opensaml.storage.impl.JPAStorageService"
    p:cleanupInterval="%{idp.storage.cleanupInterval:PT10M}"
    c:factory-ref="shibboleth.JPAStorageService.entityManagerFactory" />

<bean id="shibboleth.JPAStorageService.entityManagerFactory"
    class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean">
    <property name="packagesToScan" value="org.opensaml.storage.impl"/>
    <property name="dataSource" ref="shibboleth.MySQLDataSource"/>
    <property name="jpaVendorAdapter" ref="shibboleth.JPAStorageService.JPAVendorAdapter"/>
    <property name="jpaDialect">
        <bean class="org.springframework.orm.jpa.vendor.HibernateJpaDialect" />
    </property>
</bean>

<bean id="shibboleth.JPAStorageService.JPAVendorAdapter"
    class="org.springframework.orm.jpa.vendor.HibernateJpaVendorAdapter"
    p:generateDdl="true"
    p:database="MYSQL"
    p:databasePlatform="org.hibernate.dialect.MariaDBDialect" />
</code>

==== saml-nameid.properties ====

Dále musíme provést úpravy v konfiguračním souboru ''saml-nameid.properties''.

<code bash>
# Úpravy v konfiguračním souboru saml-nameid.properties
vim /opt/shibboleth-idp/conf/saml-nameid.properties
</code>

Zde definujeme odkazy na výše definované "<bean>y", dále atribut, který se bude pro výpočet persistentního identifikátoru používat (''uid'').

<code ini>
idp.persistentId.sourceAttribute = uid
# Nové IdP (BASE32)
idp.persistentId.encoding = BASE32
# Migrované IdP (BASE64)
#idp.persistentId.encoding = BASE64
idp.persistentId.generator = shibboleth.StoredPersistentIdGenerator
idp.persistentId.dataSource = shibboleth.MySQLDataSource
</code>

==== saml-nameid.xml ====

Podpora persistentních identifikátorů je ještě potřeba zapnout v konfiguračním souboru ''saml-nameid.xml''.

<code bash>
# Úpravy v konfiguračním souboru saml-nameid.xml
vim /opt/shibboleth-idp/conf/saml-nameid.xml
</code>

Stačí odkomentovat následující řádek, který je ve výchozí konfiguraci po instalaci IdP zakomentovaný.

<code xml>
<ref bean="shibboleth.SAML2PersistentGenerator" />
</code>

==== subject-c14n.xml ====

Teď ještě zbývá úprava v souboru ''subject-c14n.xml''.

<code bash>
# Úpravy v konfiguračním souboru subject-c14n.xml
vim /opt/shibboleth-idp/conf/c14n/subject-c14n.xml
</code>

Odkomentujeme tedy následující řádek:

<code xml>
<ref bean="c14n/SAML2Persistent" />
</code>

==== messages_cs.properties ====

Ve výchozím nastavení IdP s uživatelem přes webový prohlížeč komunikuje v angličtině. Pokud chceme, aby texty na stránkách IdP byly v češtině, musíme do IdP dodat české překlady. Ty jsou dostupné na webu [[https://shibboleth.atlassian.net/wiki/spaces/IDP4/pages/1265631751/MessagesTranslation|Shibbolethu]] a jsou pravidelně udržovány. (Pokud byste našli chybu nebo uměli dodat lepší překlad, na stránce najdete i postup, jak k překladům přispět.)

Jazyk, který bude použit, se určuje na základě nastavení webového prohlížeče. Takže pokud má uživatel v prohlížeči preferovaný jazyk angličtinu, IdP bude všechny texty vypisovat v angličtině.

<code bash>
# Stažení českých překladů
wget https://shibboleth.atlassian.net/wiki/download/attachments/1265631751/messages_cs.properties \
    -O /opt/shibboleth-idp/messages/messages_cs.properties
</code>

===== Spuštění =====

Nyní, když máme IdP nakonfigurováno, opravíme práva v adresáři ''/opt/shibboleth-idp'':

<code bash>
# Úprava práv
chown jetty /opt/shibboleth-idp/{logs,metadata}
chgrp -R jetty /opt/shibboleth-idp/{conf,credentials}
chmod -R g+r /opt/shibboleth-idp/conf
chmod 750 /opt/shibboleth-idp/credentials
chmod 640 /opt/shibboleth-idp/credentials/*
</code>

V systemd musíme Jetty povolit přístup pro zápis do adresářů s logy a metadaty.

<code bash>
# Úprava služby jetty9 v systemd
systemctl edit jetty9
</code>

Nastavení práv pro záspis do adresářů ''/opt/shibboleth-idp/{logs,metadata}'':

<code ini>
[Service]
ReadWritePaths=/opt/shibboleth-idp/logs/
ReadWritePaths=/opt/shibboleth-idp/metadata/
</code>

Zbývá jen znovu načíst konfiguraci pro službu Jetty a tu následně restartovat:

<code bash>
# Restart Jetty
systemctl daemon-reload
systemctl restart jetty9
</code>

Nyní, jakmile Jetty po chvilce nastartuje, můžeme vyzkoušet, zda IdP v pořádku běží:

<code bash>
# Zobrazení stavu IdP
/opt/shibboleth-idp/bin/status.sh
</code>

Pokud IdP korektně běží, uvidíte následující:

<code>
### Operating Environment Information
operating_system: Linux
operating_system_version: 4.19.0-16-amd64
operating_system_architecture: amd64
jdk_version: 11.0.11
available_cores: 1
used_memory: 567 MB
maximum_memory: 1500 MB

### Identity Provider Information
idp_version: 4.1.4
start_time: 2021-07-30T12:30:59.362Z
current_time: 2021-07-30T12:31:02.708316Z
uptime: PT3.346S

enabled modules: 
	idp.authn.Password (Password Authentication)
	idp.admin.Hello (Hello World)

installed plugins: 

service: shibboleth.LoggingService
last successful reload attempt: 2021-07-30T12:30:36.979656Z
last reload attempt: 2021-07-30T12:30:36.979656Z

service: shibboleth.AttributeFilterService
last successful reload attempt: 2021-07-30T12:30:49.708861Z
last reload attempt: 2021-07-30T12:30:49.708861Z

service: shibboleth.AttributeResolverService
last successful reload attempt: 2021-07-30T12:30:50.098082Z
last reload attempt: 2021-07-30T12:30:50.098082Z

	No Data Connector has ever failed

service: shibboleth.AttributeRegistryService
last successful reload attempt: 2021-07-30T12:30:40.596293Z
last reload attempt: 2021-07-30T12:30:40.596293Z

service: shibboleth.NameIdentifierGenerationService
last successful reload attempt: 2021-07-30T12:30:51.374966Z
last reload attempt: 2021-07-30T12:30:51.374966Z

service: shibboleth.RelyingPartyResolverService
last successful reload attempt: 2021-07-30T12:30:51.627042Z
last reload attempt: 2021-07-30T12:30:51.627042Z

service: shibboleth.MetadataResolverService
last successful reload attempt: 2021-07-30T12:30:41.096033Z
last reload attempt: 2021-07-30T12:30:41.096033Z

	metadata source: ShibbolethMetadata
	last refresh attempt: 2021-07-30T12:30:47.900064Z
	last successful refresh: 2021-07-30T12:30:54.303173Z
	last update: 2021-07-30T12:30:54.303173Z

	metadata source: eduidcz
	last refresh attempt: 2021-07-30T12:30:47.900064Z
	last successful refresh: 2021-07-30T12:30:47.900064Z
	last update: 2021-07-30T12:30:47.900064Z
	root validUntil: 2021-07-07T23:53:01Z

	metadata source: edugain
	last refresh attempt: 2021-07-30T12:30:54.303173Z
	last successful refresh: 2021-07-30T12:30:54.303173Z
	last update: 2021-07-30T12:30:54.303173Z
	root validUntil: 2021-07-08T14:03:02Z

service: shibboleth.ReloadableAccessControlService
last successful reload attempt: 2021-07-30T12:30:52.142085Z
last reload attempt: 2021-07-30T12:30:52.142085Z

service: shibboleth.ReloadableCASServiceRegistry
last successful reload attempt: 2021-07-30T12:30:52.226890Z
last reload attempt: 2021-07-30T12:30:52.226890Z

service: shibboleth.ManagedBeanService
last successful reload attempt: 2021-07-30T12:30:52.254087Z
last reload attempt: 2021-07-30T12:30:52.254087Z
</code>

===== Testování =====

Od verze 4.1.2 existuje modul [[https://wiki.shibboleth.net/confluence/display/IDP4/HelloWorldConfiguration|Hello]], pomocí kterého je možné IdP testovat i bez napojení na federaci.

Tento modul je po instalaci zapnutý. Pokud by však zapnutý náhodou nebyl, zapnete ho jednoduše:

<code bash>
# Zapnutí modulu Hello
/opt/shibboleth-idp/bin/module.sh -e idp.admin.Hello
</code>

Nyní zbývá nastavit uživatele, který se bude moci k tomuto diagnostickému modulu přihlásit. To se konfiguruje v souboru ''conf/access-control.xml'' ve volbě //AccessByAdminUser//, kde je ve výchozím nastavení hodnota ''jdoe'' (tato hodnota odpovídá přihlašovacímu jménu):

<code xml>
<entry key="AccessByAdminUser">
  <bean parent="shibboleth.PredicateAccessControl">
    <constructor-arg>
      <bean parent="shibboleth.Conditions.SubjectName" c:collection="#{'jdoe'}" />
    </constructor-arg>
  </bean>
</entry>
</code>

Následně na adrese ''/idp/profile/admin/hello'' našeho IdP můžeme přistoupit k modulu a po úspěšném přihlášení vidět seznam atributů a jejich hodnot, které bude umět IdP uvolnit službám ve federaci.

Po otestování je možné modul //Hello// vypnout a restartovat Jetty:

<code bash>
# Vypnutí modulu Hello
/opt/shibboleth-idp/bin/module.sh -d idp.admin.Hello

# Restartování Jetty
systemctl restart jetty9
</code>

===== Tipy =====

Na stránce [[cs:tech:idp:shibboleth:advanced]] naleznete některé zajímavé konfigurační tipy, které by vás mohly zajímat, proto se na stránku určitě podívejte.

===== Vzhled =====

Výchozí přihlašovací stránka vypadá následujícím způsobem:

{{:cs:tech:idp:shib-loginpage-default-new2.png|Výchozí vzhled přihlašovací stránky.}}

Její vzhled je možno upravit do vzhledu podobnému stránkám naší organizace. Veškeré úpravy se provádí v adresáři ''/opt/shibboleth-idp/views/''. Výchozí nastavení je možné najít v ''/opt/shibboleth-idp/dist/views/'', kde se můžete inspirovat.

Změny provedené v souborech s koncovkou ve ''views/*.vm'' se projeví okamžitě a není potřeba generovat nový ''idp.war'' ani restartovat Jetty.

----

====== Publikace metadat ======

**Máme-li nainstalován Shibboleth IdP, můžeme pokračovat [[cs:tech:metadata-publication|publikací metadat]].**