oauth_provider 0.1.0

data/README

@@ -0,0 +1,151 @@
+--------------------------------------------------------------------------------
+- OAuth Provider library in Ruby
+--------------------------------------------------------------------------------
+
+--------------------------------------------------------------------------------
+- 1) Getting the library setup
+- 2) Creating a provider
+- 3) Adding a consumer
+- 4) Issuing a request token
+- 5) Authorizing a request token
+- 6) Upgrading a request token to an access token
+- 7) Confirming access for an access token
+--------------------------------------------------------------------------------
+
+--------------------------------------------------------------------------------
+- 1) Getting the library setup
+--------------------------------------------------------------------------------
+
+You can currently only download the source and build a gem. 
+It will be put on rubyforge once it is more feature-some. 
+
+# git clone git://github.com/halorgium/oauth_provider.git
+# rake package
+
+--------------------------------------------------------------------------------
+- 2) Getting the library setup
+--------------------------------------------------------------------------------
+
+Create a provider to allow you to interact issue request tokens etc. 
+There are several backends to allow you to use this for real and in testing. 
+
+The in-memory backend is best for testing, it allows you to not have the 
+overhead of a database. 
+
+# provider = OAuthProvider.create(:in_memory)
+
+The DataMapper backend is currently the only real backend, you can provide a 
+repository which will allow you to use a different database connection. 
+
+# provider = OAuthProvider.create(:data_mapper, :some_oauth_repository)
+
+--------------------------------------------------------------------------------
+- 3) Adding a consumer
+--------------------------------------------------------------------------------
+
+To add a consumer to the provider, you need to provide a callback URL. 
+
+# consumer = provider.add_consumer("http://myconsumer.com/token")
+
+You should store the consumer shared key in your database so you can associate 
+your users with the tokens they own. 
+
+# Consumer.create("My Consumer", consumer.shared_key)
+
+--------------------------------------------------------------------------------
+- 4) Issuing a request token
+--------------------------------------------------------------------------------
+
+Now you can issue a request token, this will save the token for later access. 
+You need to pass in the raw request object which your web framework uses and 
+require the correct request-proxy. 
+
+Rails (ActionController): 
+# require 'oauth/request_proxy/action_controller_request'
+XMPP4R: 
+# require 'oauth/request_proxy/jabber_request'
+Net::HTTP: 
+# require 'oauth/request_proxy/net_http'
+Sinatra/Merb (Rack): 
+# require 'oauth/request_proxy/rack_request'
+
+Once that file is required, you can ask the provider to issue a token. 
+
+# user_request = provider.issue_request(request)
+
+You should save this token in your database to connect this token with a 
+particular user. 
+
+# current_user.tokens.create(:consumer_shared_key => user_request.consumer.shared_key,
+#                                 :shared_key => user_request.shared_key)
+
+This object allows you to access the query_string which should be returned 
+to the consumer. 
+This is the form: oauth_token=ABCDE&oauth_token_secret=SECRET123
+
+# user_request.query_string
+
+Now it is up to the consumer to redirect the user to your authorization 
+screen. To locate the token which corresponds with the shared key (usually 
+the 'oauth_token' parameter in the request) you need to 
+
+--------------------------------------------------------------------------------
+- 5) Authorizing a request token
+--------------------------------------------------------------------------------
+
+Once you have determined that the user wishes to authorize the request. You 
+should display the consumer information to the user. 
+
+An example ERB view might be: 
+
+# <p>You are about to authorize <%= token.consumer.name %> to access your account %></p>
+# <p>Do you want this to happen?</p>
+# <p><a href="/authorize?oauth_token=<%= token.shared_key %>Authorize it</a>
+
+At this point, you can also store any access control information to allow this 
+consumer to perhaps only have read-access to the user's information. 
+
+Then in the 'authorize' action you would tell the provider to authorize this 
+request token and redirect back to the consumer callback URL. 
+
+# user_request.authorize
+# redirect_to user_request.callback
+
+--------------------------------------------------------------------------------
+- 6) Upgrading a request token to an access token
+--------------------------------------------------------------------------------
+
+Now that the request token is authorized by the user, the consumer can upgrade 
+this token to an access token. 
+
+# user_access = provider.upgrade_request(request)
+
+If the request token is not yet authorized, an exception will be raised. The 
+exception class is 'OAuthProvider::UserRequestNotAuthorized'. 
+
+If the request token is authorized, the request token will be destroyed and 
+a access token will be generated and returned. 
+
+Now you can save this into your database. 
+
+# token = current_user.tokens.find_by_shared_key(user_access.request_shared_key)
+# token.update_attributes(:access => true, :shared_key => user_access.shared_key)
+
+And return the query string back to the consumer
+
+# user_access.query_string
+
+--------------------------------------------------------------------------------
+- 7) Confirming access for an access token
+--------------------------------------------------------------------------------
+
+At this point, the consumer should have a valid access token and can make API 
+requests. You can ask the provider to confirm that the access token is valid. 
+
+# user_access = provider.confirm_access(request)
+
+Now you can find the user token which corresponds to the shared_key. 
+
+# token = current_user.tokens.first(:access => true, :shared_key => user_access.shared_key)
+
+You are now ready to respond to the API request as needed!

