====== Výměna certifikátu ======

Tento dokument popisuje způsob, jak u Shibbolethu SP bez výpadku poskytování služby vyměnit certifikát v metadatech federace.

===== Základní informace =====

Poskytovatel služby (Service Provider, SP) potřebuje pro svoji činnost certifikát, který používá pro podepisování autentizačních žádostí a k dešifrování SAML zpráv. Tento certifikát se vkládá do metadat federace identit, aby ho znali všichni poskytovatelé identit (Identity Provider, IdP) ve federaci. Certifikát tedy musí být umístěn na dvou místech:

  * v konfiguračním souboru (''shibboleth2.xml'') Shibboleth SP a
  * federačních metadatech.

Změny v metadatech federace identit potřebují většinou minimálně 2 hodiny, aby se rozdistribuovaly ke všem entitám ve federaci. Některé entity metadata kontrolují a stahují častěji, jiným to však může trvat až 24 hodin. Z tohoto důvodu není možné certifikát na SP jednoduše vyměnit bez pečlivého plánování v případě, že chcete zajistit bezvýpadkový provoz své služby.

===== Nastavení =====

Aby byl návod ukázkový, budou v něm použity následující:

^ Parametr          ^ Hodnota                                            ^
| hostname          | sp.example.org                                     |
| entityID          | <nowiki>https://sp.example.org/shibboleth</nowiki> |
| starý certifikát  | /etc/shibboleth/sp-cert.pem                        |
| starý klíč        | /etc/shibboleth/sp-key.pem                         |
| nový certifikát   | /etc/shibboleth/sp-2019-cert.pem                   |
| nový klíč         | /etc/shibboleth/sp-2019-key.pem                    |

//"2019" v názvu nového certifikátu a klíče značí rok, kdy provádím výměnu certifikátu. Prosté "new" by mohlo být při další výměně matoucí. Doporučuji použití aktuálního roku.//
===== Postup výměny certifikátu =====

Následujících 6 kroků popisuje samotnou výměnu certifikátu, aniž by došlo k výpadku poskytování služby.

==== Krok 1: Vytvoření nového certifikátu ====

