Présentation générale
Le protocole OAuth permet de ne pas donner à une application un identifiant et un mot de passe qui lui permettrait de tout faire lorsqu'elle accède à un service, mais de lui donner juste les autorisations nécessaires pour faire ce qu'elle est censée faire.
Ces autorisations sont accordées sous forme de deux "jetons" :
- un jeton d'accès (access token), valide sur une durée très courte, en général une heure,
- un jeton d'actualisation (refresh token), valide sur une durée bien plus grande et qui permet de renouveler le jeton d'accès sans avoir à redemander en permanence une intervention de l'utilisateur.
Pour obtenir les jetons, l'utilisateur est invité à s'authentifier dans un navigateur web séparé de l'application (pour que cette dernière n'intercepte pas les identifiants).
Cette phase d'authentification est pilotée entièrement par le service visé et non par l'application.
Cela peut être une authentification à plusieurs facteurs, par exemple avec un code de vérification envoyé par SMS ou par e-mail.
Ce n'est qu'une fois que l'utilisateur est authentifié et a donné son accord pour les autorisations demandées que les jetons sont communiqués à l'application.
L'utilisateur peut à n'importe quel moment se reconnecter directement à son service pour consulter ou invalider les autorisations déjà accordées.
Tout est fait pour que ni son identifiant ni son mot de passe ne soient compromis.
Identification de l'application auprès du service
Les services n'accordent des autorisations qu'à des applications connues. Il faut donc une déclaration préalable qui permet d'obtenir :
- un identifiant (client ID) pour identifier l'application,
- un secret (client secret) qui doit être masqué et qui évite qu'une application se fasse passer pour une autre.
Pour le serveur SMTP de Microsoft
smtp.office365.com, il vous est proposé d'utiliser une application prédéfinie par Index Éducation. Vous n'aurez donc pas à vous occuper de cette étape.
Sinon, il faut que vous déclariez vous-même l'application pour obtenir un identifiant et un secret. Vous pouvez consulter ces deux sections plus bas dans ce document :
- Déclarer soi-même l'application auprès d'un service Google ;
- Déclarer soi-même l'application auprès d'un service Microsoft.
Paramètre important : les applications Index Éducation utilisent comme URI de redirection https://execonnect.index-education.com/callback
Identification du service auprès de l'application
L'application a besoin de plusieurs URL appelées points de terminaisons (endpoints) pour initier les échanges avec le service. Vous pouvez obtenir ces points de terminaison dans l'interface dans laquelle vous avez déclaré l'application.
Dans le cas de l'application prédéfinie par Index Éducation, ces points de terminaison sont préremplis.
Déclarer soi-même l'application auprès d'un service Google
Côté service
Pour commencer, il faut vous connecter sur
https://console.cloud.google.com/home/dashboard, puis cliquer à gauche sur
API et services.
- Créez un nouveau projet, donnez lui un nom (sans caractère accentué), puis assurez-vous que le nouveau projet est bien sélectionné. Ce nom n'est pas celui que verra l'utilisateur.
- Cliquez ensuite à gauche sur Bibliothèque et cliquez sur Gmail API. Activez les API Gmail.
- Tout en haut à gauche, cliquez sur le menu paramètres (menu burger) et retournez sur API et services.
- Cliquez ensuite à gauche dans Écran de consentement OAuth et complétez les informations.
- Au deuxième écran Niveaux d'accès, cliquez sur le bouton AJOUTER OU SUPPRIMER DES CHAMPS D'APPLICATION. Sous Ajouter manuellement des niveaux d'accès, collez https://mail.google.com/, cliquez sur AJOUTER À LA TABLE, puis sur METTRE À JOUR.
- À la question Quelles fonctionnalités utiliserez-vous, choisissez Client de messagerie.
- Terminez la configuration.
- Cliquez ensuite à gauche sur Identifiants, puis sur + CRÉER DES IDENTIFIANTS, ID client OAuth.
- Type d'application : application Web
- Nom : execonnect.index-education.com
- URI de redirection autorisés : https://execonnect.index-education.com/callback
- Une fenêtre apparaît alors avec un identifiant et un secret : ces deux paramètres doivent être conservés pour être renseignés dans l'application.
Côté application
Dans l'application, saisissez maintenant les éléments suivants :
- Identifiant, Secret : collez ici les valeurs conservées précédemment
- Point de terminaison d'autorisation : https://accounts.google.com/o/oauth2/v2/auth?prompt=consent&access_type=offline
- Point de terminaison de jeton : https://oauth2.googleapis.com/token
- Autorisations demandées : https://mail.google.com/
Vous pouvez alors obtenir des jetons OAuth.
Remarques :
- Les paramètres prompt=consent&access_type=offline sont nécessaires pour obtenir un jeton d'accès et un jeton d'actualisation.
- L'autorisation https://www.googleapis.com/auth/gmail.send (Envoyer des e-mails en votre nom) ne suffit pas pour envoyer un e-mail via un serveur SMTP, il faut https://mail.google.com/ (accès complet à la boîte mail). Voir OAuth 2.0 Mechanism
Déclarer soi-même l'application auprès d'un service Microsoft
Côté service
Pour commencer, il faut vous connecter sur
https://portal.azure.com/, puis cliquer sur
Azure Active Directory.
- Cliquez à gauche sur Inscriptions d'applications, puis tout en haut sur + Nouvelle inscription. Choisissez selon vos besoins le type de comptes pris en charge, puis dans la partie URI de redirection, choisissez Client public/natif (mobile & bureau) avec l'URI https://execonnect.index-education.com/callback.
- Une fois l'application ajoutée, cliquez à gauche sur Personnalisation et propriétés, complétez les champs et cliquez sur Enregistrer.
- Cliquez à gauche sur Authentification, puis tout en bas sous Autoriser les flux clients publics, cochez Oui. Cliquez sur Enregistrer.
- Cliquez à gauche sur API autorisées, puis sur + Ajouter une autorisation, Microsoft Graph, Autorisations déléguées. Sous User, décochez User.Read, puis sous SMTP, cochez SMTP.Send. Cliquez ensuite tout en bas sur Ajouter des autorisations.
- Cliquez tout à gauche sur Vue d'ensemble.
- Copiez la valeur face à ID d'application (client), et conservez-la pour la renseigner dans l'application.
- Cliquez tout en haut sur Points de terminaison et copiez les deux premières valeurs, Point de terminaison d'autorisation OAuth 2.0 (v2) et Point de terminaison de jeton OAuth 2.0 (v2) pour les renseigner dans l'application.
Côté application
Dans l'application, saisissez maintenant les éléments suivants :
- Identifiant : collez ici la première valeur conservée précédemment
- Secret : laissez ce champ vide, les applications publiques sont autorisées
- Point de terminaison d'autorisation et de jetons : collez les deux autres valeurs conservées précédemment
- Autorisations demandées : https://outlook.office.com/SMTP.Send offline_access
Vous pouvez alors obtenir des jetons OAuth.
Remarques :
- L'autorisation https://outlook.office.com/SMTP.Send diffère de celle déclarée dans l'application (SMTP.Send de Microsoft Graph), mais seul un jeton obtenu avec l'autorisation https://outlook.office.com/SMTP.Send permet d'envoyer un e-mail via un serveur SMTP. Voir Authenticate an IMAP, POP or SMTP connection using OAuth
- L'autorisation offline_access est nécessaire pour obtenir un jeton d'accès et un jeton d'actualisation.
Utilisation du protocole OAuth pour les périphériques à entrée limitée
Il existe une variante du protocole OAuth qui permet à un périphérique à entrée limitée (par exemple un téléviseur connecté) de demander un jeton OAuth, il s'agit de
Device Authorization Grant. Si vous rencontrez des problèmes avec le scénario OAuth proposé par défaut, vous pouvez utiliser cette variante du protocole, elle fonctionne également pour des applications sur ordinateur.
Dans l'application, maintenez les touches
Ctrl et Maj enfoncées lorsque vous cliquez sur le bouton
pour entrer dans la fenêtre
Configuration OAuth : cela vous laisse la possibilité de basculer sur le scénario Device Authorization Grant. Dans ce scénario, le point de terminaison d'autorisation est remplacé par un point de terminaison de périphérique.
Attention, cela ne fonctionne pas avec les services de Google car vous ne pouvez pas demander l'autorisation https://mail.google.com/. Voir Étendues autorisées
Par contre, cela fonctionne avec les services de Microsoft.
Il faut juste savoir que le point de terminaison de périphérique se déduit du point de terminaison d'autorisation en changeant à la fin
authorize par
devicecode :
- https://login.microsoftonline.com/common/oauth2/v2.0/authorize devient https://login.microsoftonline.com/common/oauth2/v2.0/devicecode
- https://login.microsoftonline.com/{xxx}/oauth2/v2.0/authorize devient https://login.microsoftonline.com/{xxx}/oauth2/v2.0/devicecode
