Mécanisme OAuth 2.0

Ce document définit le mécanisme SASL XOAUTH2 à utiliser avec les commandes IMAP AUTHENTICATE, POP AUTH et SMTP AUTH. Ce mécanisme permet d'utiliser des jetons d'accès OAuth 2.0 pour s'authentifier auprès d'un compte Gmail.

Utiliser OAuth 2.0

Commencez par vous familiariser avec la section Utiliser OAuth 2.0 pour accéder aux API Google. Ce document explique le fonctionnement d'OAuth 2.0 et les étapes nécessaires pour écrire un client.

Vous pouvez également parcourir l'exemple de code XOAUTH2 pour obtenir des exemples pratiques.

Habilitations OAuth 2.0

L'habilitation pour l'accès IMAP, POP et SMTP est https://mail.google.com/. Si vous demandez l'accès à l'habilitation de messagerie complète pour votre application IMAP, POP ou SMTP, elle doit être conforme à notre Règlement sur les données utilisateur dans les services d'API Google.

Délégation au niveau du domaine pour Google Workspace

Si vous prévoyez d'utiliser la délégation au niveau du domaine Google Workspace à l'aide de comptes de service pour accéder aux boîtes aux lettres des utilisateurs Google Workspace via IMAP, vous pouvez autoriser votre client à l'aide de l'habilitation https://www.googleapis.com/auth/gmail.imap_admin à la place.

Lorsque l'autorisation est accordée avec cette habilitation, les connexions IMAP se comportent différemment :

  • Tous les libellés sont affichés via IMAP, même si les utilisateurs ont désactivé l'option "Afficher en IMAP" pour le libellé dans les paramètres Gmail.
  • Tous les messages sont affichés via IMAP, quel que soit le paramètre défini par l'utilisateur dans "Limites de taille des dossiers" dans les paramètres Gmail.

Le mécanisme SASL XOAUTH2

Le mécanisme XOAUTH2 permet aux clients d'envoyer des jetons d'accès OAuth 2.0 au serveur. Le protocole utilise des valeurs encodées indiquées dans les sections suivantes.

Réponse initiale du client

La réponse initiale du client SASL XOAUTH2 se présente au format suivant :

base64("user=" {User} "^Aauth=Bearer " {Access Token} "^A^A")

Utilisez le mécanisme d'encodage en base64 défini dans la norme RFC 4648. ^A représente un Ctrl+A (\001).

Par exemple, avant l'encodage en base64, la réponse initiale du client peut se présenter comme suit :

user=someuser@example.com^Aauth=Bearer ya29.vF9dft4qmTc2Nvb3RlckBhdHRhdmlzdGEuY29tCg^A^A

Après l'encodage en base64, elle devient (sauts de ligne insérés par souci de clarté) :

dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52
YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cBAQ==

Réponse d'erreur

Une réponse initiale du client entraînant une erreur amène le serveur à envoyer un défi contenant un message d'erreur au format suivant :

base64({JSON-Body})

Le JSON-Body contient trois valeurs : status, schemes et scope. Exemple :

eyJzdGF0dXMiOiI0MDEiLCJzY2hlbWVzIjoiYmVhcmVyIG1hYyIsInNjb3BlIjoiaHR0cHM6Ly9t
YWlsLmdvb2dsZS5jb20vIn0K

Après le décodage en base64, elle devient (mise en forme par souci de clarté) :

{
  "status":"401",
  "schemes":"bearer",
  "scope":"https://mail.google.com/"
}

Le protocole SASL exige que les clients envoient une réponse vide à ce défi.

Échange de protocole IMAP

Cette section explique comment utiliser SASL XOAUTH2 avec le serveur IMAP Gmail.

Réponse initiale du client

Pour se connecter avec le mécanisme SASL XOAUTH2, le client appelle la commande AUTHENTICATE avec le paramètre de mécanisme XOAUTH2 et la réponse initiale du client telle qu'elle est construite ci-dessus. Exemple :

[connection begins]
C: C01 CAPABILITY
S: * CAPABILITY IMAP4rev1 UNSELECT IDLE NAMESPACE QUOTA XLIST
CHILDREN XYZZY SASL-IR AUTH=XOAUTH2 AUTH=XOAUTH
S: C01 OK Completed
C: A01 AUTHENTICATE XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvb
QFhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG
1semRHRXVZMjl0Q2cBAQ==
S: A01 OK Success
[connection continues...]

Éléments à noter concernant l'échange de protocole IMAP :

  • La commande IMAP AUTHENTICATE est documentée dans la norme RFC 3501.
  • La fonctionnalité SASL-IR permet d'envoyer la réponse initiale du client sur la première ligne de la commande AUTHENTICATE, de sorte qu'un seul aller-retour est nécessaire pour l'authentification. SASL-IR est documenté dans la norme RFC 4959.
  • La fonctionnalité AUTH=XOAUTH2 déclare que le serveur est compatible avec le mécanisme SASL défini par ce document, et que ce mécanisme est activé en spécifiant XOAUTH2 comme premier argument de la commande AUTHENTICATE.
  • Les sauts de ligne dans les commandes AUTHENTICATE et CAPABILITY ne sont là que par souci de clarté et ne seraient pas présents dans les données de commande réelles. L'argument base64 entier doit être une chaîne continue, sans espace blanc intégré, de sorte que la commande AUTHENTICATE complète se compose d'une seule ligne de texte.

