Utilisateur d'un fournisseur OIDC (Système d'authentification SSO)

Votre application intégre la possibilité d'utiliser un fournisseur OpenID Connect (OIDC) (exemple : Google, Microsoft, Keycloak...) comme systéme d'authentification SSO.

Pourquoi utiliser SSO ?

Simplification de l'administration de vos utilisateurs
Facilité d'utilisation pour les utilisateurs finaux
Fonctionnalités portés par le fournisseur d'authentification non pris en charge par l'application (ex : rotation de mot de passe, Authentification multi-facteurs, ...)

Fonctionnement du protocole OpenId Connect

Sequence OIDC Vitis

Pour que le protocole fonctionne il faut passer par trois étapes d'authentification.

Premièrement l'application vous redirige vers le fournisseur OIDC qui se chargera de gérer l'authentification si nécessaire (simple, avec MFA, ...), suite à quoi vous serez rediriger vers la page d'origine avec des informations permettant de passer aux étapes suivantes.

Ces élements sont ensuite envoyés au serveur qui se chargera de récupérer les informations d'authentification (jetons de connexion, d'authentification et de rafraichissement).

Ensuite l'application vérifiera la validité du token à intervalle régulier en requêtant les informations de votre compte auprès du fournisseur OIDC.

Note

Les colonnes contenant les jetons d'authentification et de rafraichissement sont chiffrées. L'administrateur de l'application lui-même n'est pas en capacité d'y accéder facilement, de façon à garantir à chaque utilisateur la sécurité que ses jetons ne seront utilisés que pour assurer l'authentification de l'utilisateur dans l'application.

Mise en place dans votre application

Il faut d'abord configurer votre fournisseur OIDC de façon à récupérer certaines informations :

Client ID
Client Secret
Point de terminaisons (fichier accessible via l'API .well-known/openid-configuration)
Possibilité d'utiliser un jeton de rafraichissement
Structure des jetons JWT retournés

Ensuite il faut aller sur le serveur et modifier la configuration du fichier vas/src/Module/Vitis/conf/properties.json :

allow_oauth2_connection : Booléen permettant de définir si la fonctionnalité est active
oauth2_auth_endpoint : Requête permettant la redirection vers le fournisseur OIDC pour l'authentification, doit contenir certaines balises :
- [CLIENT_ID] : permet de placer le client_id dans la requête
- [REDIRECT_URI] : permet de définir au fournisseur vers quelle page il devra réaliser la redirection aprés l'authentification
- [STATE] : défini une chaine aléatoire compatible avec la gestion d'état (c'est une sécurité du protocole)
- [RANDOMIZE] (optionnel) : chaine aléatoire si besoin dans certaines implémentation du protocole (ex : Google OIDC)
oauth2_token_endpoint : Point de terminaison pour la génération de token
oauth2_refresh_endpoint : Point de terminaison pour le rafraichissement de token (normalement identique au token_endpoint)
oauth2_userinfo_endpoint : Point de terminaison pour récupérer les informations de l'utilisateur
oauth2_token_field_access_token : Clé contenant le jeton d'accés dans la réponse de la requête de génération
oauth2_token_field_id_token : Clé contenant le jeton d'identification dans la réponse de génération et de rafraichissement (permet de récupérer le login dans le JWT)
oauth2_token_field_id_token_username : nom du champs dans le corps du jeton JWT contenant le login
oauth2_token_field_refresh_token : Clé contenant le jeton de rafraichissement dans la réponse de rafraichissement
oauth2_userinfo_authorization_header : Nom de l'en-tête permettant de passer le jeton d'authentification lors de la requête userinfos
oauth2_userinfo_authorization_prefix : Préfixe du jeton d'authentification pour la valeur de l'en-tête
oauth2_refresh_period_seconds : Période de vérification de la validité de l'authentification
oauth2_auto_import : Booléen permettant d'activer l'import automatique des nouveaux comptes lors de la première connexion depuis le founisseur OIDC
oauth2_user_password_salt : Sel utilisé dans les mots de passe internes à l'application pour les utilisateurs OIDC
oauth2_clientId : Identifiant du client OIDC
oauth2_clientSecret : Secret du client OIDC
default_login_endpoint : Point de terminaison par défaut de l'application, /login interface de connexion classique, /oauth2 connexion en SSO par défaut. Dans tous les cas les deux sont utilisables si vous souhaitez un fonctionnement mixte.

