gmail_xoauth 0.3.2 → 0.4.1

data/LICENSE

@@ -1,4 +1,4 @@
-Author: Nicolas Fouché <nicolas@silentale.com>
+Author: Nicolas Fouché <nicolas.fouche@gmail.com>
 Copyright: (C) 2011 Silentale SAS
 
 Licensed under the Apache License, Version 2.0 (the "License");

data/README.markdown

@@ -1,18 +1,48 @@
 # gmail_xoauth [![Dependency Status](https://gemnasium.com/nfo/gmail_xoauth.png)](https://gemnasium.com/nfo/gmail_xoauth)
 
-Get access to [Gmail IMAP and STMP via OAuth](http://code.google.com/apis/gmail/oauth), using the standard Ruby Net libraries.
+Get access to [Gmail IMAP and STMP via OAuth2](https://developers.google.com/google-apps/gmail/xoauth2_protocol) and [OAuth 1.0a](https://developers.google.com/google-apps/gmail/oauth_protocol), using the standard Ruby Net libraries.
 
 The gem supports 3-legged OAuth, and 2-legged OAuth for Google Apps Business or Education account owners.
 
-Note: 2-legged OAuth support was added by [Wojciech Kruszewski](https://github.com/wojciech).
-
 ## Install
 
     $ gem install gmail_xoauth
 
-## Usage
+## Usage for OAuth 2.0
+
+### Get your OAuth 2.0 tokens
+
+You can generate and validate your OAuth 2.0 tokens thanks to the [oauth2.py tool](http://code.google.com/p/google-mail-oauth2-tools/wiki/OAuth2DotPyRunThrough).
+
+Create your API project in the [Google APIs console](https://code.google.com/apis/console/), from the "API Access" tab.
+
+    $ python oauth2.py --generate_oauth2_token --client_id=364545978226.apps.googleusercontent.com --client_secret=zNrNsBzOOnQy8_O-8LkofeTR
+
+### IMAP OAuth 2.0
 
-### Get your OAuth tokens
+```ruby
+require 'gmail_xoauth'
+imap = Net::IMAP.new('imap.gmail.com', 993, usessl = true, certs = nil, verify = false)
+imap.authenticate('XOAUTH2', 'myemail@gmail.com', my_oauth2_token)
+messages_count = imap.status('INBOX', ['MESSAGES'])['MESSAGES']
+puts "Seeing #{messages_count} messages in INBOX"
+```
+
+### SMTP OAuth 2.0
+
+```ruby
+require 'gmail_xoauth'
+smtp = Net::SMTP.new('smtp.gmail.com', 587)
+smtp.enable_starttls_auto
+smtp.start('gmail.com', 'myemail@gmail.com', my_oauth2_token, :xoauth2)
+smtp.finish
+```
+
+## Usage for OAuth 1.0a
+
+== *[OAuth 1.0 has been officially deprecated as of April 20, 2012](https://developers.google.com/google-apps/gmail/oauth_protocol)*. ==
+
+### Get your OAuth 1.0a tokens
 
 For testing, you can generate and validate your OAuth tokens thanks to the awesome [xoauth.py tool](http://code.google.com/p/google-mail-xoauth-tools/wiki/XoauthDotPyRunThrough).
 
@@ -20,76 +50,85 @@ For testing, you can generate and validate your OAuth tokens thanks to the aweso
 
 Or if you want some webapp code, check the [gmail-oauth-sinatra](https://github.com/nfo/gmail-oauth-sinatra) project.
 
-### IMAP
+### IMAP 3-legged OAuth 1.0a
 
 For your tests, Gmail allows to set 'anonymous' as the consumer key and secret.
 
-    require 'gmail_xoauth'
-    imap = Net::IMAP.new('imap.gmail.com', 993, usessl = true, certs = nil, verify = false)
-    imap.authenticate('XOAUTH', 'myemail@gmail.com',
-      :consumer_key => 'anonymous',
-      :consumer_secret => 'anonymous',
-      :token => '4/nM2QAaunKUINb4RrXPC55F-mix_k',
-      :token_secret => '41r18IyXjIvuyabS/NDyW6+m'
-    )
-    messages_count = imap.status('INBOX', ['MESSAGES'])['MESSAGES']
-    puts "Seeing #{messages_count} messages in INBOX"
+```ruby
+require 'gmail_xoauth'
+imap = Net::IMAP.new('imap.gmail.com', 993, usessl = true, certs = nil, verify = false)
+imap.authenticate('XOAUTH', 'myemail@gmail.com',
+  :consumer_key => 'anonymous',
+  :consumer_secret => 'anonymous',
+  :token => '4/nM2QAaunKUINb4RrXPC55F-mix_k',
+  :token_secret => '41r18IyXjIvuyabS/NDyW6+m'
+)
+messages_count = imap.status('INBOX', ['MESSAGES'])['MESSAGES']
+puts "Seeing #{messages_count} messages in INBOX"
+```
 
 Note that the [Net::IMAP#login](http://www.ruby-doc.org/core/classes/Net/IMAP.html#M004191) method does not use support custom authenticators, so you have to use the [Net::IMAP#authenticate](http://www.ruby-doc.org/core/classes/Net/IMAP.html#M004190) method.
 
-If you use 2-legged OAuth:
+### IMAP 2-legged OAuth 1.0a
 
-    require 'gmail_xoauth'
-    imap = Net::IMAP.new('imap.gmail.com', 993, usessl = true, certs = nil, verify = false)
-    imap.authenticate('XOAUTH', 'myemail@mydomain.com',
-      :two_legged => true,
-      :consumer_key => 'a',
-      :consumer_secret => 'b'
-    )
+```ruby
+require 'gmail_xoauth'
+imap = Net::IMAP.new('imap.gmail.com', 993, usessl = true, certs = nil, verify = false)
+imap.authenticate('XOAUTH', 'myemail@mydomain.com',
+  :two_legged => true,
+  :consumer_key => 'a',
+  :consumer_secret => 'b'
+)
+```
 
-### SMTP
+### SMTP 3-legged OAuth 1.0a
 
 For your tests, Gmail allows to set 'anonymous' as the consumer key and secret.
 
-    require 'gmail_xoauth'
-    smtp = Net::SMTP.new('smtp.gmail.com', 587)
-    smtp.enable_starttls_auto
-    secret = {
-      :consumer_key => 'anonymous',
-      :consumer_secret => 'anonymous',
-      :token => '4/nM2QAaunKUINb4RrXPC55F-mix_k',
-      :token_secret => '41r18IyXjIvuyabS/NDyW6+m'
-    }
-    smtp.start('gmail.com', 'myemail@gmail.com', secret, :xoauth)
-    smtp.finish
-
-Note that +Net::SMTP#enable_starttls_auto+ is not defined in Ruby 1.8.6.
-
-If you use 2-legged OAuth:
-
-    require 'gmail_xoauth'
-    smtp = Net::SMTP.new('smtp.gmail.com', 587)
-    smtp.enable_starttls_auto
-    secret = {
-    	:two_legged => true,
-      :consumer_key => 'a',
-      :consumer_secret => 'b'
-    }
-    smtp.start('gmail.com', 'myemail@mydomain.com', secret, :xoauth)
-    smtp.finish
-
+```ruby
+require 'gmail_xoauth'
+smtp = Net::SMTP.new('smtp.gmail.com', 587)
+smtp.enable_starttls_auto
+secret = {
+  :consumer_key => 'anonymous',
+  :consumer_secret => 'anonymous',
+  :token => '4/nM2QAaunKUINb4RrXPC55F-mix_k',
+  :token_secret => '41r18IyXjIvuyabS/NDyW6+m'
+}
+smtp.start('gmail.com', 'myemail@gmail.com', secret, :xoauth)
+smtp.finish
+```
+
+Note that `Net::SMTP#enable_starttls_auto` is not defined in Ruby 1.8.6.
+
+### SMTP 2-legged OAuth 1.0a
+
+```ruby
+require 'gmail_xoauth'
+smtp = Net::SMTP.new('smtp.gmail.com', 587)
+smtp.enable_starttls_auto
+secret = {
+	:two_legged => true,
+  :consumer_key => 'a',
+  :consumer_secret => 'b'
+}
+smtp.start('gmail.com', 'myemail@mydomain.com', secret, :xoauth)
+smtp.finish
+```
 
 ## Compatibility
 
-Tested on Ruby MRI 1.8.6, 1.8.7, 1.9.1 and 1.9.2. Feel free to send me a message if you tested this code with other implementations of Ruby.
+Tested on Ruby MRI 1.8.6, 1.8.7, 1.9.1, 1.9.2 and 1.9.3. Feel free to send me a message if you tested this code with other implementations of Ruby.
 
 The only external dependency is the [oauth gem](http://rubygems.org/gems/oauth).
 
 ## History
 
+* 0.4.1 Changed to way to give the OAuth 2.0 token, see https://github.com/nfo/gmail_xoauth/commit/b7b936cfb094c2fc9b8e9e48526906191423cb88
+* 0.4.0 [XOAUTH2](https://developers.google.com/google-apps/gmail/xoauth2_protocol) support, thanks to [glongman](https://github.com/glongman)
 * 0.3.2 New email for the maintainer
 * 0.3.1 2-legged OAuth support confirmed by [BobDohnal](https://github.com/BobDohnal)
-* 0.3.0 Experimental 2-legged OAuth support
+* 0.3.0 Experimental 2-legged OAuth support, thanks to [wojciech](https://github.com/wojciech)
 * 0.2.0 SMTP support
 * 0.1.0 Initial release with IMAP support and 3-legged OAuth
 
@@ -107,6 +146,6 @@ The only external dependency is the [oauth gem](http://rubygems.org/gems/oauth).
 
 http://about.me/nfo
 
-## Copyright
+## License
 
-Copyright (c) 2011 Silentale SAS. See LICENSE for details.
+See LICENSE for details.

data/lib/gmail_xoauth.rb

@@ -1,3 +1,5 @@
 require 'gmail_xoauth/oauth_string'
 require 'gmail_xoauth/imap_xoauth_authenticator'
+require 'gmail_xoauth/imap_xoauth2_authenticator'
 require 'gmail_xoauth/smtp_xoauth_authenticator'
+require 'gmail_xoauth/smtp_xoauth2_authenticator'

data/lib/gmail_xoauth/imap_xoauth2_authenticator.rb

@@ -0,0 +1,24 @@
+require 'net/imap'
+
+module GmailXoauth
+  class ImapXoauth2Authenticator
+    
+    def process(data)
+      build_oauth2_string(@user, @oauth2_token)
+    end
+    
+  private
+    
+    # +user+ is an email address: roger@gmail.com
+    # +oauth2_token+ is the OAuth2 token
+    def initialize(user, oauth2_token)
+      @user = user
+      @oauth2_token = oauth2_token
+    end
+    
+    include OauthString
+    
+  end
+end
+
+Net::IMAP.add_authenticator('XOAUTH2', GmailXoauth::ImapXoauth2Authenticator)

data/lib/gmail_xoauth/oauth_string.rb

@@ -4,7 +4,7 @@ module GmailXoauth
   private
     
     #
-    # Builds the "oauth protocol parameter string". See http://code.google.com/apis/gmail/oauth/protocol.html#sasl
+    # Builds the "oauth protocol parameter string". See https://developers.google.com/google-apps/gmail/oauth_protocol#sasl_initial_client_request
     # 
     #   +request_url+ https://mail.google.com/mail/b/user_name@gmail.com/{imap|smtp}/
     #   +oauth_params+ contains the following keys:
@@ -45,10 +45,19 @@ module GmailXoauth
       oauth_request_params.map { |k,v| "#{k}=\"#{OAuth::Helper.escape(v)}\"" }.sort.join(',')
     end
 
-    # See http://code.google.com/apis/gmail/oauth/protocol.html#sasl
+    # See https://developers.google.com/google-apps/gmail/oauth_protocol#sasl_initial_client_request
     def build_sasl_client_request(request_url, oauth_string)
       'GET ' + request_url + ' ' + oauth_string
     end
+
+    #
+    # Builds the "oauth2 protocol authentication string". See https://developers.google.com/google-apps/gmail/xoauth2_protocol
+    # 
+    #   +user+ is an email address: roger@gmail.com
+    #   +oauth2_token+ is the oauth2 token
+    def build_oauth2_string(user, oauth2_token)
+      "user=%s\1auth=Bearer %s\1\1".encode("us-ascii") % [user, oauth2_token]
+    end
     
   end
 end

data/lib/gmail_xoauth/smtp_xoauth2_authenticator.rb

@@ -0,0 +1,25 @@
+require 'net/smtp'
+require 'base64'
+
+module GmailXoauth
+  module SmtpXoauth2Authenticator
+    
+    def auth_xoauth2(user, oauth2_token)
+      check_auth_args user, oauth2_token
+
+      auth_string = build_oauth2_string(user, oauth2_token)
+      res = critical {
+        get_response("AUTH XOAUTH2 #{base64_encode(auth_string)}")
+      }
+      
+      check_auth_response res
+      res
+    end
+    
+    include OauthString
+    
+  end
+end
+
+# Not pretty, right ?
+Net::SMTP.__send__('include', GmailXoauth::SmtpXoauth2Authenticator)

data/lib/gmail_xoauth/version.rb

@@ -1,3 +1,3 @@
 module GmailXoauth
-  VERSION = "0.3.2"
+  VERSION = "0.4.1"
 end

data/test/helper.rb

@@ -26,7 +26,8 @@ VALID_CREDENTIALS = begin
 rescue Errno::ENOENT
   STDERR.puts %(
 Warning: some tests are disabled because they require valid credentials. To enable them, create a file \"test/valid_credentials.yml\".
-It should contain valid OAuth tokens. Valid tokens can be generated thanks to \"xoauth.py\":http://code.google.com/p/google-mail-xoauth-tools/.
+It should contain valid OAuth tokens. Valid tokens oauth tokens can be generated thanks to \"xoauth.py\":http://code.google.com/p/google-mail-xoauth-tools/.
+It should also ontain a valid OAuth2 access token. Valid tokens oauth2 tokens can be generated thanks to \"oauth2.py\":http://code.google.com/p/google-mail-oauth2-tools//. Note that oauth2 access tokens are time limited (an hour in my experience).
 Of course, this file is .gitignored. Template:
 
 ---
@@ -35,6 +36,7 @@ Of course, this file is .gitignored. Template:
 :consumer_secret: anonymous # "anonymous" is a valid value for testing
 :token: 1/nE2xBCDOU0429bTeJySE11kRE95qzKQNlfTaaBcDeFg
 :token_secret: 123Z/bMsi9fFhN6qHFWOabcd
+:oauth2_token: ya29.AHES6ZTIpsLuSyMwnh-3C40WWcuiOe4N7he0a8xnkvDk_6Q_6yUg7E
 
 )
   false

data/test/test_imap_xoauth2_authenticator.rb

@@ -0,0 +1,32 @@
+require 'helper'
+
+class TestImapXoauth2Authenticator < Test::Unit::TestCase
+  
+  def setup
+  end
+  
+  def test_xoauth2_authenticator_is_enabled
+    authenticators = Net::IMAP.__send__('class_variable_get', '@@authenticators')
+    assert_not_nil authenticators['XOAUTH2']
+    assert_equal authenticators['XOAUTH2'], GmailXoauth::ImapXoauth2Authenticator
+  end
+  
+  def test_authenticate_with_invalid_credentials
+    imap = Net::IMAP.new('imap.gmail.com', 993, usessl = true, certs = nil, verify = false)
+    assert_raise(Net::IMAP::NoResponseError) do
+      imap.authenticate('XOAUTH2', 'roger@moore.com', 'a')
+    end
+  end
+  
+  def test_authenticate_with_valid_credentials
+    return unless VALID_CREDENTIALS
+    
+    imap = Net::IMAP.new('imap.gmail.com', 993, usessl = true, certs = nil, verify = false)
+    imap.authenticate('XOAUTH2', VALID_CREDENTIALS[:email], VALID_CREDENTIALS[:oauth2_token])
+    mailboxes = imap.list('', '*')
+    assert_instance_of Array, mailboxes
+    assert_instance_of Net::IMAP::MailboxList, mailboxes.first
+  ensure
+    imap.disconnect if imap
+  end
+end

data/test/test_smtp_xoauth2_authenticator.rb

@@ -0,0 +1,32 @@
+require 'helper'
+
+class TestSmtpXoauthAuthenticator < Test::Unit::TestCase
+  
+  def setup
+  end
+  
+  def test_smtp_authenticator_is_enabled
+    assert Net::SMTP.new(nil).respond_to?(:auth_xoauth2), 'The Net::SMTP class should define the method :auth_xoauth2'
+  end
+  
+  def test_authenticate_with_invalid_credentials
+    smtp = Net::SMTP.new('smtp.gmail.com', 587)
+    smtp.enable_starttls_auto
+    assert_raise(Net::SMTPAuthenticationError) do
+      smtp.start('gmail.com', 'roger@moore.com', 'a', :xoauth2)
+    end
+  end
+  
+  def test_authenticate_with_valid_credentials
+    return unless VALID_CREDENTIALS
+    
+    smtp = Net::SMTP.new('smtp.gmail.com', 587)
+    smtp.enable_starttls_auto
+    
+    assert_nothing_raised do
+      smtp.start('gmail.com', VALID_CREDENTIALS[:email], VALID_CREDENTIALS[:oauth2_token], :xoauth2)
+    end
+  ensure
+    smtp.finish if smtp && smtp.started?
+  end
+end

data/test/test_smtp_xoauth_authenticator.rb

@@ -34,7 +34,7 @@ class TestSmtpXoauthAuthenticator < Test::Unit::TestCase
       smtp.start('gmail.com', VALID_CREDENTIALS[:email], secret, :xoauth)
     end
   ensure
-    smtp.finish if smtp.started?
+    smtp.finish if smtp && smtp.started?
   end
 
   def test_2_legged_authenticate_with_invalid_credentials
@@ -61,6 +61,6 @@ class TestSmtpXoauthAuthenticator < Test::Unit::TestCase
       smtp.start('gmail.com', VALID_CREDENTIALS[:email], secret, :xoauth)
     end
   ensure
-    smtp.finish if smtp.started?
+    smtp.finish if smtp && smtp.started?
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gmail_xoauth
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.4.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-04-16 00:00:00.000000000 Z
+date: 2012-09-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: oauth
@@ -51,14 +51,18 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- lib/gmail_xoauth/imap_xoauth2_authenticator.rb
 - lib/gmail_xoauth/imap_xoauth_authenticator.rb
 - lib/gmail_xoauth/oauth_string.rb
+- lib/gmail_xoauth/smtp_xoauth2_authenticator.rb
 - lib/gmail_xoauth/smtp_xoauth_authenticator.rb
 - lib/gmail_xoauth/version.rb
 - lib/gmail_xoauth.rb
 - test/helper.rb
+- test/test_imap_xoauth2_authenticator.rb
 - test/test_imap_xoauth_authenticator.rb
 - test/test_oauth_string.rb
+- test/test_smtp_xoauth2_authenticator.rb
 - test/test_smtp_xoauth_authenticator.rb
 - LICENSE
 - README.markdown
@@ -83,7 +87,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: 1.3.6
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.21
+rubygems_version: 1.8.23
 signing_key: 
 specification_version: 3
 summary: Get access to Gmail IMAP and STMP via OAuth, using the standard Ruby Net