Distribution EOLE » Outils Eole » SSO

h1. Documentation (brouillon) pour l'authentification OpenID Connect (France Connect)

h2. Principes généraux

Des modifications ont été apportées à EoleSSO pour permettre d'authentifier les utilisateurs auprès du portail France Connect.

Il est également possible de configurer d'autres fournisseurs d'identité OpenID Connect dans les limites des fonctionnalités implémentées (testé à ce jour avec France Connect et Google).

Le principe de fonctionnement est le suivant :

* L'utilisateur se connecte à une application protégée par EoleSSO et est redirigé sur la page d'authentification;

* la page de login d'EoleSSO présente un bouton pour chaque fournisseur d'identité OpenID configurés;

* lorsqu'un utilisateur clique sur un de ces boutons, il est redirigé vers le portail de connexion du fournisseur correspondant;

* après authentification, il est renvoyé sur le portail EoleSSO. Deux cas sont possibles :

** lors de la première connexion avec ce fournisseur, EoleSSO demande à l'utilisateur de renseigner son login/mot de passe habituel, et l'associe à l'identifiant retourné par le fournisseur;

** si l'association a déjà été faite, EoleSSO va automatiquement retrouver le compte associé, et créer la session de l'utilisateur;

* l'utilisateur est ensuite redirigé vers l'application à laquelle il voulait accéder.

Complément : Le protocole OpenID Connect prévoie que le fournisseur de service précise un ensemble de données auxquelles il veut accéder (scope). Cela peut permettre de récupérer diverses informations (sous réserve du consentement de l'utilisateur) , comme l'adresse de messagerie, le numéro de téléphone, ... 

Dans le cadre de cette implémentation, le but est seulement de récupérer un identifiant stable dans le temps afin que l'utilisateur l'associe à son compte local. Le scope minimal est utilisé (*openid*) et seul l'attribut *sub* est récupéré par EoleSSO (*identifiant opaque* de l'utilisateur, sans informations personnelles).

La correspondance entre l'utilisateur local et son identifiant OpenID est stockée dans un fichier */usr/share/sso/openid_users/<référence_fournisseur>_users.ini*

h2. Prérequis à la mise en oeuvre

Le protocole OpenID Connect (basé sur OAuth 2) repose sur un *principe de confiance* entre un *fournisseur de service* (Relying Party, dans notre cas le serveur EoleSSO), et un *fournisseur d'identité* (OpenID Provider, par exemple France Connect).

Pour mettre en place cette relation de confiance, le fournisseur de service va effectuer une *demande d'enregistrement* auprès du fournisseur d'identité. Celui-ci lui enverra alors un n° de client et une clé secrète.

Le fournisseur d'identité doit également documenter un certain nombre d'URLs nécessaires à la configuration du client (un principe de configuration automatique est prévu par le protocole, mais il est rarement utilisé dans la pratique et n'a pas été implémenté dans EoleSSO pour l'instant).

Les *modalités* de cet échange d'informations sont *spécifiques à chaque fournisseur* (voir les exemples plus loin).

Dans la plupart des cas, il sera demandé :

* une adresse dite de *callback* : c'est l'adresse sur laquelle est renvoyé l'utilisateur après authentification. Dans le cas d'EoleSSO : *<pre>https://<adresse_serveur_eolesso>:8443/oidcallback</pre>*

* une adresse mail de contact

