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 l'accès aux API Google via OAuth 2.0. Ce document explique le fonctionnement d'OAuth 2.0 et la procédure à suivre 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 à l'ensemble des paramètres de messagerie de votre application IMAP, POP ou SMTP, vous devez respecter notre Règlement sur les données utilisateur dans les services d'API Google.

  • Pour être approuvée, votre application doit utiliser au maximum https://mail.google.com/.
  • Si votre application ne nécessite pas https://mail.google.com/, migrez vers l'API Gmail et utilisez des champs d'application restreints plus précis.

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

Si vous avez l'intention de Google Workspace déléguer l'ensemble du domaine avec des comptes de service pour accéder Google Workspace aux boîtes aux lettres des utilisateurs via IMAP, vous pouvez autoriser votre client en définissant le champ d'application https://www.googleapis.com/auth/gmail.imap_admin à la place.

Lorsqu'elles sont autorisées 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, quelle que soit la valeur définie par l'utilisateur dans la section "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 des valeurs encodées présentées dans les sections suivantes.

Réponse initiale du client

La réponse initiale du client SASL XOAUTH2 a le format suivant:

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

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

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

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

Après l'encodage en base64, voici ce qui se produit (des sauts de ligne ont été insérés pour plus de clarté):

dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52
YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cBAQ==

Réponse d'erreur

Une réponse initiale du client entraînant une erreur entraîne l'envoi par le serveur d'une question d'authentification 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, le code 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 test.

Protocole IMAP

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

Réponse initiale du client

Pour se connecter à l'aide du 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...]

Remarques à propos de l'échange de protocoles IMAP:

  • La commande IMAP AUTHENTICATE est documentée dans le document RFC 3501.
  • La capacité SASL-IR permet d'envoyer la réponse initiale du client dans la première ligne de la commande AUTHENTICATE, de sorte qu'un seul aller-retour est requis pour l'authentification. Le protocole SASL-IR est documenté dans le document RFC 4959.
  • La fonctionnalité AUTH=XOAUTH2 déclare que le serveur prend en charge le mécanisme SASL défini dans ce document, et ce mécanisme est activé en spécifiant XOAUTH2 comme premier argument de la commande AUTHENTICATE.
  • Par souci de clarté, les sauts de ligne dans les commandes AUTHENTICATE et CAPABILITY ne figurent pas 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 la commande AUTHENTICATE consiste en une seule ligne de texte.

Réponse d'erreur

Les échecs d'authentification sont également renvoyés par 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

Remarques à propos de l'échange de protocoles IMAP:

  • Le client envoie une réponse vide ("\r\n") à la question d'authentification 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 à l'aide du 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...]

Remarques à propos de l'échange de protocole POP:

  • La commande POP AUTH est documentée dans le document RFC 1734.
  • Les sauts de ligne dans la commande AUTH sont indiqués par souci de clarté et ne figureront pas 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 la commande AUTH consiste en une seule ligne de texte.

Réponse d'erreur

Les échecs d'authentification sont également renvoyés par 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 à l'aide du 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...]

Remarques à propos de l'échange de protocole SMTP:

  • La commande SMTP AUTH est documentée dans le document RFC 4954.
  • Les sauts de ligne dans la commande AUTH sont indiqués par souci de clarté et ne figureront pas 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 la commande AUTH consiste en une seule ligne de texte.

Réponse d'erreur

Les échecs d'authentification sont également renvoyés par 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...]

Remarques à propos de l'échange de protocole SMTP:

  • Le client envoie une réponse vide ("\r\n") à la question d'authentification contenant le message d'erreur.

Références