====== Výměna podpisového certifikátu metadat ======

<WRAP center important>
Agregátor metadat byl přepnut a na stávajících URL adresách se již generují metadata podepsaná novým certifikátem.

URL adresy uvedené níže (tedy s 2021 v názvu) jsou však stále platné.

Tato stránka zde zůstává z informačních důvodů.
</WRAP>


V neděli 14. února 2021 vyprší podpisový certifikát pro metadata federací spravovaných sdružením CESNET, která jsou dostupná na serveru <wrap hi>metadata.eduid.cz</wrap>.

Nově vygenerovaný certifikát obsahuje stejný veřejný klíč, jiná je tedy pouze platnost a otisk.

Implementace protokolu SAML by s platností certifikátu neměly nijak nakládat a měly by ji ignorovat. To je důvod, proč ve většině případů expirovaný certifikát (např. v metadatech) nijak neohrožuje funkčnost. <wrap em>Jsou však implementace, které platnost kontrolují navzdory standardům a doporučením, proto je vhodné tuto změnu provést.</wrap>

<WRAP center info>
**Narazíte-li na nějaký problém, nebo budete-li mít nějaký dotaz, neváhejte a napište na adresu [[info@eduid.cz]].**
</WRAP>

===== Plán výměny certifikátu =====

Již nyní generujeme nejen metadata podepsaná stávajícím certifikátem (na stávajících URL adresách), ale i metadata podepsaná novým certifikátem (na nových dočasných URL adresách).

V průběhu čtvrtka 11. února začneme metadata podepsaná novým certifikátem umísťovat na stávající URL adresy a nové dočasné URL adresy budou fungovat jako přesměrování.

<wrap em>Čili pokud změníte kvůli otestování svou konfiguraci, nebudete muset následně už nic dělat.</wrap>

===== Výsledky testování =====

Jelikož nově vygenerovaný podpisový certifikát obsahuje stejný veřejný klíč jako brzy expirující certifikát, tak v případě, že máte implementaci odpovídající standardům a doporučení, není víceméně nutné tento podpisový certifikát měnit.

Při testování Shibboleth IdP a Shibboleth SP jsme posunuli čas tak, aby současný podpisový certifikát byl expirovaný a následně jsme ověřovali stávající (i nová) metadata a to pomocí jak expirovaného, tak nového certifikátu. Shibboleth IdP i Shibboleth SP si korektně stáhl metadata (stará i nová) a bez problémů je ověřil jak novým, tak expirovaným certifikátem (právě kvůli stejnému veřejnému klíči).

Při testování SimpleSAMLphp, které používalo pro ověření metadat certifikát, vše fungovalo úplně stejně jako v případě Shibbolethu. <wrap hi>Nicméně pokud SimpleSAMLphp používalo namísto certifikátu jen jeho otisk, tak ověření samozřejmě selhalo, protože nový certifikát má logicky otisk jiný.</wrap>

Následující tabulka shrnuje výsledky testování Shibboleth IdP, Shibboleth SP a SimpleSAMLphp (jako SP) při ověřování platnosti metadat pomocí podpisového certifikátu.

^                    ^ Expirovaný certifikát ^ Nový certifikát ^
^ Stávající metadata | V pořádku             | V pořádku       |
^ Nová metadata      | V pořádku             | V pořádku       |

<WRAP center tip>
**Přesto však důrazně doporučujeme na výsledky našeho testování nespoléhat a to zejména při použití jiné implementace než Shibboleth anebo SimpleSAMLphp s certifikátem.**
</WRAP>

===== Nový certifikát + nová metadata =====

