Aller au contenu

Configuration rapide du plugin SAML

Changements majeurs à partir de la version 10.1.0

La version 10.1.0 apporte des modifications importantes au plugin SAML, qui nécessitent une mise à jour de la configuration. Si vous effectuez une mise à jour à partir d'une version inférieure, veuillez vous référer à la section Modifications à partir de la version 10.1.0.

Info

Cette procédure est destinée aux habitués. Se reporter à la page la documentation principale en cas de problème.

Configuration

Cette partie détaille les étapes de configuration nécessaires à l'installation du plugin SAML. Ici seront abordées les principales actions à réaliser, ainsi que les options pouvant être choisies.

Les étapes nécessaires à l'installation du plugin sont les suivantes :

  1. Déploiement du binaire ;
  2. Génération d'une clé privée et d'un certificat ;
  3. Configuration de l'IdP et récupération de ses métadonnées ;
  4. Configuration de l'application ;
  5. Démarrage de Squash TM.

1. Déploiement du binaire

À partir du dossier $SQUASH_HOME/plugin-files/saml/security.saml-X.Y.Z/plugins, copier le fichier .jar et le coller dans le dossier du même nom dans l'application Squash TM $SQUASH_HOME/plugins/.

2. Génération d'une clé privée et d'un certificat

Création de la clé privée au format PKCS8

À partir de la version 10, Squash TM n'utilise plus de keystore pour stocker les clés privées et les certificats. Il est donc nécessaire de générer une clé privée au format PKCS8 et un certificat pour la configuration du plugin SAML.

La commande suivante permet de générer une clé privée au format PKCS8 : 

openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out private_key.pem

Exporter le certificat pour l'importer dans les métadonnées

Ensuite, la commande suivante permet d'exporter la clé privée sous forme de certificat valable un an (ajuster la durée si nécessaire) : 

openssl req -x509 -new -key private_key.pem -sha256 -days 365 -out squashtm.cer

3. Configuration de l'IdP et récupération de ses métadonnées

Se connecter à l'IdP ou demander au fournisseur l'URL des métadonnées de ce dernier.

Soit un fichier XML du type FederationMetadata.xml sera disponible, soit une URL qui donne accès à ce fichier (bien souvent les deux). Il convient de récupérer ce dernier ou cette dernière car Squash TM en a besoin pour démarrer.

Il faut s'assurer que l'entityID est correctement déclaré sur l'IdP, conformément à celui défini dans le fichier de métadonnées du SP.

Utilisation du fichier "en dur"

  1. Télécharger le fichier dans $SQUASH_HOME/conf/saml/ avec wget ou curl et l'appeler FederationMetada.xml si ce n'est pas déjà le cas ;
  2. Noter le chemin d'accès au fichier ;
  3. Donner le droit de lecture à Squash TM sur le fichier.

Déclaration de l'URL

  1. Récupérer l'URL ;
  2. La tester depuis le serveur Squash (wget ou curl) ;
  3. La sauvegarder pour la prochaine étape.

4. Configuration de l'application

Utilisation d'un fichier dédié

  1. Copier le fichier config/squash.tm.cfg-saml.properties et le coller dans le répertoire de configuration déjà déclaré qui en général est SQUASH_HOME/conf ;

  2. Puis, éditer le fichier de configuration principal SQUASH_HOME/conf/squash.tm.cfg.properties et lui associer le fichier de configuration du plugin en lui ajoutant/éditant la propriété suivante :

    spring.profiles.include=saml

Si cette propriété était déjà présente, il est possible d'ajouter saml à la liste, séparé par une virgule.

(Alternative) Intégration des propriétés

Il est possible par souci de praticité, de simplement copier et coller le contenu du fichier de configuration du plugin dans le fichier de configuration principal, sans avoir besoin d'ajouter SAML à la liste des profils.

Configuration minimale

Le fichier de configuration propose de nombreuses propriétés, mais seulement certaines d'entre elles sont obligatoires. Squash TM ne démarrera pas / ne fonctionnera pas correctement si ces propriétés sont laissées vides ou ne sont pas renseignées correctement.

Les propriétés listées ci-dessous sont requises. Les détails (valeurs autorisées, etc.) sont disponibles dans les commentaires du fichier squash.tm.cfg-saml.properties, et plus loin dans cette même documentation.

saml.enabled : Interrupteur principal. Cette propriété permet d'activer ou de désactiver le plugin sans commentaire et sans avoir à supprimer le fichier jar.

saml.idp.metadata-url : L'emplacement des métadonnées du Fournisseur d'identité. Les protocoles file://, http:// et https:// sont autorisés. Par exemple, file:///opt/squash-tm/conf/saml/FederationMetadata.xml ou https://login.microsoftonline.com/entreprise.onmicrosoft.com/FederationMetadata/2007-06/FederationMetadata.xml.

saml.sp.registration-id : Identifiant unique utilisé pour enregistrer votre Service Provider (SP) dans la configuration SAML du plugin. Par exemple : google.

saml.sp.entity-id : Identifiant unique de l'instance Squash. Cette valeur doit être unique au sein de votre écosystème d'authentification et sera communiquée à l'IdP (Identity Provider). Par exemple : urn:squash-tm:saml ou https://squash-tm.votre-entreprise.com/saml.

saml.sp.metadata.private-key : Clé privée au format PKCS8 utilisée par le Service Provider (SP) pour signer les requêtes et déchiffrer les messages.

