Quick Run-Through with xoauth.py

xoauth.py is a script and library to help developers implement and debug Xoauth support in Python. Even if you're not programming in Python, the script can be used as a standalone utility for generating and authorizing OAuth tokens, and for generating Xoauth authentication strings from OAuth tokens.

You can download xoauth.py from the source repository on the web, or checkout the repository with SVN. You will also need to have Python version 2.4 or greater installed on your system; it can be downloaded from the python.org download site.

Throughout the tutorial we'll use the hypothetical user xoauth@gmail.com. During testing you should substitute your own Gmail or Google Mail email address, and in production this would be the Google email address of your users.

Creating and Authorizing an OAuth Token

The first step is to create and authorize an anonymous OAuth token.

$ python xoauth.py --generate_oauth_token --user=xoauth@gmail.com
oauth_token_secret: 41r18IyXjIvuyabS/NDyW6+m
oauth_token: 4/nM2QAaunKUINb4RrXPC55F-mix_k
oauth_callback_confirmed: true
To authorize token, visit this url and follow the directions to generate a verification code:
  https://www.google.com/accounts/OAuthAuthorizeToken?oauth_token=4%2FnM2QAaunKUINb4RrXPC55F-mix_k
  Enter verification code:

Visit the URL in your browser, and click the "Grant Access" button.

The next page will provide a verification code.

Copy that code and paste it in the xoauth.py script window, and hit <Enter>. xoauth.py will respond with an oauth_token and oauth_token_secret.

$ python xoauth.py --generate_oauth_token --user=xoauth@gmail.com
oauth_token_secret: 41r18IyXjIvuyabS/NDyW6+m
oauth_token: 4/nM2QAaunKUINb4RrXPC55F-mix_k
oauth_callback_confirmed: true
To authorize token, visit this url and follow the directions to generate a verification code:
  https://www.google.com/accounts/OAuthAuthorizeToken?oauth_token=4%2FnM2QAaunKUINb4RrXPC55F-mix_k
  Enter verification code: VFvY1j0R22BKuDtvN4gaAgZq
oauth_token: 1/C1va1J7SjTd1-cddVmG2iqla2XmG8xRqX3UXuqt7Eps
oauth_token_secret: sSCKc+z1xLlT+htfihqcAM3h
$

Copy oauth_token and oauth_token_secret down somewhere, as you'll want to use them for your testing. They can be used over and over again until they are revoked. To view or revoke your OAuth tokens, visit this Google Accounts page. You can also generate a new set at any time by repeating the above steps.

Generating an Xoauth Authentication String

Next, we can use xoauth.py to generate a XOAUTH authentication string using the oauth_token and oauth_token_secret.

$ python xoauth.py --generate_xoauth_string --user=xoauth@gmail.com --oauth_token=1/C1va1J7SjTd1-cddVmG2iqla2XmG8xRqX3UXuqt7Eps --oauth_token_secret=sSCKc+z1xLlT+htfihqcAM3h
signature base string:
GET&https%3A%2F%2Fmail.google.com%2Fmail%2Fb%2Fxoauth%40gmail.com%2Fimap%2F&oauth_consumer_key%3Danonymous%26oauth_nonce%3D2962782392770406806%26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp%3D1269468597%26oauth_token%3D1%252FC1va1J7SjTd1-cddVmG2iqla2XmG8xRqX3UXuqt7Eps%26oauth_version%3D1.0

xoauth string (before base64-encoding):
GET https://mail.google.com/mail/b/xoauth@gmail.com/imap/ oauth_consumer_key="anonymous",oauth_nonce="2962782392770406806",oauth_signature="dsRkigAYlJPbMOseSAyqkJ%2FcLL4%3D",oauth_signature_method="HMAC-SHA1",oauth_timestamp="1269468597",oauth_token="1%2FC1va1J7SjTd1-cddVmG2iqla2XmG8xRqX3UXuqt7Eps",oauth_version="1.0"

