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. OAuth Access TokenThe 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 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:
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] SASL Initial Client RequestThe 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 (3-legged OAuth) GET https://mail.google.com/mail/b/someuser@example.com/imap/ After base64-encoding, this initial client request would be (with linebreaks added for clarity): R0VUIGh0dHBzOi8vbWFpbC5nb29nbGUuY29tL21haWwvYi9zb21ldXNlckBleGF IMAP protocol exchangeTo 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] Things to note about the IMAP protocol exchange:
SMTP protocol exchangeTo 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] References
|