saml.sp.metadata.certificate : Certificat X.509 du Service Provider (SP) utilisé pour la validation des signatures et le chiffrement.

Configuration avancée

Il est très fréquent que Squash TM soit derrière un mandataire inverse (un reverse proxy). Si c'est le cas, il est nécessaire d'utiliser les options suivantes :

  • saml.proxy.enabled : Mettre true ;
  • saml.proxy.server-name : Mettre une URL du type squash.domaine.fr ;
  • saml.proxy.scheme : Mettre https en général ;
  • saml.proxy.server-port : Mettre 443 en général ;
  • saml.proxy.include-port-in-url : Mettre true.

5. Démarrage de Squash TM

  • Démarrer Squash TM et surveiller les logs. Les logs doivent afficher quelques lignes contenant le mot "SAML" et contenir le message "Started SquashTm in XX.XXX seconds".

  • Une fois Squash TM démarré, les métadonnées du SP seront accessibles à l'URL /auth/saml/metadata/{registrationId}.

Conventions

Format des chemins de fichiers

Les métadonnées peuvent être récupérées à la lecture en tant que fichiers locaux ou à distance via des appels HTTP(S) en utilisant la propriété saml.idp.metadata-url.

Via HTTP(S) : le chemin du fichier est l'URL à partir de laquelle il peut être téléchargé. Le protocole est soit http://, soit https://. Exemple : https://votre.idp/metadonnees.xml.

Via un chemin absolu : URL menant à un fichier local qui fonctionne bien en tant que chemin absolu. Dans ce cas, le protocole est file://. Exemple : file:///dev/squashtm/saml/idp.xml (sous Linux), file://C:/dossierappli/squashtm/conf/idp.xml (sous Windows).

Via un chemin relatif vers le dossier de configuration : Tout chemin qui n'a pas de protocole défini sera considéré comme étant un chemin relatif vers le dossier de configuration. L'emplacement du dossier de configuration peut varier selon l'environnement et le mode d'installation choisi pour Squash TM. Exemple : saml/idp.xml devient $CONF_DIR/saml/idp.xml.

Modifications à partir de la version 10.1.0

Avec la version 10.1.0, des modifications importantes ont été apportées à la configuration du plugin SAML. Ces changements doivent impérativement être pris en compte pour assurer le bon fonctionnement de l'application, en mettant à jour le fichier de configuration.

1. Nouvelles propriétés obligatoires

De nouvelles propriétés sont désormais requises pour permettre le démarrage de l'application :

Propriété Description
saml.sp.registration-id Identifiant d'enregistrement SAML (ex : okta, azure-ad)
saml.sp.metadata.private-key Clé privée au format PKCS#8 du SP pour signature et déchiffrement
saml.sp.metadata.certificate Certificat X.509 du SP
saml.idp.metadata-url URL du fichier XML fourni par l'IdP (remplace saml.idp.metadata.url)

2. Fin du support du keystore

L'utilisation d'un keystore JKS n'est plus supportée. La configuration repose désormais uniquement sur :

  • une clé privée (au format PKCS#8) pour signer les requêtes SAML envoyées au fournisseur d'identité et déchiffrer les assertions chiffrées reçues.
  • un certificat X.509 communiqué au fournisseur d'identité, permettant la vérification des signatures des requêtes et le chiffrement des assertions.

Les certificats du fournisseur d'identité sont récupérés automatiquement à partir du fichier de métadonnées XML fourni par ce dernier.

Voici comment extraire votre clé privée et votre certificat à partir d'un fichier keystore.jks.

Étape 1 : Convertir JKS → PKCS#12

keytool -importkeystore \
  -srckeystore keystore.jks \
  -destkeystore keystore.p12 \
  -deststoretype PKCS12 \
  -srcalias <alias> \
  -deststorepass <mot_de_passe> \
  -srcstorepass <mot_de_passe>

Étape 2 : Extraire la clé privée (format PEM)

openssl pkcs12 -in keystore.p12 -nocerts -nodes -out key.pem

Étape 3 : Convertir la clé privée en PKCS#8

openssl pkcs8 -topk8 -inform PEM -outform PEM -in key.pem -out private_key.pem -nocrypt

3. Génération automatique des métadonnées SP

Les métadonnées du fournisseur de service sont désormais générées automatiquement au démarrage de l'application et sont accessibles via l'URL : /auth/saml/metadata/{registration-id} où registration-id est la valeur de la propriété saml.sp.registration-id.

Vous devez impérativement transmettre ces métadonnées à votre fournisseur d'identité pour que la connexion SAML fonctionne correctement.

4. Chargement XML unique pour les métadonnées du fournisseur d'identité

La surcharge des configurations des métadonnées du fournisseur d'identité via des propriétés n'est plus supportée. La configuration du fournisseur d'Identité repose exclusivement sur le fichier XML de métadonnées, toutes les informations nécessaires (certificats, endpoints, etc.) sont extraites automatiquement à partir de celui-ci.
En conséquence, toutes les propriétés saml.idp.*, à l'exception de saml.idp.metadata-url, ne sont plus disponibles.

5. Changement des endpoints SAML

Les endpoints SAML requièrent désormais la présence du paramètre registrationId dans l'URL, ce dernier devant correspondre à la valeur de la propriété saml.sp.registration-id.

Ancien endpoint Nouvel endpoint
/auth/saml/login /auth/saml/login/{registration-id}
/auth/saml/SSO /auth/saml/sso/{registration-id}
/auth/saml/metadata /auth/saml/metadata/{registration-id}