data/lib/oauth_provider.rb

@@ -0,0 +1,52 @@
+require 'oauth'
+require 'oauth/server'
+require 'oauth/signature'
+
+module OAuthProvider
+  class Error < StandardError; end
+  class NotImplemented < Error; end
+  class ConsumerNotFound < Error
+    def initialize(shared_key)
+      super("No Consumer with shared key: #{shared_key.inspect}")
+    end
+  end
+  class UserRequestNotFound < Error
+    def initialize(shared_key)
+      super("No User Request with shared key: #{shared_key.inspect}")
+    end
+  end
+  class UserAccessNotFound < Error
+    def initialize(shared_key)
+      super("No User Access with shared key: #{shared_key.inspect}")
+    end
+  end
+  class UserRequestNotAuthorized < Error
+    def initialize(user_request)
+      super("The User Request is not yet authorized by the User: #{user_request.shared_key.inspect}")
+    end
+  end
+  class VerficationFailed < Error; end
+  class IncompleteToken < Error; end
+
+  class DuplicateCallback < Error
+    def initialize(consumer)
+      super("The callback #{consumer.callback.inspect} is already used by another consumer")
+    end
+  end
+
+  def self.create(backend_type, *args)
+    Backends.for(backend_type, *args).provider
+  end
+end
+
+$:.unshift File.dirname(__FILE__)
+
+require 'oauth_provider/fixes'
+require 'oauth_provider/token'
+require 'oauth_provider/provider'
+require 'oauth_provider/consumer'
+require 'oauth_provider/user_request'
+require 'oauth_provider/user_access'
+
+require 'oauth_provider/backends'
+require 'oauth_provider/backends/abstract'

data/lib/oauth_provider/backends.rb

@@ -0,0 +1,9 @@
+module OAuthProvider
+  module Backends
+    def self.for(type, *args)
+      require "oauth_provider/backends/#{type}"
+      klass_name = type.to_s.split('_').map {|e| e.capitalize}.join
+      const_get(klass_name).new(*args)
+    end
+  end
+end

data/lib/oauth_provider/backends/abstract.rb

@@ -0,0 +1,75 @@
+module OAuthProvider
+  module Backends
+    class Abstract
+      def provider
+        @provider ||= Provider.new(self)
+      end
+
+      def add_consumer(provider, callback, token)
+        consumer = Consumer.new(self, provider, callback, token)
+        create_consumer(consumer)
+        consumer
+      end
+
+      def create_consumer(consumer)
+        raise NotImplemented, "Implement #create_consumer in #{self.class}"
+      end
+      protected :create_consumer
+
+      def find_consumer(shared_key)
+        raise NotImplemented, "Implement #find_consumer in #{self.class}"
+      end
+
+      def save_consumer(shared_key)
+        raise NotImplemented, "Implement #save_consumer in #{self.class}"
+      end
+
+      def destroy_consumer(shared_key)
+        raise NotImplemented, "Implement #destroy_consumer in #{self.class}"
+      end
+
+      def add_user_request(consumer, authorized, token)
+        user_request = UserRequest.new(self, consumer, authorized, token)
+        create_user_request(user_request)
+        user_request
+      end
+
+      def create_user_request(user_request)
+        raise NotImplemented, "Implement #create_user_request in #{self.class}"
+      end
+      protected :create_user_request
+
+      def find_user_request(shared_key)
+        raise NotImplemented, "Implement #find_user_request in #{self.class}"
+      end
+
+      def save_user_request(user_request)
+        raise NotImplemented, "Implement #save_user_request in #{self.class}"
+      end
+
+      def destroy_user_request(user_request)
+        raise NotImplemented, "Implement #destroy_user_request in #{self.class}"
+      end
+
+      def add_user_access(user_request, token)
+        user_access = UserAccess.new(self, user_request.consumer, user_request.shared_key, token)
+        create_user_access(user_access)
+        destroy_user_request(user_request)
+        user_access
+      end
+
+      def create_user_access(user_access)
+        raise NotImplemented, "Implement #create_user_access in #{self.class}"
+      end
+      protected :create_user_access
+
+      def find_user_access(shared_key)
+        raise NotImplemented, "Implement #find_user_access in #{self.class}"
+      end
+
+      def destroy_user_access(user_access)
+        raise NotImplemented, "Implement #destroy_user_access in #{self.class}"
+      end
+    end
+  end
+end

data/lib/oauth_provider/backends/data_mapper.rb

