Aller au contenu

Configuration rapide du plugin SAML

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. Création du keystore et des métadonnées SP ;
  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 avec sa nouvelle configuration ;
  6. Tirer sur le trouble ;
  7. Validation du déploiement de SAML une fois qu'un utilisateur se connecte et que ses métadonnées sont bien renseignées dans Squash TM à la création de son compte si elle est automatique.

1. Déploiement du binaire

À partir du paquet .zip ou .tar.gz contenant le plugin, copier le fichier .jar du dossier plugins et le coller dans le dossier du même nom dans l'application Squash TM $SQUASH_HOME/plugins/.

2. Création du keystore et des métadonnées SP

Création du keystore

La commande keytool est disponible avec les JVM ou les JDK Java.

La commande suivante permet de créer un couple de clés RSA pour Squash TM avec l'algorithme de signature SHA256withRSA valable dix ans (ajuster la durée si nécessaire) : 

keytool -genkeypair -keyalg rsa -keysize 2048 -sigalg SHA256withRSA -alias squashtm -keystore keystore.jks -validity 3650

où squashtm est l'alias de la clé et keystore.jks est le nom du keystore. S'il n'existe pas déjà, le keystore sera créé dans la foulée et dans ce cas, il faudra répondre aux questions nécessaires à sa création. Veiller à bien noter les mots de passe pour le keystore et la clé.

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

Il est possible d'exporter un certificat à partir du keystore en utilisant la commande suivante : 

keytool -export -rfc -keystore keystore.jks -alias squashtm -file squashtm.cer

Configuration du fichier de metadonnées SP

Le plus simple est de ré-utiliser le fichier sp.xml fournit en exemple avec le plugin.

Il est nécessaire de modifier les champs suivants :

  • EntityID : l'identifiant de l'instance Squash ; doit être unique parmi tous les fournisseurs de service connus par l'IDP ;
  • SP X.509 Cert (pour la signature et le chiffrement) : le certificat Squash TM pouvant être obtenu comme expliqué dans Exporter un certificat.

Les valeurs par défaut peuvent être conservées pour les autres champs.

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 sp.xml.

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.metadata.url : L'emplacement des métadonnées du Fournisseur de service. Les protocoles file://, http:// et https:// sont autorisés. Par exemple : file:///opt/squash-tm/conf/saml/sp.xml.

saml.keystore.url : L'emplacement du keystore. Seul le protocole file:// est autorisé. Par exemple, file:///opt/squash-tm/conf/saml/keystore.jks.

saml.keystore.password : Le mot de passe du keystore.

saml.keystore.credentials.<?> : L'alias d'un couple clé publique / clé privée pour les besoins de Squash TM en terme de chiffrement. Le point d'interrogation ? représente un alias. La valeur de la propriété est le mot de passe de cette clé. Cette propriété peut être répétée une fois pour chaque clé. Si la procédure a été suivie, mettre squashtm comme valeur.

saml.keystore.default-key : L'alias de la clé que Squash TM doit utiliser à chaque fois qu'une clé privée est requise, sauf si une autre clé est spécifiée pour cette situation dans le fichier de configuration. La clé par défaut doit évidemment être présente dans la liste des identifiants. Si la procédure a été suivie, mettre squashtm comme valeur.

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 se terminer par "Squash TM Started in XXXms".

6. Résolution de problèmes

  • Il est parfois nécessaire d'importer le certificat de l'IDP dans le keystore (Aide au formatage des certificats) : 

    keytool -import -trustcacerts -alias adfs -file $SQUASH_HOME/plugins/saml/adfs.cer -keystore $SQUASH_HOME/plugins/saml/keystore.jks`

  • Le fichier de métadonnées FederationMetadata.xml doit être encodé en UTF-8 sans BOM, sinon il peut causer des problèmes de lecture de ce dernier au démarrage de Squash TM (Message d'erreur indiquant des métadonnées IDP vides).

    file FederationMetadata.xml ou bien file -i FederationMetada.xml

    apt install icu-devtools

    uconv -f utf-8 -t utf-8 --add-signature FederationMetadata.xml > idp.xml

Conventions

Format des chemins de fichiers

Les métadonnées et le keystore peuvent être récupérés à la lecture en tant que fichiers locaux ou à distance via des appels HTTP(S) en utilisant les propriétés saml.idp.metadata.url, saml.sp.metadata.url et saml.keystore.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.