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.

OpenID Connect

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 dossier conf de Squash. Si elle est déjà présente, il suffit d'ajouter le profil openid-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 dossier plugins de Squash ;
Ajouter et modifier le fichier de configuration du plugin squash.tm.cfg-openid-connect.properties dans le dossier conf 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.