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/
https://mail.google.com/mail/b/<email address>/smtp/
and the following format for two-legged OAuth:
https://mail.google.com/mail/b/<email address>/imap/?xoauth_requestor_id=<url-escaped email address>
https://mail.google.com/mail/b/<email address>/smtp/?xoauth_requestor_id=<url-escaped email address>
For example, to authenticate to IMAP as user someuser@example.com with 3-legged OAuth, the request URL would be:
https://mail.google.com/mail/b/someuser@example.com/imap/
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:
The HTTP request method is GET.
The request URL is defined in above section.
The request parameters consist of all the oauth parameters except the oauth_signature parameter; and also (for two-legged OAuth) the xoauth_requestor_id parameter from the request URL.
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):
(2-legged OAuth)
GET https://mail.google.com/mail/b/someuser@example.com/imap/?xoauth_requestor_id=someuser%40example.com
oauth_consumer_key="example.com",
oauth_nonce="4710307327925439451",
oauth_signature="75%2BB63NbW2GdDMaOCEd%2Fy%2Fb%2B0Qk%3D",
oauth_signature_method="HMAC-SHA1",
oauth_timestamp="1260933683",
oauth_version="1.0"
(3-legged OAuth)
GET https://mail.google.com/mail/b/someuser@example.com/imap/
oauth_consumer_key="anonymous",
oauth_nonce="4710307327925439451",
oauth_signature="75%2BB63NbW2GdDMaOCEd%2Fy%2Fb%2B0Qk%3D",
oauth_signature_method="HMAC-SHA1",
oauth_timestamp="1260933683",
oauth_token="0j20h2jhgp93hls9hj",
oauth_version="1.0"
After base64-encoding, this initial client request would be (with linebreaks added for clarity):
R0VUIGh0dHBzOi8vbWFpbC5nb29nbGUuY29tL21haWwvYi9zb21ldXNlckBleGF
tcGxlLmNvbS9pbWFwLz94b2F1dGhfcmVxdWVzdG9yX2lkPXNvbWV1c2VyJTQwZX
hhbXBsZS5jb20gb2F1dGhfY29uc3VtZXJfa2V5PSJleGFtcGxlLmNvbSIsb2F1d
Ghfbm9uY2U9IjQ3MTAzMDczMjc5MjU0Mzk0NTEiLG9hdXRoX3NpZ25hdHVyZT0i
NzUlMkJCNjNOYlcyR2RETWFPQ0VkJTJGeSUyRmIlMkIwUWslM0QiLG9hdXRoX3N
pZ25hdHVyZV9tZXRob2Q9IkhNQUMtU0hBMSIsb2F1dGhfdGltZXN0YW1wPSIxMj
YwOTMzNjgzIixvYXV0aF92ZXJzaW9uPSIxLjAiCg==
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.
For example:
[connection begins]
C: C01 CAPABILITY
S: * CAPABILITY IMAP4rev1 UNSELECT IDLE NAMESPACE QUOTA XLIST
CHILDREN XYZZY SASL-IR AUTH=XOAUTH
S: C01 OK Completed
C: A01 AUTHENTICATE XOAUTH R0VUIGh0dHBzOi8vbWFpbC5nb29nbGUuY29tL21haWwvYi9zb21ldXN
lckBleGFtcGxlLmNvbS9pbWFwLyBvYXV0aF9jb25zdW1lcl9rZXk9ImFub255bW91cyIsb2F1dGhfbm9uY
2U9Ijc5OTIxNDU5MDIzMDY4MTQxNDQiLG9hdXRoX3NpZ25hdHVyZT0iazJidXU4cWYwd1E0U1pDNW9rZUI
2MSUyQnBBTWslM0QiLG9hdXRoX3NpZ25hdHVyZV9tZXRob2Q9IkhNQUMtU0hBMSIsb2F1dGhfdGltZXN0Y
W1wPSIxMjY3MjA1Njg4IixvYXV0aF90b2tlbj0iYXNkZmFzZGYiLG9hdXRoX3ZlcnNpb249IjEuMCI=
S: A01 OK Success
[connection continues...]
Things to note about the IMAP protocol exchange:
The SASL-IR capability allows for sending the initial client request 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=XOAUTH capability declares that the server supports the SASL mechanism defined by this document, and this mechanism is activated by specifying XOAUTH as the first argument to the AUTHENTICATE command.
The linebreaks 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.
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:
[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
S: 250-ENHANCEDSTATUSCODES
S: 250 PIPELINING
C: AUTH XOAUTH R0VUIGh0dHBzOi8vbWFpbC5nb29nbGUuY29tL21ha
WwvYi9zb21ldXNlckBleGFtcGxlLmNvbS9zbXRwLyBvYXV0aF9jb25zd
W1lcl9rZXk9ImFub255bW91cyIsb2F1dGhfbm9uY2U9IjIwNDg1MjE2O
DgzNjgyNzY0MzAiLG9hdXRoX3NpZ25hdHVyZT0iVEJNQmo2NG9ZMzNJd
ERUOWxtUGlveGF0Uko0JTNEIixvYXV0aF9zaWduYXR1cmVfbWV0aG9kP
SJITUFDLVNIQTEiLG9hdXRoX3RpbWVzdGFtcD0iMTI2NzIwNTc2OSIsb
2F1dGhfdG9rZW49ImFzZGZhc2RmIixvYXV0aF92ZXJzaW9uPSIxLjAi
S: 235 2.7.0 Accepted
[connection continues...]
References