oauth2-provider-jonrowe 0.1.0

data/README.rdoc

@@ -0,0 +1,314 @@
+= OAuth2::Provider
+
+This gem provides a toolkit for adding OAuth2 provider capabilities to a Ruby
+web app. It handles most of the protocol for you: it is designed to provide
+a sufficient level of abstraction that it can implement updates to the protocol
+without affecting your application code at all. All you have to deal with is
+authenticating your users and letting them grant access to client apps.
+
+It is also designed to be usable within any web frontend, at least those of
+Rails and Sinatra. It assumes very little about the request objects in your
+environment, namely they:
+
+* respond to <tt>#params</tt> with a <tt>Hash</tt> of request parameters
+* respond to <tt>#get?</tt> and <tt>#post?</tt>
+* respond to <tt>#url</tt> with the full URL string of the request
+* respond to <tt>#env</tt>, returning the HTTP environment <tt>Hash</tt>
+
+It stores the clients and authorizations using ActiveRecord; the schema is in
+<tt>lib/oauth2/model/schema.rb</tt>. Run it to update your database to
+store OAuth data:
+
+  OAuth2::Model::Schema.up
+
+The current imeplementation is based on draft-10[http://tools.ietf.org/html/draft-ietf-oauth-v2-10].
+
+
+== Usage
+
+A basic example is in <tt>example/application.rb</tt>. To implement OAuth, you
+need to provide four things:
+
+* Some UI to register client applications
+* The OAuth request endpoint
+* A flow for logged-in users to grant access to clients
+* Resources protected by access tokens
+
+
+=== Configuration
+
+<tt>OAuth2::Provider</tt> requires very little configuration. The only thing it
+needs to know about your app is its name, which is used in the headers for some
+authentication errors. To load the library, just do this:
+
+  require 'oauth2/provider'
+  OAuth2::Provider.realm = 'My OAuth app'
+
+You may also need to configure assertion handlers if your application supports
+third-party access credentials. See 'Using Assertions' below.
+
+
+=== Registering client applications
+
+Clients are modelled by the <tt>OAuth2::Model::Client</tt> class, which is an
+ActiveRecord model. You just need to implement a UI for creating them, for
+example in a Sinatra app:
+
+  get '/oauth/apps/new' do
+    @client = OAuth2::Model::Client.new
+    erb :new_client
+  end
+
+  post '/oauth/apps' do
+    @client = OAuth2::Model::Client.new(params)
+    @client.save ? erb(:show_client) : erb(:new_client)
+  end
+
+Client applications must have a <tt>name</tt> and a <tt>redirect_uri</tt>:
+provide fields for editing these but do not allow the other fields to be edited,
+since they are the client's access credentials. When you've created the client,
+you should show its details to the user registering the client: its <tt>name</tt>,
+<tt>redirect_uri</tt>, <tt>client_id</tt> and <tt>client_secret</tt> (the last
+two are generated for you). <tt>client_secret</tt> is not stored in plain text
+so you can only read it when you initially create the client object.
+
+
+=== OAuth request endpoint
+
+This is a path that your application exposes in order for clients to communicate
+with your application. It is also the page that the client will send users to
+so they can authenticate and grant access. Many requests to this endpoint will
+be protocol-level requests that do not involve the user, and <tt>OAuth2::Provider</tt>
+gives you a generic way to handle all that.
+
+You should use this to get the right response, status code and headers to send to
+the client. In the event that <tt>OAuth2::Provider</tt> does not provide a response,
+you should render a page that lets the user begin to authenticate and grant access.
+
+This endpoint must be accessible via GET and POST. In this example we will expose
+the OAuth service through the path <tt>/oauth/authorize</tt>. We check if there is
+a logged-in resource owner and give this to <tt>OAuth::Provider</tt>, since we
+may be able to immediately redirect if the user has already authorized the client:
+
+  [:get, :post].each do |method|
+    __send__ method, '/oauth/authorize' do
+      @owner  = User.find_by_id(session[:user_id])
+      @oauth2 = OAuth2::Provider.parse(@owner, request)
+      
+      redirect @oauth2.redirect_uri if @oauth2.redirect?
+          
+      headers @oauth2.response_headers
+      status  @oauth2.response_status
+      
+      @oauth2.response_body || erb(:login)
+    end
+  end
+
+There is a set of parameters that you will need to hold on to for when your app
+needs to redirect back to the client. You could store them in the session, or
+pass them through forms as the user completes the flow. For example to embed
+them in the login form, do this:
+
+  <% @oauth2.params.each do |key, value| %>
+    <input type="hidden" name="<%= key %>" value="<%= value %>">
+  <% end %>
+
+You may also want to use scopes to provide granular access to your domain using
+<i>scopes</i>. The <tt>@oauth2</tt> object exposes the scopes the client has asked
+for so you can display them to the user:
+
+  <p>The application <%= @oauth2.client.name %> wants the following permissions:</p>
+  
+  <ul>
+    <% @oauth2.scopes.each do |scope| %>
+      <li><%= PERMISSION_UI_STRINGS[scope] %></li>
+    <% end %>
+  </ul>
+
+You can also use the method <tt>@oauth2.unauthorized_scopes</tt> to get the list
+of scopes the user has not already granted to the client, in the case where the
+client already has some authorization. If no prior authorization exists between
+the user and the client, <tt>@oauth2.unauthorized_scopes</tt> just returns all
+the scopes the client has asked for.
+
+
+=== Granting access to clients
+
+Your application will probably have some concept of a user, or a <i>resource
+owner</i> in OAuth lingo. Add this mixin to the model that represents your
+users:
+
+  class User < ActiveRecord::Base
+    include OAuth2::Model::ResourceOwner
+  end
+
+This just adds a couple of relations and methods to the model to let it interact
+with the <tt>OAuth2</tt> models.
+
+Once the user has authenticated you should show them a page to let them grant
+or deny access to the client application. This is straightforward; let's say
+the user checks a box before posting a form to indicate their intent:
+
+  post '/oauth/allow' do
+    @user = User.find_by_id(session[:user_id])
+    @auth = OAuth2::Provider::Authorization.new(@user, params)
+    
+    if params['allow'] == '1'
+      @auth.grant_access!
+    else
+      @auth.deny_access!
+    end
+    redirect @auth.redirect_uri
+  end
+
+After granting or denying access, we just redirect back to the client using a
+URI that <tt>OAuth2::Provider</tt> will provide for you.
+
+
+=== Using password credentials
+
+If you like, OAuth lets you use a user's login credentials to authenticate with
+a provider. In this case the client application must request these credentials
+directly from the user and then post them to the exchange endpoint. On the
+provider side you can handle this using the <tt>handle_passwords</tt> and
+<tt>grant_access!</tt> API methods, for example:
+
+  OAuth2::Provider.handle_passwords do |client, username, password|
+    user = User.find_by_username(username)
+    if user.authenticate?(password)
+      user.grant_access!(client)
+    else
+      nil
+    end
+  end
+
+The block must return <tt>user.grant_access!(client)</tt> if you want to allow
+access, otherwise it should return <tt>nil</tt>.
+
+
+=== Using assertions
+
+Assertions provide a way to access your OAuth services using user credentials
+from another service. When using assertions, the user will not authenticate on
+your web site; the OAuth client will authenticate the user using some other
+framework and obtain a token, then exchange this token for an access token on
+your domain.
+
+For example, a client application may let a user authenticate using Facebook,
+so the application obtains a Facebook access token from the user. The client
+would then pass this token to your OAuth endpoint and exchange it for an
+access token from your site. You will typically create an account in your
+database to represent this, then have that new account grant access to the
+client.
+
+To use assertions, you must tell <tt>OAuth2::Provider</tt> how to handle
+assertions based on their type. An assertion type must be a valid URI. For
+the Facebook example we'd do the following. The block yields the <tt>Client</tt>
+object making the exchange request, and the value of the assertion, which in
+this example will be a Facebook access token.
+
+  OAuth2::Provider.handle_assertions 'https://graph.facebook.com/me' do |client, assertion|
+    facebook = URI.parse('https://graph.facebook.com/me?access_token=' + assertion)
+    response = Net::HTTP.get_response(facebook)
+    
+    user_data = JSON.parse(response.body)
+    account   = User.from_facebook_data(user_data)
+    
+    account.grant_access!(client)
+  end
+
+This code should run when your app boots, not during a request handler - think
+of it as configuration for <tt>OAuth2::Provider</tt>. The framework will invoke
+it when a client attempts to use assertions with your OAuth endpoint.
+
+The final call in your handler should be to <tt>grant_access!</tt>; this returns
+an <tt>Authorization</tt> object that the framework then uses to complete the
+response to the client. If you want to deny the request for whatever reason, the
+block must return <tt>nil</tt>. If a client tries to use an assertion type you
+have no handler for, the client will get an error response.
+
+
+=== Protecting resources with access tokens
+
+To protect the user's resources you need to check for access tokens. This is
+simple, for example a call to get a user's notes:
+
+  get '/user/:username/notes' do
+    user  = User.find_by_username(params[:username])
+    token = OAuth2::Provider.access_token(user, ['read_notes'], request)
+    
+    headers token.response_headers
+    status  token.response_status
+    
+    if token.valid?
+      JSON.unparse('notes' => user.notes)
+    else
+      JSON.unparse('error' => 'No notes for you!')
+    end
+  end
+
+<tt>OAuth2::Provider.access_token()</tt> takes a <tt>ResourceOwner</tt>, a list
+of scopes required to access the resource, and a request object. If the token
+was not granted for the required scopes, has expired or is simply invalid,
+headers and a status code are set to indicate this to the client. <tt>token.valid?</tt>
+is the call you should use to determine whether to server the request or not.
+
+It is also common to provide a dynamic resource for getting some basic data
+about a user by supplying their access token. This can be done by passing
+<tt>nil</tt> as the resource owner:
+
+  get '/me' do
+    token = OAuth2::Provider.access_token(nil, [], request)
+    if token.valid?
+      JSON.unparse('username' => token.owner.username)
+    else
+      JSON.unparse('error' => 'Keep out!')
+    end
+  end
+
+<tt>token.owner</tt> returns the <tt>ResourceOwner</tt> that issued the token.
+A token represents the fact that a single owner gave a single client a set of
+permissions.
+
+
+=== Transport security
+
+Your application should ensure that any endpoint that receives or returns OAuth
+data is only accessible over a secure transport such as the <tt>https:</tt>
+protocol. <tt>OAuth2::Provider</tt> can enforces this to make it easier to keep
+your users' data secure. If you want to enable these behaviours, set
+<tt>OAuth2::Provider.enforce_ssl = true</tt>.
+
+* The <tt>OAuth2::Provider.parse</tt> method will produce error responses and
+  will not process the incoming request unless the request was made using the
+  <tt>https:</tt> protocol.
+* An access token constructed using <tt>OAuth2::Provider.access_token</tt> will
+  return <tt>false</tt> for <tt>#valid?</tt> unless the request was made using the
+  <tt>https:</tt> protocol.
+* Any access token received over an insecure connection is immediately destroyed
+  to prevent eavesdroppers getting access to the user's resources. A client
+  making an insecure request will have to send the user through the authorization
+  process again to get a new token.
+
+
+== License
+
+Copyright (c) 2010-2011 Songkick.com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/example/README.rdoc

@@ -0,0 +1,11 @@
+= OAuth2::Provider example app
+
+To get up and running:
+
+  # in parent directory
+  bundle install
+  
+  cd example/
+  ruby schema.rb
+  rackup config.ru
+

data/example/application.rb

@@ -0,0 +1,151 @@
+dir = File.expand_path(File.dirname(__FILE__))
+require dir + '/environment'
+
+require 'sinatra'
+require 'json'
+
+set :static, true
+set :public, dir + '/public'
+set :views,  dir + '/views'
+enable :sessions
+
+PERMISSIONS = {
+  'read_notes' => 'Read all your notes'
+}
+
+ERROR_RESPONSE = JSON.unparse('error' => 'No soup for you!')
+
+get('/') { erb(:home) }
+
+
+get '/users/new' do
+  @user = User.new
+  erb :new_user
+end
+
+post '/users/create' do
+  @user = User.create(params)
+  if @user.save
+    erb :create_user
+  else
+    erb :new_user
+  end
+end
+
+#================================================================
+# Register applications
+
+get '/oauth/apps/new' do
+  @client = OAuth2::Model::Client.new
+  erb :new_client
+end
+
+post '/oauth/apps' do
+  @client = OAuth2::Model::Client.new(params)
+  if @client.save
+    session[:client_secret] = @client.client_secret
+    redirect("/oauth/apps/#{@client.id}")
+  else
+    erb :new_client
+  end
+end
+
+get '/oauth/apps/:id' do
+  @client = OAuth2::Model::Client.find_by_id(params[:id])
+  @client_secret = session[:client_secret]
+  erb :show_client
+end
+
+
+#================================================================
+# OAuth 2.0 flow
+
+# Initial request exmample:
+# /oauth/authorize?response_type=token&client_id=7uljxxdgsksmecn5cycvug46v&redirect_uri=http%3A%2F%2Fexample.com%2Fcb&scope=read_notes
+[:get, :post].each do |method|
+  __send__ method, '/oauth/authorize' do
+    @user = User.find_by_id(session[:user_id])
+    @oauth2 = OAuth2::Provider.parse(@user, request)
+    redirect @oauth2.redirect_uri if @oauth2.redirect?
+        
+    headers @oauth2.response_headers
+    status  @oauth2.response_status
+    
+    @oauth2.response_body || erb(:login)
+  end
+end
+
+post '/login' do
+  @user = User.find_by_username(params[:username])
+  @oauth2 = OAuth2::Provider.parse(@user, request)
+  session[:user_id] = @user.id
+  erb(@user ? :authorize : :login)
+end
+
+post '/oauth/allow' do
+  @user = User.find_by_id(session[:user_id])
+  @auth = OAuth2::Provider::Authorization.new(@user, params)
+  if params['allow'] == '1'
+    @auth.grant_access!
+  else
+    @auth.deny_access!
+  end
+  redirect @auth.redirect_uri
+end
+
+#================================================================
+# Domain API
+
+get '/me' do
+  authorization = OAuth2::Provider.access_token(nil, [], request)
+  headers authorization.response_headers
+  status  authorization.response_status
+  
+  if authorization.valid?
+    user = authorization.owner
+    JSON.unparse('username' => user.username)
+  else
+    ERROR_RESPONSE
+  end
+end
+
+get '/users/:username/notes' do
+  verify_access :read_notes do |user|
+    notes = user.notes.map do |n|
+      {:note_id => n.id, :url => "#{host}/users/#{user.username}/notes/#{n.id}"}
+    end
+    JSON.unparse(:notes => notes)
+  end
+end
+
+get '/users/:username/notes/:note_id' do
+  verify_access :read_notes do |user|
+    note = user.notes.find_by_id(params[:note_id])
+    note ? note.to_json : JSON.unparse(:error => 'No such note')
+  end
+end
+
+
+
+helpers do
+  #================================================================
+  # Check for OAuth access before rendering a resource
+  def verify_access(scope)
+    user  = User.find_by_username(params[:username])
+    token = OAuth2::Provider.access_token(user, [scope.to_s], request)
+    
+    headers token.response_headers
+    status  token.response_status
+    
+    return ERROR_RESPONSE unless token.valid?
+    
+    yield user
+  end
+  
+  #================================================================
+  # Return the full app domain
+  def host
+    request.scheme + '://' + request.host_with_port
+  end
+end
+