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 du compte Gmail d'un utilisateur.

Utiliser OAuth 2.0

Commencez par vous familiariser avec 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 fonctionnels.

Champs d'application OAuth 2.0

Le champ d'application de l'accès IMAP, POP et SMTP est https://mail.google.com/. Si vous demandez l'accès au champ d'application complet du courrier pour votre application IMAP, POP ou SMTP, elle doit respecter notre Règlement sur les données utilisateur dans les services d'API Google.

  • Pour être approuvée, votre application doit utiliser pleinement https://mail.google.com/.
  • Si votre application n'a pas besoin de https://mail.google.com/, migrez vers l'API Gmail et utilisez des scopes restreints plus précis.

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

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

Lorsque l'autorisation est accordée avec ce champ d'application, 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, quels que soient les paramètres de l'utilisateur dans "Limites de taille des dossiers" des paramètres Gmail.

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 les 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 comme suit :

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

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

Par exemple, avant l'encodage 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, cela devient (sauts de ligne insérés pour plus de clarté) :

dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52
YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cBAQ==

Réponse d'erreur

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

base64({JSON-Body})

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

eyJzdGF0dXMiOiI0MDEiLCJzY2hlbWVzIjoiYmVhcmVyIG1hYyIsInNjb3BlIjoiaHR0cHM6Ly9t
YWlsLmdvb2dsZS5jb20vIn0K

Après le décodage en base64, cela devient (formaté pour plus 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 que 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...]

Voici quelques points à noter concernant l'échange de protocole IMAP :

  • La commande IMAP AUTHENTICATE est documentée dans la RFC 3501.
  • La fonctionnalité SASL-IR permet d'envoyer la réponse initiale du client sur la première ligne de la commande AUTHENTICATE. Ainsi, un seul aller-retour est nécessaire pour l'authentification. SASL-IR est documenté dans la RFC 4959.
  • La fonctionnalité AUTH=XOAUTH2 indique que le serveur est compatible avec le mécanisme SASL défini par ce document. 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 sont là pour plus de clarté et ne seraient pas présents dans les données de commande réelles. L'intégralité de l'argument base64 doit être une chaîne continue, sans espace blanc intégré, de sorte que l'intégralité de la commande AUTHENTICATE 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

Voici quelques points à 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 commande AUTH avec le paramètre de mécanisme XOAUTH2 et la réponse initiale du client telle que construite ci-dessus. Exemple :

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

Points à noter concernant l'échange de protocole POP :

  • La commande POP AUTH est documentée dans la RFC 1734.
  • Les sauts de ligne dans la commande AUTH sont là par souci de clarté et ne seraient pas présents dans les données de commande réelles. L'intégralité de l'argument base64 doit être une chaîne continue, sans espace blanc intégré, de sorte que l'intégralité de la commande AUTH 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 que 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...]

Voici quelques points à noter concernant l'échange de protocole SMTP :

  • La commande SMTP AUTH est documentée dans la RFC 4954.
  • Les sauts de ligne dans la commande AUTH sont là par souci de clarté et ne seraient pas présents dans les données de commande réelles. L'intégralité de l'argument base64 doit être une chaîne continue, sans espace blanc intégré, de sorte que l'intégralité de la commande AUTH 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...]

Voici quelques points à 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