cs:tech:sp:shibboleth:rollover

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 https://sp.example.org/shibboleth
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é 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í:

# 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

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:

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

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:

shibd -tc /etc/shibboleth/shibboleth2.xml

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:

systemctl restart shibd

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 https://sp.example.org/Shibboleth.sso/Metadata 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:

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

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

shibd -tc /etc/shibboleth/shibboleth2.xml

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:

systemctl restart shibd

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:

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

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

shibd -tc /etc/shibboleth/shibboleth2.xml

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:

systemctl restart shibd

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

rm -i /etc/shibboleth/sp-{cert,key}.pem
Last modified:: 2019/12/13 20:12