Click here for the english version

Procédure pour renouveler le certificat SAML d'un SP Shibboleth

La procédure décrite ci-dessous permet de remplacer le certificat d’un SP Shibboleth sans interruption de service.

Avertissement:
Le renouvellement du certificat SAML d'un SP est une opération sensible qui ne peut pas être réalisée en une seule étape.

Il est en particulier nécessaire de tenir compte du temps de propagation des métadonnées à l'ensemble des autres entités SAML de la fédération.

Afin de réaliser cette opération sans interruption de service, il est crucial de respecter l'ordre et le timing des instructions décrites ci-après.

1. Périmètre

Veuillez noter que les instructions décrites ci-après sont uniquement applicables à un SP Shibboleth 2.x.

Si vous utilisez un SP SimpleSAMLphp, veuillez consulter la procédure de renouvellement SimpleSAMLphp et adapter les étapes ci-dessous en conséquence.

2. Instructions

Etape 0 : créer un nouveau certificat

RENATER recommande l’utilisation de certificats auto-signés pour Shibboleth. Pour générer un nouveau certificat auto-signé pour votre SP, exécutez les commandes suivantes :

Cliquez pour afficher ⇲

Cliquez pour masquer ⇱


Utilisation du répertoire tmp pour générer le nouveau couple certificat/clé privé:
# cd /tmp

Copie du fichier key courant vers le répertoire tmp en préservant les permissions du fichier:
# cp -p /etc/shibboleth/sp-key.pem sp-key-temp.pem

Génération d’un nouveau couple certificat/clé privée (-h : SP hostname / -e: SP entityID):
# /opt/shibboleth-sp/etc/shibboleth/keygen.sh -y 3 -h www.example.org -e https://www.example.org/shibboleth

Copie du contenu vers fichier key temporaire avec les persmissions de fichier correct:
# cat sp-key.pem > sp-key-temp.pem

Déplacement du fichier key temporaire vers le répertoire cible:
# mv sp-key-temp.pem /etc/shibboleth/sp-key-2018.pem

Nettoyage:
# rm sp-key.pem

Copie du certificat vers le répertoire cible:
# mv sp-cert.pem /etc/shibboleth/sp-cert-2018.pem


Important : assurez-vous que le fichier key /etc/shibboleth/sp-key-2018.pem est bien accessible en lecture par l’utilisateur qui exécute le démon shibd.


Etape 1 : configurer le nouveau certificat comme certificat additionnel pour le SP

Avant d’ajouter le nouveau certificat dans les métadonnées de la fédération, ce dernier doit d’abord être ajouté à la configuraton du SP.

1.1 Dans le fichier de configuration du SP (shibboleth2.xml), remplacer l’élément CredentialResolver avec le suivant :

Important: veillez bien à respecter l’ordre de déclaration en ajoutant le nouveau certificat après l’ancien (les certificats sont utilisés selon cet ordre).
/etc/shibboleth/shibboleth2.xml
<!-- 
Certificate/Private key pairs are read in sequence. 
Unless specificially defined only the first CredentialResolver is used for attribute requests.
More info: https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPCredentialResolver
-->
 
<CredentialResolver type="Chaining">
 
    <!-- Active certificate -->
    <CredentialResolver type="File"
                        key="/etc/shibboleth/sp-key.pem" 
                        certificate="/etc/shibboleth/sp-cert.pem"/>
 
    <!-- Additional new certificate -->
    <CredentialResolver type="File"
                        key="/etc/shibboleth/sp-key-2018.pem" 
                        certificate="/etc/shibboleth/sp-cert-2018.pem"/>
 
</CredentialResolver>

1.2 Après avoir ajouté le nouveau certificat comme certificat additionnel, il est recommandé de vérifier la configuration (en tant qu’administrateur ou root) avec la commande suivante :


# shibd -tc /etc/shibboleth/shibboleth2.xml



1.3 Redémarrer ensuite le démon Shibboleth :


# service shibd restart




Etape 2 : ajouter le nouveau certificat aux méta-données

Cette étape peut être réalisée immédiatement après l’étape 1.
Maintenant que le SP a le nouveau certificat configuré en tant que certificat additionnel, ce dernier peut être publié dans les métadonnées via le guichet afin qu’il soit propagé aux IDP de la fédération.

2.1 Connectez-vous au guichet de la fédération et accédez à la page d'édition de votre SP (onglet informations techniques).

2.2 Commencez par copier le contenu du champ Certificat X.509 SAML courant dans le champ Certificat X.509 SAML temporaire.

2.3 Copier le contenu du nouveau certificat du SP /etc/shibboleth/sp-cert-2018.pem dans le champ Certificat X.509 SAML courant en remplacement du contenu précédent (copier les lignes du certificat comprises entre BEGIN CERTIFICATE et END CERTIFICATE mais sans ces deux lignes).

2.4 Soumettez les modifications.

Important: Le certificat principal d'un SP (champ Certificat X.509 SAML courant du guichet) apparaît deux fois dans les méta-données, sous la forme d'éléments XML KeyDescriptor ayant un attribut use différent : encryption et signing.

Lorsque vous déclarez un second certificat pour un SP (via le champ Certificat X.509 SAML temporaire du guichet), il n'est publié que pour un usage de type signing, pas encryption.

Une fois les modifications enregistrées sur le guichet, il vous faudra tenir compte du temps de propagation des nouvelles méta-données à l’ensemble des IDP de la Fédération Éducation-Recherche. D'un IDP à l'autre, ce temps de propagation peut varier selon la version des métadonnées utilisée et la fréquence de rechargement configurée pour les métadonnées. Plus de détails sur cette page.

Au maximum cela prendra 48 heures avant que l’ensemble des IDPs de la Fédération Éducation-Recherche utilisent le nouveau fichier de métadonnées.

Pendant cette période transitoire, les IDP ayant téléchargé le nouveau fichier de métadonnées utiliseront le nouveau certificat pour chiffrer les assertions SAML à destination du SP. Ceux n’ayant pas encore téléchargé le nouveau fichier de métadonnées utiliseront en revanche l’ancien certificat.

Le SP ayant les deux certificats positionnés au niveau de sa configuration, il sera en mesure de déchiffrer les assertions SAML transmises dans ces deux cas de figure par les IDP.

Attention : Par mesure de précaution, afin de s'assurer que l'ensemble des IDP aient téléchargé le dernier fichier de métadonnées, il est important de ne pas réaliser l’étape suivante avant que ce laps de temps de 48 heures se soit écoulé.


Etape 3 : configurer le SP pour utiliser le nouveau certificat

Après un laps de temps d’au moins 48 heures, tous les IDP de la Fédération Educaton-Recherche devraient avoir téléchargé le dernier fichier de métadonnées, qui inclut le nouveau certificat. Consécutivement, le SP peut maintenant être configuré pour utiliser le nouveau certificat comme certificat principal et conserver l’ancien en tant que certificat additionnel.

3.1 Positionnez le nouveau certificat avant l’ancien en changeant l’ordre des éléments CredentialResolver dans le fichier de configuration du SP shibboleth2.xml :

/etc/shibboleth/shibboleth2.xml
<!-- 
Certificate/Private key pairs are read in sequence.
Unless specificially defined only the first 
CredentialResolver is used for attribute requests.
More information:
https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPCredentialResolver
-->
<CredentialResolver type="Chaining">
    <!-- Active certificate -->
    <CredentialResolver type="File"
                        key="/etc/shibboleth/sp-key-2018.pem" 
                        certificate="/etc/shibboleth/sp-cert-2018.pem"/>
     <!-- Additional old certificate -->
     <CredentialResolver type="File"
                         key="/etc/shibboleth/sp-key.pem" 
                         certificate="/etc/shibboleth/sp-cert.pem"/>
</CredentialResolver>

3.2 Après avoir appliqué la modification, vérifier la configuration en redémarrant le démon Shibboleth:


# shibd -tc /etc/shibboleth/shibboleth2.xml



3.3 Redémarrer ensuite le démon shibd :


# service shibd restart




Etape 4 : supprimer l'ancien certificat des métadonnées

Cette étape peut être réalisée immédiatement après l’étape 3.

4.1 Connectez-vous au guichet de la fédération et accéder à la page d’édition de votre SP (onglet informations techniques).

4.2 Supprimer le contenu associé à l'ancien certificat apparaissant au niveau du champ Certificat X.509 SAML temporaire.

4.3 Soumettez les modifications.

Après soumission des modifications, cela prendra encore une fois 48 heures maximum avant que la modification soit propagée à l’ensemble des IDP de la Fédération Éducation-Recherche.

Attention: Par mesure de précaution, il est important d’attendre au moins 48 heures avant de réaliser l'étape suivante, de manière à être sûr que l’ensemble des IDP de la Fédération Éducation-Recherche aient téléchargé le nouveau fichier de métadonnées.


Etape 5 : Supprimer l'ancien certificat de la configuration du SP

Après un laps de temps d'au moins 48 heures, l’ancien certificat peut être retiré de la configuration du SP (recommandé pour raison de sécurité).

5.1 Plutôt que de le supprimer, il est conseillé de commenter l’ancien certificat dans le fichier de configuration shibboleth2.xml.

/etc/shibboleth/shibboleth2.xml
<!-- 
Certificate/Private key pairs are read in sequence.
Unless specificially defined only the first 
CredentialResolver is used for attribute requests.
More information:
https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPCredentialResolver
-->
<CredentialResolver type="Chaining">
    <!-- Active certificate -->
    <CredentialResolver type="File"
                        key="/etc/shibboleth/sp-key-2018.pem" 
                        certificate="/etc/shibboleth/sp-cert-2018.pem"/>   
     <!-- Additional old certificate -->
     <!--
     <CredentialResolver type="File"
                         key="/etc/shibboleth/sp-key.pem" 
                         certificate="/etc/shibboleth/sp-cert.pem"/>
      -->
</CredentialResolver>