README.rdoc in vidibus-oauth2_server-0.0.2 vs README.rdoc in vidibus-oauth2_server-0.0.3

@@ -1,10 +1,10 @@
-= vidibus-oauth2_server
+= Vidibus::Oauth2Server
 
-Allows OAuth2 authentication based on http://tools.ietf.org/html/draft-ietf-oauth2-v2-00.
+Allows OAuth2 authentication for Rails applications based on http://tools.ietf.org/html/draft-ietf-oauth2-v2-00.
 
-This gem is part of the open source SOA framework Vidibus: http://vidibus.org.
+This gem is part of the open source SOA framework {Vidibus}[http://vidibus.org].
 
 It is far from being complete and stable! But this will change soon.
 
 
 == Installation
@@ -13,50 +13,59 @@
 
   gem "vidibus-oauth2_server"
 
 Then call bundle install on your console.
 
+To get your own OAuth2 server working, some small adjustments will have to be made to your Rails application:
 
-=== Routes
 
-Two routes will be added to your application. If you use a catch-all route, you will have to define these routes manually:
+=== Client model
 
-  get "oauth/authorize" => "oauth2#authorize"
-  post "oauth/access_token" => "oauth2#access_token"
+Each remote application that requests authentication has to be authorized to do this. Usually, such an application will have to provide an API key that will be validated against a local repository. For OAuth2 this API key is called "client_id".
 
+Additionally, each client application has to provide a password to make a valid Oauth2 request, the "client_secret".
 
-=== ApplicationController
+This gem will validate an incoming OAuth2 request against client_id and client_secret parameters. Thus your client model has to provide both attributes, although they don't have to be named like this.
 
-In ApplicationController of your OAuth server application you have to define two methods in order to perform OAuth authentication.
+You'll also have to provide a #domain method on your OAuth client model that returns the domain name of the client, e.g. vidibus.org. This method is used to validate the redirect_url parameter.
 
-The first method performs a sign in of the current user. If you use Devise for authentication, this method already exists and works. This is an example that works with Authlogic:
+Before issuing a token, the Oauth2Controller will ensure that the given client_secret is valid. In order to perform this validation, a method #valid_oauth2_secret? must be given on your client model.
 
-  # Calls authentication method.
-  def authenticate_user!
-    logged_in? or login_required
-  end
+If you use the {Vidibus::Service}[https://github.com/vidibus/vidibus-service] gem, you'll get this method on the service model:
 
-The second method returns a client object with given id. This is an example for usage with vidibus-service gem:
-
-  # Returns Service with given id.
-  # This method is called from Vidibus' OauthServer gem.
-  # The given client_id comprises the requesting service's
-  # uuid and realm, concatenated by -
-  def oauth2_client(client_id)
-    Service(*client_id.split("-"))
+  # Returns true if given client_secret matches signature.
+  def valid_oauth2_secret?(client_secret)
+    client_secret == Vidibus::Secure.sign("#{Service.this.url}#{uuid}", secret)
   end
 
 
 === User model
 
-Your user model has to provide an unique UUID. If you use Mongoid, add the following:
+Your user model has to provide an unique UUID in compact format. If you use Mongoid, you may include the UUID generator provided by the {Vidibus::Uuid}[https://github.com/vidibus/vidibus-uuid] gem:
 
-  field :uuid
+  class User
+    include Mongoid::Document
+    include Vidibus::Uuid::Mongoid
+    ...
+  end
 
-If you have an ActiveRecord model, add a migration like this:
+If you have an ActiveRecord model, implement something like this:
 
   require "uuid"
+  class User < ActiveRecord::Base
+    before_create :generate_uuid
+    ...
+    protected
+
+    def generate_uuid
+      self.uuid ||= UUID.new.generate(:compact)
+    end
+  end
+
+And don't forget the migration:
+
+  require "uuid"
   class AddUuidToUsers < ActiveRecord::Migration
     def self.up
       add_column :users, :uuid, :string, :null => false
       add_index :users, :uuid
       User.all.each do |user|
@@ -69,14 +78,49 @@
       remove_column :users, :uuid
     end
   end
 
 
-=== User controller
+=== Routes
 
-This gem will an action to obtain data of the currently logged in user. The following route will be added:
+Two routes will be added to your Rails application. If you use a catch-all route, you will have to define these routes manually:
 
+  get "oauth/authorize" => "oauth2#authorize"
+  post "oauth/access_token" => "oauth2#access_token"
+
+
+=== ApplicationController
+
+In the ApplicationController of your OAuth server application you'll have to define two methods in order to perform OAuth authentication.
+
+The first method performs the sign-in of the current user. If you use Devise for authentication with a "User" model, that method already exists and works. This is an example that works with Authlogic:
+
+  # Calls authentication method.
+  def authenticate_user!
+    logged_in? or login_required
+  end
+
+The second method returns a service client with given id. This is an example taken from the {Vidibus::Service}[https://github.com/vidibus/vidibus-service] gem:
+
+  # Returns service matching given client_id.
+  # This method is called from Vidibus' Oauth2Server gem.
+  #
+  # In this example from Vidibus the given client_id
+  # comprises the requesting service's uuid and realm,
+  # concatenated by -.
+  #
+  # Adjust this method to your needs.
+  #
+  def oauth2_client(client_id)
+    Service(*client_id.split("-"))
+  end
+
+
+=== Oauth2::UsersController
+
+This gem will also provide an action to obtain data of the user currently logged in. The following route will be added:
+
   get "/oauth/user" => "oauth2/users#show"
 
 You may overwrite the Oauth2::UsersController class to adjust it to your needs. However, if you want to use the default controller, you'll need a method on your ApplicationController to obtain a user by a given UUID.
 
 For a typical ActiveRecord model this would be:
@@ -84,34 +128,25 @@
   # Returns user matching given uuid
   def find_user_by_uuid(uuid)
     User.first(:conditions => {:uuid => uuid})
   end
 
-The default #show method delivers a JSON string including name, email and UUID of the current user:
+The default #show method of this controller delivers a JSON string including name, email and UUID of the current user:
 
   def show
     render :json => @user.attributes.only(*%w[name email uuid])
   end
 
+== And the client side?
 
-=== Client model
+Well, this is just the server side of the story. To implement OAuth2 on your client applications, there are many solutions available. The basic tools are provided by the excellent {OAuth2}[https://github.com/intridea/oauth2] gem. For a sophisticated example, check out {OmniAuth}[https://github.com/intridea/omniauth].
 
-Provide a #domain method to your OAuth client model that returns the domain name of the client. This method is used to validate the redirect_url.
+In a typical Vidibus service-oriented environment, clients are equipped with the {Vidibus::User}[https://github.com/vidibus/vidibus-user] gem.
 
-Before issuing a token, the Oauth2Controller will ensure that the given client_secret is valid. In order to perform this validation, a method #valid_oauth2_secret? must be given on your client model.
 
-If you use the vidibus-service gem, you'll get this method on the service model:
-
-  # Returns true if given client_secret matches signature.
-  def valid_oauth2_secret?(client_secret)
-    client_secret == Vidibus::Secure.sign("#{Service.this.url}#{uuid}", secret)
-  end
-
-
 == TODO
 
 * Write specs!
-* Explain usage and integration
 * Implement token expiry
 * Apply changes made in http://tools.ietf.org/html/draft-ietf-oauth2-v2-10?
 
 
 == Copyright