Nový certifikát je již k dispozici na webu:

  * [[https://www.eduid.cz/docs/metadata2021.eduid.cz.crt.pem]]

Pomocí tohoto certifikátu již podepisujeme metadata, která jsou však umístěna na jiných URL adresách. Kdo chce mít 100% jistotu, že jeho služba nebude nijak postižena po přepnutí, ať si vyzkouší stahovat nová metadata a kontrolovat jejich podpis novým certifikátem.

Nová metadata mají oproti těm stávajícím v názvu přidán současný rok, tedy "2021", vizte následující tabulky:

==== eduID.cz ====

^ Starý certifikát     ^ Nový certifikát                                 ^
| eduid                | eduid<color #ed1c24>2021</color>                |
| eduid+idp            | eduid<color #ed1c24>2021</color>+idp            |
| eduid+idp+avcr       | eduid<color #ed1c24>2021</color>+idp+avcr       |
| eduid+idp+cesnet     | eduid<color #ed1c24>2021</color>+idp+cesnet     |
| eduid+idp+hospital   | eduid<color #ed1c24>2021</color>+idp+hospital   |
| eduid+idp+library    | eduid<color #ed1c24>2021</color>+idp+library    |
| eduid+idp+other      | eduid<color #ed1c24>2021</color>+idp+other      |
| eduid+idp+university | eduid<color #ed1c24>2021</color>+idp+university |
| eduid+sp             | eduid<color #ed1c24>2021</color>+sp             |

==== eduGAIN ====

^ Starý certifikát ^ Nový certifikát                        ^
| edugain          | edugain<color #ed1c24>2021</color>     |
| edugain+idp      | edugain<color #ed1c24>2021</color>+idp |
| edugain+sp       | edugain<color #ed1c24>2021</color>+sp  |

==== Social IdPs ====

^ Starý certifikát ^ Nový certifikát                       ^
| socialidps       | socialidps<color #ed1c24>2021</color> |

==== Standalone IdPs ====

^ Starý certifikát ^ Nový certifikát                           ^
| standaloneidps   | standaloneidps<color #ed1c24>2021</color> |

==== CESNET-int ====

^ Starý certifikát ^ Nový certifikát                           ^
| cesnet-int       | cesnet-int<color #ed1c24>2021</color>     |
| cesnet-int+idp   | cesnet-int<color #ed1c24>2021</color>+idp |
| cesnet-int+sp    | cesnet-int<color #ed1c24>2021</color>+sp  |

===== Konfigurační změny =====

==== Shibboleth IdP ====

Shibboleth IdP by měl nadále fungovat bez jakéhokoliv konfiguračního zásahu. Nicméně i tak doporučujeme provést změnu zdroje metadat a certifikátu. Tím otestujete, že až přestaneme generovat stará metadata, vše bude fungovat.

Předpokládáme, že máte Shibboleth IdP nainstalován dle našeho [[cs:tech:idp|návodu]] v adresáři ''/opt/shibboleth-idp/''.

V souboru ''conf/metadata-providers.xml'' musíte u elementu ''<MetadataProvider>'' změnit atribut ''metadataURL'' dle výše uvedených "převodních tabulek" a také v elementu ''<MetadataFilter>'' upravit atribut ''certificateFile''.

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

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

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

</MetadataProvider>
</code>

Musíte také stáhnout nový podpisový certifikát, např. následujícím příkazem:

<code bash>
# Stažení nového podpisového certifikátu metadata2021.eduid.cz.crt.pem
wget -P /opt/shibboleth-idp/credentials \
    https://www.eduid.cz/docs/metadata2021.eduid.cz.crt.pem
</code>

<WRAP center tip>
Můžete též smazat keš metadat v adresáři ''/opt/shibboleth-idp/metadata/'', ale nemažte soubor ''idp-metadata.xml'' obsahující metadata vašeho IdP, která jsou dostupná na <nowiki>https://HOSTNAME/idp/shibboleth</nowiki>.
</WRAP>

Po provedení výše uvedených změn nezapomeňte restartovat Jetty:

<code bash>
# Restart Jetty
systemctl restart jetty9
</code>

==== Shibboleth SP ====

Shibboleth SP by měl nadále fungovat bez jakéhokoliv konfiguračního zásahu. Nicméně i tak doporučujeme provést změnu zdroje metadat a certifikátu. Tím otestujete, že až přestaneme generovat stará metadata, vše bude fungovat.

Předpokládáme, že máte Shibboleth SP nainstalován z distribučního balíčku dle našeho [[cs:tech:sp:shibboleth|návodu]] v adresáři ''/etc/shibboleth/''.

V souboru ''shibboleth2.xml'' musíte u elementu ''<MetadataProvider>'' změnit atribut ''url'' dle výše uvedených "převodních tabulek" a také v elementu ''<MetadataFilter>'' upravit atribut ''certificate''.

<code xml>
<!-- eduID.cz -->
<MetadataProvider type="XML" validate="true"
    url="https://metadata.eduid.cz/entities/eduid2021+idp"
    backingFilePath="eduid+idp.xml" maxRefreshDelay="900">

    <MetadataFilter type="RequireValidUntil" maxValidityInterval="2419200"/>
    <MetadataFilter type="Signature" certificate="metadata2021.eduid.cz.crt.pem" verifyBackup="false"/>
</MetadataProvider>
</code>

Musíte také stáhnout nový podpisový certifikát, např. následujícím příkazem:

<code bash>
# Stažení nového podpisového certifikátu metadata2021.eduid.cz.crt.pem
wget -P /etc/shibboleth/ \
    https://www.eduid.cz/docs/metadata2021.eduid.cz.crt.pem
</code>

<WRAP center tip>
Můžete též smazat keš metadat v adresáři ''/var/cache/shibboleth/''.
</WRAP>

Po provedení výše uvedených změn nezapomeňte restartovat Shibboleth SP:

<code bash>
# Restart Shibboleth démona
systemctl restart shibd
</code>

==== SimpleSAMLphp SP ====

U SimpleSAMLphp jsme dříve doporučovali používat ke kontrole metadat pouze otisk podpisového certifikátu. To se v konfiguračním souboru ''config-metarefresh.php'' konfigurovalo pomocí volby ''validateFingerprint'' následovně.

<code php>
# Dřívější nastavení v konfiguračním souboru config/config-metarefresh.php
# Starý metadata feed
# Používá pouze otisk podpisového certifikátu
$config = [

  'sets' => [

    # eduID.cz
    'eduidcz' => [
      'cron' => ['hourly'],
      'sources' => [
        [
          'src' => 'https://metadata.eduid.cz/entities/eduid+idp',
          'validateFingerprint' => '2E:51:FC:08:CF:15:C5:15:48:28:AF:64:A7:97:50:80:B4:AB:5D:24',
        ],
      ],
      'expireAfter' => 60*60*24*4, // Maximum 4 days cache time.
      'outputDir' => 'metadata/eduidcz/',
      'outputFormat' => 'flatfile',
    ],

  ],
];
</code>

Nyní je však nutné tuto volbu opravit, protože metadata jsou podepisována novým certifikátem, který má jiný otisk. Současná konfigurace tedy způsobí, že nově stažená metadata nebudou považována za platná a přestanou se tak aktualizovat. Až vyprší jejich platnost (atribut ''validUntil'' v elementu ''<EntitiesDescriptor>'' v metadatech), služba nebude fungovat.

Buď můžete upravit otisk (to bude fungovat, ale není to optimální) anebo začít používat ke kontrole certifikát (to je optimální).

Smažte (nebo zakomentujte) volbu ''validateFingerprint'' a přidejte ''certificates'' dle ukázky níže:

<code php>
# Nové nastavení v konfiguračním souboru config/config-metarefresh.php
# Nový metadata feed
# Používá se podpisový certifikát, nikoliv jen jeho otisk
$config = [

  'sets' => [

    # eduID.cz
    'eduidcz' => [
      'cron' => ['hourly'],
      'sources' => [
        [
          'src' => 'https://metadata.eduid.cz/entities/eduid2021+idp',
          'certificates' => [
            'metadata2021.eduid.cz.crt.pem',
          ],
        ],
      ],
      'expireAfter' => 60*60*24*4, // Maximum 4 days cache time.
      'outputDir' => 'metadata/eduidcz/',
      'outputFormat' => 'flatfile',
    ],

  ],
];
</code>

Je také potřeba mít stažený podpisový certifikát a to v podadresáři ''cert/'' uvnitř adresáře se SimpleSAMLphp. V případě, že máte SimpleSAMLphp v adresáři ''/opt/simplesamlphp/'', stáhněte nový podpisový certifikát následujícím příkazem:

<code bash>
# Stažení certifikátu pro ověření metadat federace
wget -P /opt/simplesamlphp/cert/ \
     https://www.eduid.cz/docs/metadata2021.eduid.cz.crt.pem
</code>

<WRAP center tip>
Můžete též smazat keš metadat v adresáři ''/opt/simplesamlphp/metadata/<ODPOVÍDAJÍCÍ_ADRESÁŘ_DLE_VAŠÍ_KONFIGURACE>''.
</WRAP>

Následně aktualizujte metadata tak, jak jste obyčejně zvyklí, nebo se přihlaste do webového administračního rozhraní SimpleSAMLphp a v záložce **Federation** zvolte v sekci **Tools** odkaz pro aktualizaci metadat nazvaný **Metarefresh: fetch metadata**.

==== Ostatní implementace ====

Doporučuji, abyste ve svém vlastním zájmu aktualizovali zdroj metadat (dle výše uvedené "převodní tabulky"), stáhli si nový podpisový certifikát, smazali keš metadat a ověřili, že si vaše implementace stáhne bez problémů nová metadata a ověří je.