@@ -0,0 +1,115 @@
+require 'dm-core'
+require 'dm-validations'
+
+module OAuthProvider
+  module Backends
+    class DataMapper < Abstract
+      def initialize(repository = :default)
+        @repository = repository
+      end
+
+      def consumers
+        with_repository do
+          Consumer.all.map do |c|
+            c.to_oauth(self)
+          end
+        end
+      end
+
+      def create_consumer(consumer)
+        with_repository do
+          raise DuplicateCallback.new(consumer) if Consumer.first(:callback => consumer.callback)
+          model = Consumer.new(:callback => consumer.callback,
+                               :shared_key => consumer.shared_key,
+                               :secret_key => consumer.secret_key)
+          model.save || raise("Failed to create Consumer: #{model.inspect}, #{model.errors.inspect}")
+        end
+      end
+
+      def find_consumer(shared_key)
+        consumer = consumer_for(shared_key)
+        consumer && consumer.to_oauth(self)
+      end
+
+      def destroy_consumer(consumer)
+        consumer = consumer_for(consumer.shared_key)
+        consumer && consumer.destroy
+      end
+
+      def create_user_request(user_request)
+        with_repository do
+          if consumer = consumer_for(user_request.consumer.shared_key)
+            consumer.user_requests.create(:shared_key => user_request.shared_key,
+                                          :secret_key => user_request.secret_key,
+                                          :authorized => user_request.authorized?)
+          end
+        end
+      end
+
+      def find_user_request(shared_key)
+        user_request = user_request_for(shared_key)
+        user_request && user_request.to_oauth(self)
+      end
+
+      def save_user_request(user_request)
+        if model = user_request_for(user_request.shared_key)
+          model.authorized = user_request.authorized?
+          model.save || raise("Failed to save UserRequest: #{user_request.shared_key}, #{model.errors.inspect}")
+        end
+      end
+
+      def destroy_user_request(user_request)
+        user_request = user_request_for(user_request.shared_key)
+        user_request && user_request.destroy
+      end
+
+      def create_user_access(user_access)
+        with_repository do
+          if consumer = consumer_for(user_access.consumer.shared_key)
+            u = consumer.user_accesses.create(:request_shared_key => user_access.request_shared_key,
+                                              :shared_key => user_access.shared_key,
+                                              :secret_key => user_access.secret_key)
+          else
+            raise ConsumerNotFound.new(user_access.consumer.shared_key)
+          end
+        end
+      end
+
+      def find_user_access(shared_key)
+        with_repository do
+          user_access = UserAccess.first(:shared_key => shared_key)
+          user_access && user_access.to_oauth(self)
+        end
+      end
+
+      private
+      def with_repository(&block)
+        ::DataMapper.repository(@repository) do
+          yield
+        end
+      end
+
+      def consumer_for(shared_key)
+        with_repository do
+          Consumer.first(:shared_key => shared_key)
+        end
+      end
+
+      def user_request_for(shared_key)
+        with_repository do
+          UserRequest.first(:shared_key => shared_key)
+        end
+      end
+
+      def user_access_for(shared_key)
+        with_repository do
+          UserAccess.first(:shared_key => shared_key)
+        end
+      end
+    end
+  end
+end
+
+require 'oauth_provider/backends/data_mapper/consumer'
+require 'oauth_provider/backends/data_mapper/user_request'
+require 'oauth_provider/backends/data_mapper/user_access'

data/lib/oauth_provider/backends/data_mapper/consumer.rb

@@ -0,0 +1,25 @@
+module OAuthProvider
+  module Backends
+    class DataMapper
+      class Consumer
+        include ::DataMapper::Resource
+
+        property :id, Serial
+        property :callback, String, :unique => true, :nullable => false
+        property :shared_key, String, :unique => true, :nullable => false
+        property :secret_key, String, :unique => true, :nullable => false
+
+        has n, :user_requests, :class_name => '::OAuthProvider::Backends::DataMapper::UserRequest'
+        has n, :user_accesses, :class_name => '::OAuthProvider::Backends::DataMapper::UserAccess'
+
+        def token
+          OAuthProvider::Token.new(shared_key, secret_key)
+        end
+
+        def to_oauth(backend)
+          OAuthProvider::Consumer.new(backend, backend.provider, callback, token)
+        end
+      end
+    end
+  end
+end

data/lib/oauth_provider/backends/data_mapper/user_access.rb

@@ -0,0 +1,25 @@
+module OAuthProvider
+  module Backends
+    class DataMapper
+      class UserAccess
+        include ::DataMapper::Resource
+
+        property :id, Serial
+        property :consumer_id, Integer, :nullable => false
+        property :request_shared_key, String, :nullable => false
+        property :shared_key, String, :unique => true, :nullable => false
+        property :secret_key, String, :unique => true, :nullable => false
+
+        belongs_to :consumer , :class_name => '::OAuthProvider::Backends::DataMapper::Consumer'
+
+        def token
+          OAuthProvider::Token.new(shared_key, secret_key)
+        end
+
+        def to_oauth(backend)
+          OAuthProvider::UserAccess.new(backend, consumer.to_oauth(backend), request_shared_key, token)
+        end
+      end
+    end
+  end
+end