Mécanisme OAuth 2.0

Ce document définit le mécanisme SASL XOAUTH2 à utiliser avec le protocole IMAP Commandes AUTHENTICATE, POP AUTH et SMTP AUTH. Ce mécanisme permet l'utilisation de 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 les étapes requises pour écrire un client.

Vous pouvez également parcourir l'exemple de code XOAUTH2 pour découvrir 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 demander l'accès à l'ensemble des e-mails pour votre application IMAP, POP ou SMTP ; elles doivent être conformes à nos Règles relatives aux données utilisateur dans les services d'API Google.

  • Pour être approuvée, votre appli doit montrer qu'elle utilise entièrement https://mail.google.com/.
  • Si votre application ne nécessite pas https://mail.google.com/, migrez vers Gmail API et utilisez des champs d'application restreints plus précis.

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

Si vous prévoyez d'utiliser Google Workspace délégation au niveau du domaine avec Comptes de service pour accéder aux Google Workspace utilisateurs vos boîtes aux lettres via IMAP, vous pouvez autoriser votre client à l'aide du 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, quelles que soient les valeurs définies 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 les valeurs encodées présentées dans les sections suivantes.

Réponse initiale du client

La réponse initiale du client SASL XOAUTH2 est au 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 une combinaison de touches 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, cela se présente comme suit (sauts de ligne insérés pour plus de clarté):

dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52
YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cBAQ==

Réponse d'erreur

Une réponse initiale du client provoquant une erreur entraîne l'envoi par le serveur d'une 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 à 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, comme illustré 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 concernant l'échange de protocole IMAP:

  • La commande IMAP AUTHENTICATE est documentée dans le document RFC 3501.
  • La fonctionnalité 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 nécessaire pour l'authentification. SASL-IR est documenté dans le document RFC 4959.
  • La capacité AUTH=XOAUTH2 déclare que le serveur prend en charge 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 fournis par souci de clarté et ne figurent pas dans les données de commande réelles. L'argument base64 complet doit être une chaîne continue sans espace blanc intégré, de sorte que l'intégralité de 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 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 à 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, comme illustré ci-dessus. Exemple :

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

Remarques concernant 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 fournis par souci de clarté et ne sont pas présents dans les données de commande réelles. L'argument base64 complet doit être une chaîne continue sans espace blanc intégré, de sorte que l'intégralité de 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 protocoles 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, comme illustré 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 concernant 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 fournis par souci de clarté et ne sont pas présents dans les données de commande réelles. L'argument base64 complet doit être une chaîne continue sans espace blanc intégré, de sorte que l'intégralité de 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 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