This documentation is for an EXPERIMENTAL feature, so it may change. We are also working with the community to develop Internet standards on the use of OAuth with SASL enabled protocols. If you would like to be involved in such a discussion, join the public mailing list
XOAUTH SASL Mechanism for Gmail IMAP and SMTP
This document defines the experimental SASL mechanism XOAUTH for use with the IMAP AUTHENTICATE and SMTP AUTH commands. It allows the use of OAuth authentication parameters to authenticate to a user's GMail account. The mechanism supports standard "three-legged" OAuth and non-standard "two-legged" OAuth.
Constructing the OAuth Protocol Parameters
The OAuth Protocol Parameters will be constructed in accordance with [OAUTH], with the following restrictions.
The scope for IMAP and SMTP access is "https://mail.google.com/". Multiple scopes can be requested by specifying them in a list, separated by spaces.
OAuth Request URL
OAuth requires that a request URL be used as input to the signing algorithm. The URL will have the following format for three-legged OAuth:
https://mail.google.com/mail/b/<email address>/imap/and the following format for two-legged OAuth:
https://mail.google.com/mail/b/<email address>/imap/?xoauth_requestor_id=<url-escaped email address>
For example, to authenticate to IMAP as user firstname.lastname@example.org with 3-legged OAuth, the request URL would be:
Constructing the oauth_signature parameter
The oauth_signature parameter will be constructed according to [OAuth 9]. Section 9.1 describes creating the signature base string as a combination of the HTTP request method, the request absolute URL, and the normalized request parameters. For the XOAUTH mechanism:
For standard, three-legged OAuth, there will be an oauth_token parameter, and the signing key is generated as per [OAuth 9.2], using both the Consumer Secret and the Token Secret.
For two-legged OAuth, there will be no oauth_token parameter, and the signing key is just the Consumer Secret.
Once the oauth_signature has been been generated, the OAuth protocol parameters are combined and encoded into a comma-separated string as specified in [OAuth 5.4.1]
The SASL initial client request has the following format:
"GET" SPACE base64(<Request URL> SPACE <oauth protocol parameter string>)
using the base64 encoding mechanism defined in RFC 4648.
For example, before base64-encoding, the initial client request might look like this (with linebreaks added for clarity):
After base64-encoding, this initial client request would be (with linebreaks added for clarity):
To login with the XOAUTH mechanism, the client invokes the AUTHENTICATE command with the mechanism parameter of "XOAUTH", and the initial client request as constructed above.
Things to note about the IMAP protocol exchange:
To login with the XOAUTH mechanism, the client invokes the AUTH command with the mechanism parameter of "XOAUTH", and the initial client request as constructed above. The SMTP AUTH command is documented in RFC 2554. For example: