Click here for the english version

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

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

Avertissement:
Le renouvellement du certificat SAML d'un IDP 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-dessous sont uniquement applicables à un IDP Shibboleth.

!! Avertissement pour les implémentations de SP autres que Shibboleth ou SimpleSAMLphp !!

Certaines implémentations de SP autres que Shibboleth ou SimpleSAMLphp ne seront pas capables de gérer correctement le renouvellement de certificat au niveau de l’IDP :
  • Soit le SP ignorera le certificat additionnel dans les méta-données pour n'utiliser que le premier ou le second certificat (cas 1) ;
  • Soit le SP ne sera pas capable de recharger régulièrement les métadonnées et pas conséquent n’aura jamais connaissance d’un nouveau certificat pour l’IDP (cas 2).

Dans les deux cas, les SP concernés échoueront à vérifier la signature de l’assertion SAML de l’IDP et la communication avec cet IDP échouera de facto :

  • Dans le cas 1, le retour à un fonctionnement normal interviendra une fois la procédure de renouvellement effectuée et l’ancien certificat supprimé des métadonnées lors de l’étape 3 ;
  • Dans le cas 2, le retour à un fonctionnement normal interviendra une fois que la configuration du SP aura été mise à jour manuellement avec le nouveau certificat de l’IDP après l’étape 2.

Pour ce type de SP, il est ainsi recommandé dans la mesure du possible de procéder à l'opération de renouvellement du certificat en Heures Non Ouvrables afin de minimiser l'impact sur les utilisateurs du service.

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 l'IDP, exécutez les commandes suivantes en tant que root :

Cliquez pour afficher ⇲

Cliquez pour masquer ⇱


# cd /opt/shibboleth-idp/credentials

# sudo java -cp “../webapp/WEB-INF/lib/*:../bin/lib/*” \
net.shibboleth.utilities.java.support.security.SelfSignedCertificateGenerator \
–lifetime 3 \
–certfile idp.crt.new \
–keyfile idp.key.new \
–hostname aai-logon.example.org \
–uriAltName https://aai-logon.example.org/idp/shibboleth

# sudo chmod 600 idp.key.new

# sudo chown –reference idp.key idp.key.new



Avec les commandes ci-dessus, un nouveau couple certificat/clé privé est généré dans le répertoire /opt/shibboleth-idp/credentials.


Etape 1: ajouter le nouveau certificat aux métadonnées

Attention : dans le cas de SP non basé sur Shibboleth ou SimpleSAMLphp, veuillez lire attentivement la note de mise en garde ci-dessus.

Cette étape peut être effectuée immédiatement après l’étape 0.
Maintenant qu’un nouveau certificat a été généré pour l’IDP (non activé pour le moment), ce dernier peut être publié dans les métadonnées afin qu’il soit propagé aux SP de la fédération Education-Recherche.

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

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

1.3 Ajoutez ensuite le contenu du nouveau certificat de l’IDP /opt/shibboleth-idp/credentials/idp.crt.new 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).

1.4 Soumettez les modifications.

Important :
La déclaration du nouveau certificat de l'IDP en tant que “Certificat SAML courant” et le passage de l'ancien certificat en “Certificat SAML temporaire” sur le guichet se traduit comme suit dans les métadonnées :
- Le nouveau certificat de l'IDP apparait comme 1er certificat pour un usage de type signature (signing) et un usage de type chiffrement (encryption);
- L'ancien certificat de l'IDP apparait comme second certificat pour un usage de type signing uniquement.

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 SP de la Fédération Education-Recherche. D'un SP à 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 SP de la fédération Education-Recherche aient téléchargé le nouveau fichier de métadonnées.

Pendant cette période transitoire, à la fois les SP ayant téléchargé le nouveau fichier de métadonnéees (avec l’ancien certificat de l’IDP déclaré en tant que 2nd certificat de signature) et ceux disposant toujours de l’ancienne version du fichier (avec l’ancien certificat de l’IDP déclaré en tant que 1er certificat de signature) seront en mesure de vérifier les assertions signées par l’IDP avec l’ancien certificat (le SP shibboleth testant l’ensemble des certificats de signature à disposition dans les métadonnées).

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 SP de la fédération Education-Recherche aient téléchargé le nouveau fichier de métadonnées.


Etape 2: configurer l'IDP pour utiliser le nouveau certificat

Après un laps de temps d’au moins 48 heures, tous les SP de la Fédération Education-Recherche devraient avoir téléchargé le dernier fichier de métadonnées, qui inclut le nouveau certificat de l’IDP.

2.1 Consécutivement, l’IDP peut maintenant être configuré pour utiliser le nouveau certificat en effectuant les opérations suivantes :

Cliquez pour afficher ⇲

Cliquez pour masquer ⇱


Sauvegarde des anciens fichiers:
# sudo mv /opt/shibboleth-idp/credentials/idp.key /opt/shibboleth-idp/credentials/idp.key.bak.0
# sudo mv /opt/shibboleth-idp/credentials/idp.crt /opt/shibboleth-idp/credentials/idp.crt.bak.0

Activation des nouveaux fichiers:
# sudo mv /opt/shibboleth-idp/credentials/idp.key.new /opt/shibboleth-idp/credentials/idp.key
# sudo mv /opt/shibboleth-idp/credentials/idp.crt.new /opt/shibboleth-idp/credentials/idp.crt



2.2 Redémarrer ensuite le conteneur de servlet (e.g Tomcat). Dans le cas de Tomcat, la commande à exécuter en tant que root est la suivante :

Cliquez pour afficher ⇲

Cliquez pour masquer ⇱


Pour ubuntu :
# sudo service tomcat7 restart

Pour RHEL 7 / CentOS 7 :
# sudo systemctl restart tomcat.service




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

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

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

3.2 Supprimer l’ancien certificat enregistré au niveau du champ « Certificat X.509 SAML temporaire ».

3.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 SP de la fédération Education-Recherche.