Base de connaissances EDT-
Comment envoyer des e-mails via le protocole OAuth ?
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" :
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.
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.
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 :
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 :
- 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.
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.
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 :
Vous pouvez alors obtenir des jetons OAuth.
- 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
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 :
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
Ce contenu vous a été utile ?
Vous ne trouvez pas de réponse à votre question ?
Contactez notre assistance