XOAUTH string (base64-encoded): R0VUIGh0dHBzOi8vbWFpbC5nb29nbGUuY29tL21haWwvYi94b2F1dGhAZ21haWwuY29tL2ltYXAvIG9hdXRoX2NvbnN1bWVyX2tleT0iYW5vbnltb3VzIixvYXV0aF9ub25jZT0iMjk2Mjc4MjM5Mjc3MDQwNjgwNiIsb2F1dGhfc2lnbmF0dXJlPSJkc1JraWdBWWxKUGJNT3NlU0F5cWtKJTJGY0xMNCUzRCIsb2F1dGhfc2lnbmF0dXJlX21ldGhvZD0iSE1BQy1TSEExIixvYXV0aF90aW1lc3RhbXA9IjEyNjk0Njg1OTciLG9hdXRoX3Rva2VuPSIxJTJGQzF2YTFKN1NqVGQxLWNkZFZtRzJpcWxhMlhtRzh4UnFYM1VYdXF0N0VwcyIsb2F1dGhfdmVyc2lvbj0iMS4wIg==

The base64-encoded string R0VUI... is what you would want to pass to the IMAP AUTHENTICATE command.

Logging in to IMAP with Xoauth

Finally, xoauth.py can go one step further and connect to Google Mail's IMAP server and attempt to authenticate.

$ python xoauth.py --test_imap_authentication --user=xoauth@gmail.com \
     --oauth_token=1/C1va1J7SjTd1-cddVmG2iqla2XmG8xRqX3UXuqt7Eps --oauth_token_secret=sSCKc+z1xLlT+htfihqcAM3h

signature base string:
GET&https%3A%2F%2Fmail.google.com%2Fmail%2Fb%2Fxoauth%40gmail.com%2Fimap%2F&oauth_consumer_key%3Danonymous%26oauth_nonce%3D1228371114564228351%26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp%3D1269468281%26oauth_token%3D1%252FC1va1J7SjTd1-cddVmG2iqla2XmG8xRqX3UXuqt7Eps%26oauth_version%3D1.0

xoauth string (before base64-encoding):
GET https://mail.google.com/mail/b/xoauth@gmail.com/imap/ oauth_consumer_key="anonymous",oauth_nonce="1228371114564228351",oauth_signature="5XwIr9RqhLMosuXVVdM%2BrRuVNOs%3D",oauth_signature_method="HMAC-SHA1",oauth_timestamp="1269468281",oauth_token="1%2FC1va1J7SjTd1-cddVmG2iqla2XmG8xRqX3UXuqt7Eps",oauth_version="1.0"

XOAUTH string (base64-encoded): R0VUIGh0dHBzOi8vbWFpbC5nb29nbGUuY29tL21haWwvYi94b2F1dGhAZ21haWwuY29tL2ltYXAvIG9hdXRoX2NvbnN1bWVyX2tleT0iYW5vbnltb3VzIixvYXV0aF9ub25jZT0iMTIyODM3MTExNDU2NDIyODM1MSIsb2F1dGhfc2lnbmF0dXJlPSI1WHdJcjlScWhMTW9zdVhWVmRNJTJCclJ1Vk5PcyUzRCIsb2F1dGhfc2lnbmF0dXJlX21ldGhvZD0iSE1BQy1TSEExIixvYXV0aF90aW1lc3RhbXA9IjEyNjk0NjgyODEiLG9hdXRoX3Rva2VuPSIxJTJGQzF2YTFKN1NqVGQxLWNkZFZtRzJpcWxhMlhtRzh4UnFYM1VYdXF0N0VwcyIsb2F1dGhfdmVyc2lvbj0iMS4wIg==

  04:42.43 > KNPK1 AUTHENTICATE XOAUTH
  04:42.60 < +
  04:42.60 write literal size 428
  04:43.76 < * CAPABILITY IMAP4rev1 UNSELECT LITERAL+ IDLE NAMESPACE QUOTA ID XLIST CHILDREN X-GM-EXT-1 UIDPLUS COMPRESS=DEFLATE
  04:43.76 < KNPK1 OK xoauth@gmail.com authenticated (Success)
  04:43.76 > KNPK2 SELECT INBOX
  04:44.63 < * FLAGS (\Answered \Flagged \Draft \Deleted \Seen)
  04:44.63 < * OK [PERMANENTFLAGS (\Answered \Flagged \Draft \Deleted \Seen \*)]
  04:44.63 < * OK [UIDVALIDITY 634733457]
  04:44.64 < * 0 EXISTS
  04:44.64 < * 0 RECENT
  04:44.64 < * OK [UIDNEXT 5]
  04:44.64 < KNPK2 OK [READ-WRITE] INBOX selected. (Success)

 $

The debug protocol dump shows that xoauth.py successfully authenticated to IMAP (OK xoauth@gmail.com authenticated (Success)). The entry write literal size 428 is where xoauth.py is sending the base64-encoded Xoauth string to the server.