Configuration du plugin OpenId Connect
Le plugin OpenID Connect ajoute un nouveau point d’entrée pour l’authentification sur Squash. Squash agit comme un Service Provider uniquement. L’identity Provider est un outil externe comme par exemple : Google, GitLab, Microsoft ou encore Okta.
OpenID Connect s’appuie sur le protocole OAuth 2.0 associé à un jeton JSON Web Token (JWT).
Ce plugin ne remplace pas le formulaire de connexion qui reste le point d'entrée par défaut de Squash. Les utilisateurs peuvent donc continuer à s'authentifier via les champs Login et Mot de passe.
Configuration rapide du plugin
Prérequis
Le plugin OpenId Connect nécessite d’avoir :
- Squash en version 6.0 minimum ;
- une licence PREMIUM ou ULTIMATE valide ;
- téléchargé le plugin
security.openid.connect-X.Y.Z.RELEASE
.
Cette documentation donne des exemples avec les IdP Google, GitLab et Okta mais d'autres applications peuvent être utilisées comme identity Provider : Microsoft Azure, Keycloak, Github, etc.
Création ou enregistrement de l’application dans l’IdP
Il est nécessaire avant de commencer toute configuration dans Squash de créer l'application dans l'IdP. Voici les liens des pages de documentation décrivant les étapes à suivre pour Google, GitLab et Okta :
- créer une application avec Google Cloud Console en suivant la documentation fournie par Google ;
- créer une application avec GitLab en suivant la documentation fournie par GitLab ;
- créer une application avec Okta en suivant la documentation fournie par Okta.
Configuration dans Squash
-
Activer le plugin en ajoutant la propriété suivante dans le fichier
squash.tm.cfg.properties
présent dans le dossierconf
de Squash. Si elle est déjà présente, il suffit d'ajouter le profilopenid-connect
aux profils existants, séparé par une virgule ;spring.profiles.include=openid-connect
-
Placer le plugin
security.openid.connect-X.Y.Z.RELEASE.jar
dans le dossierplugins
de Squash ; -
Ajouter et modifier le fichier de configuration du plugin
squash.tm.cfg-openid-connect.properties
dans le dossierconf
de Squash. Les configurations souhaitées sont portées par ce fichier.
Renseigner le fichier de propriétés
Les propriétés Oauth2
Les propriétés OAuth2 qui concernent la mise en place d'un IdP suivent le schéma de nommage suivant :
spring.security.oauth2.client.[provider_ou_registration].[nom_de_l_idp].[propriete]
Le nom de l'IdP est à renseigner librement, cette valeur s'affiche sur le bouton de connexion présent sur la page de connexion classique de Squash. Les espaces doivent être remplacés par des _
.
On distingue deux types de propriétés pour la configuration d'un IdP : les propriétés avec les informations dites "du fournisseur" et celles avec les informations dites "du client".
- propriétés "du fournisseur" : Ces propriétés commencent par
spring.security.oauth2.client.provider
; - propriétés "du client" : Ces propriétés commencent par
spring.security.oauth2.client.registration
.
Ces propriétés correspondent aux informations fournies par l'IdP suite à l'enregistrement de l'application.
Selon l'IdP choisi, toutes les propriétés de configuration ne sont pas nécessaires. Notamment pour les IdP Google, Okta, GitHub et Facebook, elles peuvent être en partie omises.
Pour éviter les erreurs de configuration, il est recommandé de se renseigner sur la configuration minimale nécessaire pour l'IdP sélectionné ou de saisir toutes les propriétés.
Pour plus d'informations sur les propriétés disponibles, consulter la documentation disponible directement dans le fichier de propriétés squash.tm.cfg-openid-connect.properties
embarqué par le plugin.
Ajouter les propriétés avec les informations dites "du fournisseur".
Quelques exemples :
-
Google : Google ne nécessite le remplissage d'aucune de ces propriétés.
Info
Les informations du provider Google sont directement intégrées dans le plugin, il n'est donc pas nécessaire de les ajouter.
-
GitLab
spring.security.oauth2.client.provider.gitlab.authorization-uri=https://gitlab.com/oauth/authorize spring.security.oauth2.client.provider.gitlab.token-uri=https://gitlab.com/oauth/token spring.security.oauth2.client.provider.gitlab.user-info-uri=https://gitlab.com/oauth/userinfo spring.security.oauth2.client.provider.gitlab.jwk-set-uri=https://gitlab.com/oauth/discovery/keys spring.security.oauth2.client.provider.gitlab.issuer-uri=https://gitlab.com
-
Okta
spring.security.oauth2.client.provider.okta.authorization-uri= spring.security.oauth2.client.provider.okta.token-uri=https://{yourOktaDomain}/oauth2/default/v1/token spring.security.oauth2.client.provider.okta.user-info-uri= spring.security.oauth2.client.provider.okta.jwk-set-uri= spring.security.oauth2.client.provider.okta.issuer-uri=
Ajouter les propriétés avec les informations dites "du client"
Quelques exemples :
-
Google
spring.security.oauth2.client.registration.google.client-id= {client id} spring.security.oauth2.client.registration.google.client-secret= {client secret} spring.security.oauth2.client.registration.google.scope= {champs d'application} spring.security.oauth2.client.registration.google.redirect-uri= {uri de redirection} spring.security.oauth2.client.registration.google.client-name= {nom de l'IdP) {facultatif} spring.security.oauth2.client.registration.google.authorization-grant-type=authorization_code{facultatif}
-
GitLab
spring.security.oauth2.client.registration.gitlab.client-id= {application id} spring.security.oauth2.client.registration.gitlab.client-secret= {secret} spring.security.oauth2.client.registration.gitlab.authorization-grant-type=authorization_code spring.security.oauth2.client.registration.gitlab.redirect-uri= {uri de redirection} spring.security.oauth2.client.registration.gitlab.scope= {scope} spring.security.oauth2.client.registration.gitlab.client-name= {nom de l'IdP}
-
Okta
spring.security.oauth2.client.registration.okta.client-id= {client id} spring.security.oauth2.client.registration.okta.client-secret= {client secret} spring.security.oauth2.client.registration.okta.authorization-grant-type=client_credentials spring.security.oauth2.client.registration.okta.scope= {scope}
Tout ce qui est en spring.security.oauth2.client.provider.XXX.YYY
se trouve dans le fichier .well-known
d'OpenId Connect de chaque IdP.
Tout ce qui est en spring.security.oauth2.client.registration.XXX.YYY
est spécifique à l'application Squash renseigné dans l'IdP.
XXX
est à définir soi-même pour différencier les différents IdP ;YYY
sont les paramètres minimums pour arriver à connecter Squash à l'IdP OpenId Connect.
Propriétés recommandées
user-name-attribute
L'ajout de la propriété user-name-attribute
permet de déterminer quelle valeur est utilisée comme login pour l'utilisateur dans Squash.
Attention, cette valeur doit être unique. Si un utilisateur existant dispose d'un login identique à la valeur envoyée par l'IdP, la connexion se fera sur le compte de l'utilisateur existant. Inversement, si cette valeur ne correspond à aucun login, un nouvel utilisateur est créé.
Configuration recommandée de cette propriété :
spring.security.oauth2.client.provider.[nom_de_l_idp].user-name-attribute=email
oidc.access.whitelist
Certains IdPs ne donnent pas la possibilité de filtrer les utilisateurs pouvant accéder à l'application. Cette propriété permet de définir une liste blanche de noms de domaine ou d'emails utilisateurs ayant la permission de se connecter à Squash.
Les éléments de la liste doivent être séparés par des virgules et ne doivent pas contenir d'espaces :
oidc.access.whitelist=@nomDeDomaine.com,@nomDeDomaine.fr
Attention
La propriété oidc.access.whitelist
ne peut pas être utilisée avec un IdP qui ne connait pas ou ne fournit pas l'email de l'utilisateur, comme c'est le cas avec Microsoft Azure par exemple.
Fonctionnement de la connexion
Les utilisateurs peuvent aussi bien se connecter via l'IdP que via le formulaire de connexion par défaut.
Pour que les utilisateurs puissent se connecter à Squash avec OpenId Connect, ils doivent être présents dans l'IdP et être autorisés à se connecter. Seuls les utilisateurs des domaines autorisés par l'application et par la liste blanche définie dans Squash peuvent se connecter à Squash via cet IdP :
- si l'utilisateur n'est pas autorisé à se connecter par l'application un message d'erreur de l'IdP s'affiche ;
- si l'utilisateur est autorisé à se connecter par l'application mais n'est pas autorisée par la liste blanche configurée dans Squash, un message d'erreur s'affiche directement dans Squash ;
- si l'utilisateur est autorisé à se connecter par l'application et par la liste blanche, l'utilisateur peut se connecter :
- l’utilisateur dispose déjà d'un compte dans Squash avec un login identique : lors de sa connexion, il récupère les habilitations correspondantes à son compte ;
- l’utilisateur n’a pas de compte utilisateur dans Squash : lors de sa première connexion, un compte utilisateur est automatiquement créé dans Squash mais aucune habilitation ne lui est affectée.
Par la suite, des habilitations doivent lui être attribuées par un administrateur depuis Squash.