Note

Changez le niveau de verbosité de vos journaux au niveau DEBUG pour configurer plus facilement certains de ces paramètres.

Création de compte manuellement

Vous pouvez ajouter manuellement les utilisateurs qui pourront se connecter via le protocole OIDC.

Aprés avoir configurer votre provider OIDC sur le serveur, une boite à cocher supplémentaire sera disponible dans le formulaire de création des utilisateurs (Dans l'administration classique des utilisateurs).

Sequence OIDC Vitis

Il vous suffit d'utiliser comme login le champ récupéré dans le token JWT (properties : oauth2_token_field_id_token_username).

Exemples

Pour tous les exemples qui vont suivre :

oauth2_refresh_period_seconds doit être inférieur à la durée de validité du jeton d'authentification définit par le fournisseur OIDC
oauth2_auth_endpoint : contient des balises entre crochet qui ne sont pas à remplacer par l'administrateur
oauth2_auto_import est à définir à votre convenance mais peut impliquer un risque pour votre application en cas de mauvaise administration du client OIDC, dans le cas de la création de ces utilisateurs les droits appliqués lors de la création seront ceux définit pour l'inscription classique :
- sign_up_automated_roles
- sign_up_automated_groups

Avertissement

Les configurations proposées par la suite sont des exemples simples. Il est probable que des configurations supplémentaires soit nécessaire pour garantir la sécurité de votre fournisseur d'authentification.

Google

Documentation officielle

Se rendre sur la page de credential
Ajouter un client OAuth 2.0 :
- URI de redirection : https://mon-domaine/vmap/oauth2
Ouvrir les informations sur les points de terminaisons
Ouvrir le fichier de configuration de l'application et retoucher les clés suivantes :

{
    "allow_oauth2_connection": true,
    "oauth2_auth_endpoint": "https://accounts.google.com/o/oauth2/v2/auth?response_type=code&client_id=[CLIENT_ID]&scope=openid%20email&redirect_uri=[REDIRECT_URI]&state=[STATE]&nonce=[RANDOMIZE]&access_type=offline",
    "oauth2_token_endpoint": "https://oauth2.googleapis.com/token",
    "oauth2_refresh_endpoint": "https://oauth2.googleapis.com/token",
    "oauth2_userinfo_endpoint": "https://openidconnect.googleapis.com/v1/userinfo",
    "oauth2_token_field_access_token": "access_token",
    "oauth2_token_field_id_token": "id_token",
    "oauth2_token_field_id_token_username": "email",
    "oauth2_token_field_refresh_token": "refresh_token",
    "oauth2_userinfo_authorization_header": "Authorization",
    "oauth2_userinfo_authorization_prefix": "Bearer ",
    "oauth2_refresh_period_seconds": 3500,
    "oauth2_user_password_salt": "CHAINE RANDOM A DEFINIR",
    "oauth2_clientId": "ID CLIENT A DEFINIR",
    "oauth2_clientSecret": "SECRET CLIENT A DEFINIR",
    "oauth2_auto_import" : false,
    "default_login_endpoint": "oauth2",
}

Ouvrir https://mon-domaine/vmap/oauth2 dans votre navigateur, vous devriez être redirigé vers le systéme d'authentification de google.

Microsoft Office 365

Documentation officielle

Se rendre sur la console d'administration Microsoft
Ajouter une Inscription
Dans la partie Authentification :
- Définir l'URI de redirection : https://mon-domaine/vmap/oauth2
- L'utilisation du jeton de connexion et d'identification
Dans Certificat et secrets :
- Ajouter un secret pour le client (ATTENTION : vous ne pourrez le récupérer qu'une seule fois)
Dans Vue d'ensemble il est possible d'accéder aux points de terminaison dont le /.well-known/openid-configuration qui contiendra les autres
Ouvrir le fichier de configuration de l'application et retoucher les clés suivantes :

{
    "allow_oauth2_connection": true,
    "oauth2_auth_endpoint": "https://login.microsoftonline.com/TENANT A REMPLACER/oauth2/v2.0/authorize?response_type=code&client_id=[CLIENT_ID]&scope=openid%20offline_access%20https%3A%2F%2Fgraph.microsoft.com%2Fuser.read&redirect_uri=[REDIRECT_URI]&state=[STATE]&response_mode=query",
    "oauth2_token_endpoint": "https://login.microsoftonline.com/TENANT A REMPLACER/oauth2/v2.0/token",
    "oauth2_refresh_endpoint": "https://login.microsoftonline.com/TENANT A REMPLACER/oauth2/v2.0/token",
    "oauth2_userinfo_endpoint": "https://graph.microsoft.com/oidc/userinfo",
    "oauth2_token_field_access_token": "access_token",
    "oauth2_token_field_id_token": "access_token",
    "oauth2_token_field_id_token_username": "unique_name",
    "oauth2_token_field_refresh_token": "refresh_token",
    "oauth2_userinfo_authorization_header": "Authorization",
    "oauth2_userinfo_authorization_prefix": "Bearer ",
    "oauth2_refresh_period_seconds": 3500,
    "oauth2_user_password_salt": "CHAINE RANDOM A DEFINIR",
    "oauth2_clientId": "ID CLIENT A DEFINIR",
    "oauth2_clientSecret": "SECRET CLIENT A DEFINIR",
    "oauth2_auto_import" : false,
    "default_login_endpoint": "oauth2",
}

Ouvrir https://mon-domaine/vmap/oauth2 dans votre navigateur, vous devriez être redirigé vers le systéme d'authentification de Microsoft.

Keycloack

Documentation officielle

Sur votre instance de keycloack définisser le realm à utiliser
Ajouter vos comptes utilisateurs ou ajouter un connecteur
Créer un client avec les paramètres suivant à minima
- standard flow activé
- Redirect URI valid redirect Uri : https://mon-domain/vmap/oauth2
- Web-Origin : https://mon-domain
- Acess type : Confidential
Sur la configuration du realm cliquer sur le lien OpenID Endpoint Configuration pour accéder au json contenant les informations des différents endpoint à utiliser pour votre realm.
Ouvrir le fichier de configuration de l'application et retoucher les clés suivantes :

{
    "allow_oauth2_connection": true,
    "oauth2_auth_endpoint": "https://app.please-open.it/auth/realms/REALM A REMPLACER/protocol/openid-connect/auth?client_id=[CLIENT_ID]&response_type=code&scope=openid%20offline_access&redirect_uri=[REDIRECT_URI]&state=[STATE]",
    "oauth2_token_endpoint": "https://app.please-open.it/auth/realms/REALM A REMPLACER/protocol/openid-connect/token",
    "oauth2_refresh_endpoint": "https://app.please-open.it/auth/realms/REALM A REMPLACER/protocol/openid-connect/token",
    "oauth2_userinfo_endpoint": "https://app.please-open.it/auth/realms/REALM A REMPLACER/protocol/openid-connect/userinfo",
    "oauth2_token_field_access_token": "access_token",
    "oauth2_token_field_id_token": "access_token",
    "oauth2_token_field_id_token_username": "preferred_username",
    "oauth2_token_field_refresh_token": "refresh_token",
    "oauth2_userinfo_authorization_header": "Authorization",
    "oauth2_userinfo_authorization_prefix": "Bearer ",
    "oauth2_refresh_period_seconds": 600,
    "oauth2_user_password_salt": "CHAINE RANDOM A DEFINIR",
    "oauth2_clientId": "ID CLIENT A DEFINIR",
    "oauth2_clientSecret": "SECRET CLIENT A DEFINIR",
    "oauth2_auto_import" : false,
    "default_login_endpoint": "oauth2",
}

Ouvrir https://mon-domaine/vmap/oauth2 dans votre navigateur, vous devriez être redirigé vers le systéme d'authentification de Keycloack.

Limitation de la fonctionnalité

Les utilisateurs OIDC ne sont pas considérés comme des utilisateurs locaux. Il ne peuvent pas :

Se connecter via le endpoint /login
Avoir des jetons de connexion publiques
Changer de mot de passe dans l'application (il faut passer par le fournisseur OIDC)

La validité des jetons de connexion est relative au rafraichissement défini via oauth2_refresh_period_seconds ou la durée de vie de notre propre jeton de connexion.

En cas d'utilisation d'un provider OIDC hébergé en dehors de votre infrastructure le serveur applicatif doit avoir accés à internet ou utiliser un proxy.

Avertissement

Il est primordial d'utiliser le même sel sur toutes les applications Veremes (vMap, GTF, ...) connectées à votre provider SSO, qui utilisent des bases de données dans le même cluster Postgres.