Důrazně doporučujeme použití self-sign certifikátu, který však musí splňovat určité [[https://www.eduid.cz/cs/tech/certificates|požadavky]]. Nejjednodušší je použití utility //shib-keygen//, která je součástí distribučního balíčku v Debianu.

__Použití serverového TCS certifikátu je naprosto nevhodné z důvodu krátké platnosti a tedy potřebě častější výměny certifikátu.__

Postup pro vygenerování nového certifikátu je následující:

<code bash>
# Vygenerujeme nový certifikát a klíč s prefixem aktuálního kalendářního roku, např. "​sp-2019"
shib-keygen -h sp.example.org -e https://sp.example.org/shibboleth -n sp-2019
</code>
==== Krok 2: Přidáno nového certifikátu do SP ====

Ještě než přidáme nový certifikát do metadat federace, je nezbytné, aby s ním umělo SP pracovat a umělo tedy rozšifrovat zprávy od IdP, které jím byly zašifrovány. Zároveň však musí být zaručeno, že SP samotné tento certifikát nezačne aktivně používat pro dotazy na atributy. Nový certifikát tedy nakonfigurujeme až //jako druhý v pořadí// — není-li totiž specificky určeno jinak, pak se použije první pár klíč-certifikát v pořadí.

Konfigurace se provádí v souboru ''/etc/shibboleth/shibboleth2.xml''. Je potřeba změnit element ''<CredentialResolver>'' následujícím způsobem:

<code xml>
<CredentialResolver type="Chaining">

  <CredentialResolver type="File" key="sp-key.pem" certificate="sp-cert.pem"/>
  <CredentialResolver type="File" key="sp-2019-key.pem" certificate="sp-2019-cert.pem" keyName="2019"/>

</CredentialResolver>
</code>

Je velmi důležité, aby **nový certifikát** byl definován **za stávajícím certifikátem**, protože jsou na straně SP používány v pořadí svého uvedení a my chceme, aby se prozatím aktivně používal ten starý.

Po přidání nového certifikátu do konfigurace SP zkontrolujeme, zda-li je konfigurační soubor v pořádku:

<code bash>
shibd -tc /etc/shibboleth/shibboleth2.xml
</code>

Výstup by měl zobrazit informaci //overall configuration is loadable// bez chyb anebo kritických zpráv. Pokud je vše v pořádku, restartujeme démona Shibboleth:

<code bash>
systemctl restart shibd
</code>

Nyní SP umí rozšifrovat zprávy od IdP jak starým tak novým certifikátem. Avšak aktivně bude SP používat stále starý certifikát.

==== Krok 3: Přidání nového certifikátu do metadat federace ====

Nyní je potřeba nový certifikát přidat do metadat federace. Metadata SP snadno vygenerujete přístupem na adresu ''<nowiki>https://sp.example.org/Shibboleth.sso/Metadata</nowiki>'' a zajistíme jejich aktualizaci ve federaci obvyklým způsobem.

IdP ve federaci s novými metadaty použijí pro šifrování zpráv pro SP náhodně zvolený certifikát ze seznamu dostupných. SP již tedy musí umět pracovat s oběma certifikáty -- starým i novým.

**S následujícím krokem doporučujeme počkat alespoň 24 hodin od doby potvrzení aktualizace metadat správcem federace.**

==== Krok 4: Nastavení nového certifikátu jako preferovaného na SP ====

Po uplynutí 24 hodin od aktualizace metadat ve federaci budou mít všechna IdP aktualizovaná metadata a budou tedy znát starý i nový certifikát. Nastavíme tedy nový certifikát jako výchozí -- umístíme ho na první místo v konfiguraci -- a SP začne tedy nový certifikát aktivně používat při komunikaci.

**Starý certifikát však stále v konfiguraci ponecháme!**

Konfigurace se provádí v souboru ''/etc/shibboleth/shibboleth2.xml''. Je potřeba změnit element ''<CredentialResolver>'' následujícím způsobem:

<code xml>
<CredentialResolver type="Chaining">
 
  <CredentialResolver type="File" key="sp-2019-key.pem" certificate="sp-2019-cert.pem" keyName="2019"/>
  <CredentialResolver type="File" key="sp-key.pem" certificate="sp-cert.pem"/>
 
</CredentialResolver>
</code>

Po úpravě konfigurace SP zkontrolujeme, zda-li je konfigurační soubor v pořádku:

<code bash>
shibd -tc /etc/shibboleth/shibboleth2.xml
</code>

Výstup by měl zobrazit informaci //overall configuration is loadable// bez chyb anebo kritických zpráv. Pokud je vše v pořádku, restartujeme démona Shibboleth:

<code bash>
systemctl restart shibd
</code>

==== Krok 5: Odstranění starého certifikátu z metadat federace ====

Tento krok můžeme provést ihned po provedení kroku předchozího.

Požádáme správce federace o odstranění starého certifikátu z metadat SP.

Po potvrzení, že metadata byla aktualizována, by si měla všechna IdP metadata aktualizovat opět nejpozději do 24 hodin.

==== Krok 6: Odstranění starého certifikátu z konfigurace SP ====

Starý certifikát z konfigurace SP odstraníme //až po uplynutí alespoň 24 hodin// od doby, kdy jsme dostali od operátora federace potvrzení o odebrání starého certifikátu z metadat. Pouze pak je totiž jistota, že opravdu všechna IdP ve federaci mají aktuální metadata a budou tedy používat již pouze a jen nový certifikát. V případě, že se tak nestane, Vaše služba nebude fungovat.

Konfigurace se provádí v souboru ''/etc/shibboleth/shibboleth2.xml''. Je potřeba změnit element ''<CredentialResolver>'' následujícím způsobem:

<code xml>
<CredentialResolver type="Chaining">
 
  <CredentialResolver type="File" key="sp-2019-key.pem" certificate="sp-2019-cert.pem" keyName="2019"/>
 
</CredentialResolver>
</code>

Po úpravě konfigurace SP zkontrolujeme, zda-li je konfigurační soubor v pořádku:

<code bash>
shibd -tc /etc/shibboleth/shibboleth2.xml
</code>

Výstup by měl zobrazit informaci //overall configuration is loadable// bez chyb anebo kritických zpráv. Pokud je vše v pořádku, restartujeme démona Shibboleth:

<code bash>
systemctl restart shibd
</code>

Pokud vše proběhne bez problémů, můžeme smazat starý certifikát a klíč:

<code bash>
rm -i /etc/shibboleth/sp-{cert,key}.pem
</code>