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 requises pour écrire un client.

Vous pouvez également consulter 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'étendue de messagerie complète 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 https://mail.google.com/ à plein.
  • Si votre application n'a pas besoin de 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 prévoyez d'utiliser la délégation au niveau du domaineGoogle Workspace à l'aide de comptes de service pour accéder aux boîtes aux lettres des utilisateurs via IMAP, vous pouvez autoriser votre client à l'aide du champ d'application https://www.googleapis.com/auth/gmail.imap_admin. Google Workspace

Lorsqu'elles sont autorisées avec cette portée, 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.

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 client initiale 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 la RFC 4648. ^A représente Ctrl+A (\001).

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

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

Après l'encodage en base64, la chaîne devient (sauts de ligne insérés pour plus de clarté):

dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52
YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cBAQ==

Réponse d'erreur

Une réponse client initiale entraînant une erreur entraîne l'envoi par le serveur d'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, la chaîne devient (mise en forme 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 client initiale telle que créée 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 la RFC 3501.
  • La fonctionnalité SASL-IR permet d'envoyer la réponse client initiale 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 la RFC 4959.
  • La capacité AUTH=XOAUTH2 déclare que le serveur est compatible avec le mécanisme SASL défini dans 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 destinés à clarifier les choses et ne figurent pas dans les données de commande réelles. L'argument base64 doit être une chaîne continue, sans espace blanc intégré, de sorte que la commande AUTHENTICATE entière consiste en 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

Remarques concernant l'échange de protocole IMAP:

  • Le client envoie une réponse vide ("\r\n") à la requête 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 client initiale telle que créée 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 la RFC 1734.
  • Les sauts de ligne dans la commande AUTH sont là pour plus de clarté et ne sont pas présents dans les données de commande réelles. L'argument base64 doit être une chaîne continue, sans espace blanc intégré, de sorte que la commande AUTH entière consiste en 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 client initiale 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 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à pour plus de clarté et ne sont pas présents dans les données de commande réelles. L'argument base64 doit être une chaîne continue, sans espace blanc intégré, de sorte que la commande AUTH entière consiste en 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...]

Remarques concernant l'échange de protocole SMTP:

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

Références