====== 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>
**Konec podpory pro Shibboleth IdP řady 4 je k 1. 9. 2024. Tento návod se tedy týká již nové řady 5.**
</WRAP>

<WRAP tip>
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/5.0.0/|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/5.0.0/shibboleth-identity-provider-5.0.0.tar.gz \
     https://shibboleth.net/downloads/identity-provider/5.0.0/shibboleth-identity-provider-5.0.0.tar.gz.asc \
     https://shibboleth.net/downloads/identity-provider/5.0.0/shibboleth-identity-provider-5.0.0.tar.gz.sha256
 
# Přepnutí do adresáře /opt
cd /opt
 
# Kontrola SHA256 otisku
sha256sum -c shibboleth-identity-provider-5.0.0.tar.gz.sha256
 
# Kontrola GPG podpisu
gpg --verify shibboleth-identity-provider-5.0.0.tar.gz.asc
</code>

Nyní přistoupíme k samotné instalaci.

<code bash> 
# Instalace Shibboleth IdP
tar -xzf shibboleth-identity-provider-5.0.0.tar.gz
cd shibboleth-identity-provider-5.0.0/
./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ě),
  - 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>
Installation Directory: [/opt/shibboleth-idp] ? 

INFO  - New Install.  Version: 5.0.0
Host Name: [idp.example.org] ? 

