OAuth 2.0 Mechanism

This document defines the SASL XOAUTH2 mechanism for use with the IMAP AUTHENTICATE and SMTP AUTH commands. This mechanism allows the use of OAuth 2.0 Access Tokens to authenticate to a user's Gmail account.

Using OAuth 2.0

Start by familiarizing yourself with Using OAuth 2.0 to Access Google APIs. That document explains how OAuth 2.0 works, and the steps required to write a client.

You may also want to browse the sample XOAUTH2 code for working examples.

OAuth 2.0 Scopes

The scope for IMAP and SMTP access is https://mail.google.com/.

Domain-wide delegation for G Suite

If you intend to use G Suite domain-wide delegation using Service Accounts to access G Suite users' mailboxes, you can authorize your client using the scope https://www.googleapis.com/auth/gmail.imap_admin instead.

When authorized with this scope, IMAP connections behave differently:

  • All labels are shown via IMAP, even if users disabled "Show in IMAP" for the label in the Gmail settings.
  • All messages are shown via IMAP, regardless of what the user set in "Folder Size Limits" in the Gmail settings.

The SASL XOAUTH2 Mechanism

The XOAUTH2 mechanism allows clients to send OAuth 2.0 access tokens to the server. The protocol uses encoded values shown in the following sections.

Initial Client Response

The SASL XOAUTH2 initial client response has the following format:

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

using the base64 encoding mechanism defined in RFC 4648. ^A represents a Control+A (\001).

For example, before base64-encoding, the initial client response might look like this:

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

After base64-encoding, this becomes (line breaks inserted for clarity):

dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJlciB2RjlkZnQ0cW1UYzJOdmIzUmxj
a0JoZEhSaGRtbHpkR0V1WTI5dENnPT0BAQ==

Error Response

A initial client response causing an error results in the server sending a challenge containing an error message in the following format:

base64({JSON-Body})

The JSON-Body contains three values: status, schemes, and scope. For example:

eyJzdGF0dXMiOiI0MDEiLCJzY2hlbWVzIjoiYmVhcmVyIG1hYyIsInNjb3BlIjoiaHR0cHM6Ly9t
YWlsLmdvb2dsZS5jb20vIn0K

After base64-decoding, this becomes (formatted for clarity):

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

The SASL protocol requires clients to send an empty response to this challenge.

IMAP Protocol Exchange

Initial Client Response

To log in with the SASL XOAUTH2 mechanism, the client invokes the AUTHENTICATE command with the mechanism parameter of XOAUTH2, and the initial client response as constructed above. For example:

[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
QFhdXRoPUJlYXJlciB2RjlkZnQ0cW1UYzJOdmIzUmxja0JoZEhSaGRtbHpkR0
V1WTI5dENnPT0BAQ==
S: A01 OK Success
[connection continues...]

Things to note about the IMAP protocol exchange:

  • The IMAP AUTHENTICATE command is documented in RFC 3501.
  • The SASL-IR capability allows for sending the initial client response in the first line of the AUTHENTICATE command, so that only one round trip is required for authentication. SASL-IR is documented in RFC 4959.
  • The AUTH=XOAUTH2 capability declares that the server supports the SASL mechanism defined by this document, and this mechanism is activated by specifying XOAUTH2 as the first argument to the AUTHENTICATE command.
  • The line breaks in the AUTHENTICATE and CAPABILITY commands are for clarity and would not be present in the actual command data. The entire base64 argument should be one continuous string, with no embedded whitespace, so that the entire AUTHENTICATE command consists of a single line of text.

Error Response

Authentication failures are also returned via the IMAP AUTHENTICATE command:

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

Things to note about the IMAP protocol exchange:

  • The client sends an empty response ("\r\n") to the challenge containing the error message.

SMTP Protocol Exchange

Initial Client Response

To log in with the XOAUTH2 mechanism, the client invokes the AUTH command with the mechanism parameter of XOAUTH2, and the initial client response as constructed above. For example:

[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
ciB2RjlkZnQ0cW1UYzJOdmIzUmxja0JoZEhSaGRtbHpkR0V1WTI5dENnPT0BAQ==
S: 235 2.7.0 Accepted
[connection continues...]

Things to note about the SMTP protocol exchange:

  • The SMTP AUTH command is documented in RFC 4954.
  • The line breaks in the AUTH command are for clarity and would not be present in the actual command data. The entire base64 argument should be one continuous string, with no embedded whitespace, so that the entire AUTH command consists of a single line of text.

Error Response

Authentication failures are also returned via the SMTP AUTH command:

[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
ciB2RjlkZnQ0cW1UYzJOdmIzUmxja0JoZEhSaGRtbHpkR0V1WTI5dENnPT0BAQ==
S: 334 eyJzdGF0dXMiOiI0MDEiLCJzY2hlbWVzIjoiYmVhcmVyIG1hYyIsInNjb
3BlIjoiaHR0cHM6Ly9tYWlsLmdvb2dsZS5jb20vIn0K
C:
S: 535-5.7.1 Username and Password not accepted. Learn more at
S: 535 5.7.1 http://support.google.com/mail/bin/answer.py?answer=14257 hx9sm5317360pbc.68
[connection continues...]

Things to note about the SMTP protocol exchange:

  • The client sends an empty response ("\r\n") to the challenge containing the error message.

References

Enviar comentarios sobre…