Réponse d'erreur

Les échecs d'authentification sont également renvoyés via la commande IMAP AUTHENTICATE :

[connection begins]
S: * CAPABILITY IMAP4rev1 UNSELECT IDLE NAMESPACE QUOTA XLIST
CHILDREN XYZZY SASL-IR AUTH=XOAUTH2
S: C01 OK Completed
C: A01 AUTHENTICATE XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQ
FhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1s
emRHRXVZMjl0Q2cBAQ==
S: + eyJzdGF0dXMiOiI0MDEiLCJzY2hlbWVzIjoiYmVhcmVyIG1hYyIsInNjb
3BlIjoiaHR0cHM6Ly9tYWlsLmdvb2dsZS5jb20vIn0K
C:
S: A01 NO SASL authentication failed

Éléments à noter concernant l'échange de protocole IMAP :

  • Le client envoie une réponse vide ("\r\n") au défi contenant le message d'erreur.

Échange de protocole POP

Cette section explique comment utiliser SASL XOAUTH2 avec le serveur POP Gmail.

Réponse initiale du client

Pour se connecter avec le mécanisme SASL XOAUTH2, le client appelle la AUTH commande avec le paramètre de mécanisme XOAUTH2 et la réponse initiale du client telle qu'elle est construite ci-dessus. Exemple :

[connection begins]
C: AUTH XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYX
JlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0
Q2cBAQ==
S: +OK Welcome.
[connection continues...]

Éléments à noter concernant l'échange de protocole POP :

  • La commande POP AUTH est documentée dans la norme RFC 1734.
  • Les sauts de ligne dans la commande AUTH ne sont là que par souci de clarté et ne seraient pas présents dans les données de commande réelles. L'argument base64 entier doit être une chaîne continue, sans espace blanc intégré, de sorte que la commande AUTH complète se compose d'une seule ligne de texte.

Réponse d'erreur

Les échecs d'authentification sont également renvoyés via la commande POP AUTH :

[connection begins]
C: AUTH XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlY
XJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMj
l0Q2cBAQ==
S: + eyJzdGF0dXMiOiI0MDAiLCJzY2hlbWVzIjoiQmVhcmVyIiwic2NvcGUi
OiJodHRwczovL21haWwuZ29vZ2xlLmNvbS8ifQ==

Échange de protocole SMTP

Cette section explique comment utiliser SASL XOAUTH2 avec le serveur SMTP Gmail.

Réponse initiale du client

Pour se connecter avec le mécanisme XOAUTH2, le client appelle la commande AUTH avec le paramètre de mécanisme XOAUTH2 et la réponse initiale du client telle qu'elle est construite ci-dessus. Exemple :

[connection begins]
S: 220 mx.google.com ESMTP 12sm2095603fks.9
C: EHLO sender.example.com
S: 250-mx.google.com at your service, [172.31.135.47]
S: 250-SIZE 35651584
S: 250-8BITMIME
S: 250-AUTH LOGIN PLAIN XOAUTH XOAUTH2
S: 250-ENHANCEDSTATUSCODES
S: 250 PIPELINING
C: AUTH XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlY
XJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMj
l0Q2cBAQ==
S: 235 2.7.0 Accepted
[connection continues...]

Éléments à noter concernant l'échange de protocole SMTP :

  • La commande SMTP AUTH est documentée dans RFC 4954.
  • Les sauts de ligne dans la commande AUTH ne sont là que par souci de clarté et ne seraient pas présents dans les données de commande réelles. L'argument base64 entier doit être une chaîne continue, sans espace blanc intégré, de sorte que la commande AUTH complète se compose d'une seule ligne de texte.

Réponse d'erreur

Les échecs d'authentification sont également renvoyés via la commande SMTP AUTH :

[connection begins]
S: 220 mx.google.com ESMTP 12sm2095603fks.9
C: EHLO sender.example.com
S: 250-mx.google.com at your service, [172.31.135.47]
S: 250-SIZE 35651584
S: 250-8BITMIME
S: 250-AUTH LOGIN PLAIN XOAUTH XOAUTH2
S: 250-ENHANCEDSTATUSCODES
S: 250 PIPELINING
C: AUTH XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJl
ciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cB
AQ==
S: 334 eyJzdGF0dXMiOiI0MDEiLCJzY2hlbWVzIjoiYmVhcmVyIG1hYyIsInNjb
3BlIjoiaHR0cHM6Ly9tYWlsLmdvb2dsZS5jb20vIn0K
C:
S: 535-5.7.1 Username and Password not accepted. Learn more at
S: 535 5.7.1 https://support.google.com/mail/?p=BadCredentials hx9sm5317360pbc.68
[connection continues...]

Éléments à noter concernant l'échange de protocole SMTP :

  • Le client envoie une réponse vide ("\r\n") au défi contenant le message d'erreur.

Références