INFO  - Creating idp-signing, CN = idp.example.org URI = https://idp.example.org/idp/shibboleth, keySize=3072
INFO  - Creating idp-encryption, CN = idp.example.org URI = https://idp.example.org/idp/shibboleth, keySize=3072
INFO  - Creating backchannel keystore, CN = idp.example.org URI = https://idp.example.org/idp/shibboleth, keySize=3072
INFO  - Creating Sealer KeyStore
INFO  - No existing versioning property, initializing...
SAML EntityID: [https://idp.example.org/idp/shibboleth] ? 

Attribute Scope: [example.org] ? 

INFO  - Initializing OpenSAML using the Java Services API
INFO  - Algorithm failed runtime support check, will not be usable: http://www.w3.org/2001/04/xmlenc#ripemd160
INFO  - Algorithm failed runtime support check, will not be usable: http://www.w3.org/2001/04/xmldsig-more#hmac-ripemd160
INFO  - Algorithm failed runtime support check, will not be usable: http://www.w3.org/2001/04/xmldsig-more#rsa-ripemd160
INFO  - Algorithm failed runtime support check, will not be usable: http://www.w3.org/2007/05/xmldsig-more#sha1-rsa-MGF1
INFO  - Algorithm failed runtime support check, will not be usable: http://www.w3.org/2007/05/xmldsig-more#sha224-rsa-MGF1
INFO  - Algorithm failed runtime support check, will not be usable: http://www.w3.org/2007/05/xmldsig-more#sha256-rsa-MGF1
INFO  - Algorithm failed runtime support check, will not be usable: http://www.w3.org/2007/05/xmldsig-more#sha384-rsa-MGF1
INFO  - Algorithm failed runtime support check, will not be usable: http://www.w3.org/2007/05/xmldsig-more#sha3-224-rsa-MGF1
INFO  - Algorithm failed runtime support check, will not be usable: http://www.w3.org/2007/05/xmldsig-more#sha3-256-rsa-MGF1
INFO  - Algorithm failed runtime support check, will not be usable: http://www.w3.org/2007/05/xmldsig-more#sha3-384-rsa-MGF1
INFO  - Algorithm failed runtime support check, will not be usable: http://www.w3.org/2007/05/xmldsig-more#sha3-512-rsa-MGF1
INFO  - Algorithm failed runtime support check, will not be usable: http://www.w3.org/2007/05/xmldsig-more#sha512-rsa-MGF1
INFO  - Creating Metadata to /opt/shibboleth-idp/metadata/idp-metadata.xml
INFO  - Rebuilding /opt/shibboleth-idp/war/idp.war, Version 5.0.0
INFO  - Initial populate from /opt/shibboleth-idp/dist/webapp to /opt/shibboleth-idp/webpapp.tmp
INFO  - Overlay from /opt/shibboleth-idp/edit-webapp to /opt/shibboleth-idp/webpapp.tmp
INFO  - Creating war file /opt/shibboleth-idp/war/idp.war
</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://shibboleth.atlassian.net/wiki/spaces/IDP5/pages/3199509576/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://shibboleth.atlassian.net/wiki/spaces/IDP5/pages/3199501202/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://shibboleth.atlassian.net/wiki/spaces/IDP5/pages/3199501202/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://shibboleth.atlassian.net/wiki/spaces/IDP5/pages/3199501202/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''. 
<WRAP important>
**Je nutné nezapomenout nakopírovat soubor ''ldap-server.crt'' na odpovídající místo!**
</WRAP>
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://shibboleth.atlassian.net/wiki/spaces/IDP5/pages/3199506865/FileBackedHTTPMetadataProvider|v oficiální dokumentaci]]. Vše okolo ''<MetadataFilter>'' elementu naleznete také [[https://shibboleth.atlassian.net/wiki/spaces/IDP5/pages/3199507005/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://shibboleth.atlassian.net/wiki/spaces/IDP5/pages/3199502864/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.
</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://shibboleth.atlassian.net/wiki/spaces/IDP5/pages/3199501794/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>
<md: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>
</md:Extensions>
</code>

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

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

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

<code xml>
<md:ContactPerson contactType="technical">
    <md:GivenName>Kryštof</md:GivenName>
    <md:SurName>Šáteček</md:SurName>
    <md:EmailAddress>mailto:krystof.satecek@example.org</md:EmailAddress>
</md: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="JDBCStorageService" parent="shibboleth.JDBCStorageService"
          p:dataSource-ref="shibboleth.MySQLDataSource"
          p:transactionIsolation="4"
          p:retryableErrors="40001"
     />

    <bean id="shibboleth.JPAStorageService"
        parent="shibboleth.JDBCStorageService"
        p:cleanupInterval="%{idp.storage.cleanupInterval:PT10M}"
        p:dataSource-ref="shibboleth.MySQLDataSource"/>
</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/IDP5/pages/3199501275/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 jetty11 v systemd
systemctl edit jetty11
</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>

Přidání doplňků a potvrdíme dvakrát pomocí y a enter.
<code bash>
/opt/shibboleth-idp/bin/plugin.sh -I net.shibboleth.plugin.storage.jdbc
/opt/shibboleth-idp/bin/plugin.sh -I net.shibboleth.idp.plugin.nashorn
</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 jetty11
</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: 6.1.0-17-amd64
operating_system_architecture: amd64
jdk_version: 17.0.9
available_cores: 1
used_memory: 551 MB
maximum_memory: 1500 MB

### Identity Provider Information
idp_version: 5.0.0
start_time: 2024-01-08T13:37:39.849Z
current_time: 2024-01-08T13:37:41.870585878Z
uptime: PT2.021S

enabled modules: 
	idp.Core (Core IdP Functions (Required))
	idp.CommandLine (Command Line Scripts)
	idp.EditWebApp (Overlay Tree for WAR Build)
	idp.authn.Password (Password Authentication)
	idp.admin.Hello (Hello World)

installed plugins: 
	net.shibboleth.idp.plugin.nashorn Version 2.0.0
	net.shibboleth.plugin.storage.jdbc Version 2.0.0

service: shibboleth.LoggingService
last successful reload attempt: 2024-01-08T13:36:14.071738505Z
last reload attempt: 2024-01-08T13:36:14.071738505Z

service: shibboleth.AttributeFilterService
last successful reload attempt: 2024-01-08T13:36:39.855671743Z
last reload attempt: 2024-01-08T13:36:39.855671743Z

service: shibboleth.AttributeResolverService
last successful reload attempt: 2024-01-08T13:36:40.005816408Z
last reload attempt: 2024-01-08T13:36:40.005816408Z

	No Data Connector has ever failed

service: shibboleth.AttributeRegistryService
last successful reload attempt: 2024-01-08T13:36:17.429465810Z
last reload attempt: 2024-01-08T13:36:17.429465810Z

service: shibboleth.NameIdentifierGenerationService
last successful reload attempt: 2024-01-08T13:36:41.444220674Z
last reload attempt: 2024-01-08T13:36:41.444220674Z

service: shibboleth.RelyingPartyResolverService
last successful reload attempt: 2024-01-08T13:36:41.542714468Z
last reload attempt: 2024-01-08T13:36:41.542714468Z

service: shibboleth.MetadataResolverService
last successful reload attempt: 2024-01-08T13:36:18.003662057Z
last reload attempt: 2024-01-08T13:36:18.003662057Z

	metadata source: eduidcz
	last refresh attempt: 2024-01-08T13:36:18.602115911Z
	last successful refresh: 2024-01-08T13:36:18.602115911Z
	last update: 2024-01-08T13:36:18.602115911Z
	root validUntil: 2024-02-03T23:53:01Z

	metadata source: edugain
	last refresh attempt: 2024-01-08T13:36:23.567438235Z
	last successful refresh: 2024-01-08T13:36:23.567438235Z
	last update: 2024-01-08T13:36:23.567438235Z
	root validUntil: 2024-02-04T14:03:02Z

service: shibboleth.ReloadableAccessControlService
last successful reload attempt: 2024-01-08T13:36:42.376372150Z
last reload attempt: 2024-01-08T13:36:42.376372150Z

service: shibboleth.ReloadableCASServiceRegistry
last successful reload attempt: 2024-01-08T13:36:42.426232528Z
last reload attempt: 2024-01-08T13:36:42.426232528Z

service: shibboleth.ManagedBeanService
last successful reload attempt: 2024-01-08T13:36:42.454961810Z
last reload attempt: 2024-01-08T13:36:42.454961810Z
</code>

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

Od verze 4.1.2 existuje modul [[https://shibboleth.atlassian.net/wiki/spaces/IDP5/pages/3199510241/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 jetty11
</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]].**