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.
Prérequis
Le plugin SAML nécessite d’avoir Squash TM en version 1.19 minimum et Java Hotspot 8 ou 11. Les autres versions de Java ne sont pas testées.
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 :
- Déploiement du binaire ;
- Création du keystore et des métadonnées SP ;
- Configuration de l'IDP et récupération de ses métadonnées ;
- Configuration de l’application ;
- Démarrage de Squash TM avec sa nouvelle configuration ;
- Tirer sur le trouble ;
- 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 coller le dans le dossier du même nom dans votre 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 votre 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 à votre IDP ou demander à votre 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"
- Télécharger le fichier dans
$SQUASH_HOME/conf/saml/
avecwget
oucurl
et l'appelerFederationMetada.xml
si ce n'est pas déjà le cas ; - Noter le chemin d'accès au fichier ;
- Donner le droit de lecture accès à Squash TM sur le fichier.
Déclaration de l'URL
- Récupérer l'URL ;
- La tester depuis le serveur Squash (
wget
oucurl
) ; - La sauvegarder pour la prochaine étape.
4. Configuration de l'application
Utilisation d'un fichier dédié
- Copier le fichier
config/squash.tm.cfg-saml.properties
et collez-le dans le répertoire de configuration déjà déclaré qui en général estSQUASH_HOME/conf
; -
Puis, éditez le fichier de configuration principal
SQUASH_HOME/conf/squash.tm.cfg.properties
et associez-lui 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, vous pouvez juste 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 vous avez suivi la procédure, mettez 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
: Mettretrue
;saml.proxy.server-name
: Mettre une URL du typesquash.domaine.fr
;saml.proxy.scheme
: Mettrehttps
en général ;saml.proxy.server-port
: Mettre443
en général ;saml.proxy.include-port-in-url
: Mettretrue
.
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. Tirer sur le trouble
-
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 bienfile -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ées à 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
.