* Un logo représentant le fournisseur de service (logo Eole, de l'académie, ...).

h2. variables de configuration (gen_config)

Une fois en possession des informations nécessaires, vous pouvez configurer le service eole-sso de la façon suivante (*onglet Eole sso* de l'interface gen_config en *mode expert*)

*  passer la variable *Autoriser l'authentification OpenID Connect* à *oui*

*  Ajouter un fournisseur en cliquant sur le bouton *+Référence du fournisseur d'identité OpenID*

*  renseigner un libellé pour identifier le fournisseur. Ce libellé est interne à l'application EoleSSO. Il est en particulier utilisé pour définir le nom des fichiers contenant les logos/boutons du fournisseur :

** /usr/share/sso/interface/images/<libelle>.png : bouton de connexion présenté sur la page de login (par exemple 'se connecter avec France Connect')

** /usr/share/sso/interface/images/logo-<libelle>.png : logo du fournisseur qui sera affiché sur la page d'association de comptes.

* Renseigner ensuite les informations suivantes concernant le fournisseur :

* *Libellé du fournisseur d'identité OpenID* : libellé à destination des utilisateurs pour décrire le fournisseur ("France Connect", "Google", ...)

** URL d'accès (*issuer*) : URL décrivant le fournisseur d'identité (la plupart du temps, l'URL de base de son service d'authentification)

** URL de demande d'autorisation (*authorization endpoint*) : URL permettant au client d'initier le processus d'authentification

** URL de récupération de jeton d'accès (*token endpoint*) : URL permettant de récupérer un jeton (éventuellement l'identifiant de l'utilisateur) après authentification

** URL de déconnexion (*logout endpoint*) : URL permettant de demander une déconnexion (si disponible)

** URL de lecture des informations (*userinfo endpoint*) : URL permettant de récupérer les informations de l'utilisateur à l'aide du jeton fourni

** URL de description des certificats de signature (*jwks URI*) : URL décrivant les certificats utilisés par le fournisseur (si disponible)

** *Client ID* : identifiant client fourni par le fournisseur lors de l'échange préalable

** *Client secret* : clé secrète fournie par le fournisseur lors de l'échange préalable

notes: 

* La cinématique de déconnexion (single logout) n'est pas implémentée par tous les fournisseurs. Une cinématique spécifique a été mise en oeuvre dans le cas de certains acteurs connus. à ce jour : Google (testé) et Facebook / Microsoft (non testé). le paramètre *URL de déconnexion* sera donc ignoré pour ceux-ci.

h2. exemples de configuration

h3. France Connect

Une configuration prédéfinie est fournie pour France Connect. Pour l'activer, choisissez *fconnect* dans la liste déroulante de la variable *Référence du fournisseur d'identité OpenID*.

Les seuls données à renseigner sont *Client ID* et *Client secret*

Pour obtenir ces identifiants, s'inscrire en tant que fournisseur de service à cette adresse : https://doc.integ01.dev-franceconnect.fr/inscription (environnement de test)

Il vous sera demandé les informations suivantes:

* Nom du service

* Email de contact

* Logo du service (apparaîtra sur la page d'authentification de France Connect)

* Urls de callback : adresse sur laquelle renvoyer après authentification de l'utilisateur (voir plus haut)

Les logos et bouton de connexion France Connect sont déjà fournis avec EoleSSO.

Pour plus d'informations sur le fonctionnement et la configuration, se reporter à cette page : https://integ01.dev-franceconnect.fr/fournisseur-service

h3. Google

La mise en oeuvre de l'authentification des utilisateurs avec les services de Google a également été testée.

Pour récupérer votre Client ID / Client Secret, vous devez créer un compte développeur depuis cette adresse : https://developers.google.com/

Rendez-vous ensuite dans la console développeur de Google afin de déclarer votre service EoleSSO comme application : https://console.developers.google.com

* Créez un nouveau projet (barre supérieure de la console -> *select a project* -> *create a project*)

* Une fois le projet créé, cliquez sur la barre de menu gauche (3 barres horizontales), puis sur *API Manager*. Cliquez ensuite sur *Credentials* (à gauche)

* Cliquer sur *Oauth Consent Screen* et renseigner au minimum le champ *Product name shown to users* (par exemple 'établissement xxx')

* Sauvegarder et dans Credentias, cliquer sur *Create credentials*, *Oauth Client ID"

* Choisir *Web application* et renseigner les champs suivants :

** Name  : au choix

** Authorized JavaScript origins : https://[adresse_serveur_sso]:8443

** Authorized redirect URIs : https://[adresse_serveur_sso]:8443/oidcallback

* Cliquer sur *Create* et recopier l'identifiant et la clé secrète fournis

Une fois les identifiants récupérés, vous pouvez configurer les paramètres d'EoleSSO (gen_config, onglet Eole SSO en mode expert)

* Passer à *oui* la variable *Autoriser l'authentification OpenID Connect*

* ajouter un forunisseur en cliquant sur *+Référence du fournisseur d'identité OpenID*

* *Référence du fournisseur d'identité OpenID* : google (des logos sont présents et utilisés automatiquement en choisissant ce libellé)

* *Libellé du fournisseur d'identité OpenID* : Google (ou autre description de votre choix)

* *issuer*: https://accounts.google.com

* *authorization_endpoint*: https://accounts.google.com/o/oauth2/v2/auth

* *token_endpoint*: https://www.googleapis.com/oauth2/v4/token

* *userinfo_endpoint*: https://www.googleapis.com/oauth2/v3/userinfo

* *jwks_uri*: https://www.googleapis.com/oauth2/v3/certs

En cas de problème, les paramètres en cours de validité sont décrits ici :  https://accounts.google.com/.well-known/openid-configuration

Pour plus d'informations sur le support d'OpenID chez Google : https://developers.google.com/identity/protocols/OpenIDConnect

h3. autres fournisseurs