sinatra_auth_github 0.1.1 → 0.1.2

data/README.md

@@ -3,58 +3,56 @@ sinatra_auth_github
 
 A sinatra extension that provides oauth authentication to github.  Find out more about enabling your application at github's [oauth quickstart](http://gist.github.com/419219).
 
-To test it out on localhost set your callback url to 'http://localhost:9292/auth/github/callback'
+To test it out on localhost set your callback url to 'http://localhost:9393/auth/github/callback'
 
-There's an example app in [spec/app.rb](/atmos/sinatra_auth_github/blob/master/spec/app.rb).
+The gist of this project is to provide a few things easily:
+
+* authenticate a user against github's oauth service
+* provide an easy way to make API requests for the authenticated user
+* optionally restrict users to a specific github organization
+* optionally restrict users to a specific github team
+
+Installation
+============
 
-There's a slightly more deployment friendly version [href](http://gist.github.com/421704).
+    % gem install sinatra_auth_github
 
-The Extension in Action
-=======================
+Running the Example
+===================
     % gem install bundler
     % bundle install
-    % GITHUB_CLIENT_ID="<from GH>" GITHUB_CLIENT_SECRET="<from GH>" bundle exec shotgun
+    % GITHUB_CLIENT_ID="<from GH>" GITHUB_CLIENT_SECRET="<from GH>" bundle exec rackup -p9393
+
+There's an example app in [spec/app.rb](/atmos/sinatra_auth_github/blob/master/spec/app.rb).
 
-```ruby
-module Example
-  class App < Sinatra::Base
-    enable :sessions
+Example App Functionality
+=========================
 
-    set  :github_options, {
-                            # GitHub Provided secrets
-                            :secret       => ENV['GITHUB_CLIENT_SECRET'],
-                            :client_id    => ENV['GITHUB_CLIENT_ID'],
+You can simply authenticate via GitHub by hitting http://localhost:9292
 
-                            # How much info you need about the user
-                            :scopes       => 'user,offline_access',
+You can check organization membership by hitting http://localhost:9292/orgs/github
 
-                            # restrict access to a members of organization named
-                            :organization => "github",
+You can check team membership by hitting http://localhost:9292/teams/42
 
-                            # restrict access to specific team on an organization
-                            :team         => nil # || 42
-                          }
+All unsuccessful authentication requests get sent to the securocat denied page.
 
-    register Sinatra::Auth::Github
+API Requests
+============
 
-    before do
-      authenticate!
-    end
+The extension also provides a simple way to do get requests against the
+GitHub API as the authenticated user.
 
-    helpers do
-      def repos
-        github_request("repos/show/#{github_user.login}")
-      end
+    def repos
+      github_request("user/repos")
     end
 
-    get '/' do
-      "Hello There, #{github_user.name}!#{github_user.token}\n#{repos.inspect}"
-    end
+There's awesome docs on the v3 API [available here](http://developer.github.com/v3/).
 
-    get '/logout' do
-      logout!
-      redirect '/'
-    end
-  end
-end
-```
+Extension Options
+=================
+
+* `:scopes`       - The OAuth2 scopes you require, [Learn More](http://gist.github.com/419219)
+* `:secret`       - The client secret that GitHub provides
+* `:client_id`    - The client id that GitHub provides
+* `:failure_app`  - A Sinatra::Base class that has a route for `/authenticated`, Useful for overriding the securocat default page.
+* `:callback_url` - The path that GitHub posts back to, defaults to `/auth/github/callback`.

data/lib/sinatra/auth/github.rb

@@ -5,14 +5,17 @@ require 'rest_client'
 module Sinatra
   module Auth
     module Github
-      VERSION = "0.1.1"
+      VERSION = "0.1.2"
 
+      # Simple way to serve an image early in the stack and not get blocked by
+      # application level before filters
       class AccessDenied < Sinatra::Base
         get '/_images/securocat.png' do
           send_file(File.join(File.dirname(__FILE__), "views", "securocat.png"))
         end
       end
 
+      # The default failure application, this is overridable from the extension config
       class BadAuthentication < Sinatra::Base
         helpers do
           def unauthorized_template
@@ -43,6 +46,9 @@ module Sinatra
           warden.logout
         end
 
+        # The authenticated user object
+        #
+        # Supports a variety of methods, name, full_name, email, etc
         def github_user
           warden.user
         end
@@ -81,7 +87,7 @@ module Sinatra
         def github_organization_access?(name)
           orgs = github_request("orgs/#{name}/members")
           orgs.map { |org| org["login"] }.include?(github_user.login)
-        rescue RestClient::Unauthorized, RestClient::ResourceNotFound => e
+        rescue RestClient::Forbidden, RestClient::Unauthorized, RestClient::ResourceNotFound => e
           false
         end
 
@@ -93,16 +99,25 @@ module Sinatra
         def github_team_access?(team_id)
           members = github_request("teams/#{team_id}/members")
           members.map { |user| user["login"] }.include?(github_user.login)
-        rescue RestClient::Unauthorized, RestClient::ResourceNotFound => e
+        rescue RestClient::Forbidden, RestClient::Unauthorized, RestClient::ResourceNotFound => e
           false
         end
 
-        # Auth only certain individuals
+        # Enforce user membership to the named organization
+        #
+        # name - the organization to test membership against
+        #
+        # Returns an execution halt if the user is not a member of the named org
         def github_organization_authenticate!(name)
           authenticate!
           halt([401, "Unauthorized User"]) unless github_organization_access?(name)
         end
 
+        # Enforce user membership to the team id
+        #
+        # team_id - the team_id to test membership against
+        #
+        # Returns an execution halt if the user is not a member of the team
         def github_team_authenticate!(team_id)
           authenticate!
           halt([401, "Unauthorized User"]) unless github_team_access?(team_id)
@@ -120,10 +135,9 @@ module Sinatra
 
           manager.failure_app           = app.github_options[:failure_app] || BadAuthentication
 
-          manager[:github_secret]       = app.github_options[:secret]
-          manager[:github_scopes]       = app.github_options[:scopes] || 'email,offline_access'
-          manager[:github_client_id]    = app.github_options[:client_id]
-          manager[:github_organization] = app.github_options[:organization] || nil
+          manager[:github_secret]       = app.github_options[:secret]       || ENV['GITHUB_CLIENT_SECRET']
+          manager[:github_scopes]       = app.github_options[:scopes]       || 'email,offline_access'
+          manager[:github_client_id]    = app.github_options[:client_id]    || ENV['GITHUB_CLIENT_ID']
           manager[:github_callback_url] = app.github_options[:callback_url] || '/auth/github/callback'
         end
 
@@ -131,9 +145,9 @@ module Sinatra
 
         app.get '/auth/github/callback' do
           authenticate!
-          redirect _relative_url_for('/')
+          return_to = session.delete('return_to') || _relative_url_for('/')
+          redirect return_to
         end
-
       end
     end
   end

data/sinatra_auth_github.gemspec

@@ -3,7 +3,7 @@ $:.push File.expand_path("../lib", __FILE__)
 
 Gem::Specification.new do |s|
   s.name        = "sinatra_auth_github"
-  s.version     = "0.1.1"
+  s.version     = "0.1.2"
   s.platform    = Gem::Platform::RUBY
   s.authors     = ["Corey Donohoe"]
   s.email       = ["atmos@atmos.org"]
@@ -15,7 +15,7 @@ Gem::Specification.new do |s|
 
   s.add_dependency "sinatra",       "~>1.0"
   s.add_dependency "rest-client",   "~>1.6.1"
-  s.add_dependency "warden-github", "~>0.1.0"
+  s.add_dependency "warden-github", "~>0.1.1"
 
   s.add_development_dependency "rake"
   s.add_development_dependency "rspec",     "~>1.3.0"

data/spec/app.rb

@@ -35,7 +35,7 @@ module Example
 
     get '/logout' do
       logout!
-      redirect '/'
+      redirect 'https://github.com'
     end
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: sinatra_auth_github
 version: !ruby/object:Gem::Version 
-  hash: 25
+  hash: 31
   prerelease: 
   segments: 
   - 0
   - 1
-  - 1
-  version: 0.1.1
+  - 2
+  version: 0.1.2
 platform: ruby
 authors: 
 - Corey Donohoe
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-06-22 00:00:00 -07:00
+date: 2011-06-27 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -57,12 +57,12 @@ dependencies:
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
-        hash: 27
+        hash: 25
         segments: 
         - 0
         - 1
-        - 0
-        version: 0.1.0
+        - 1
+        version: 0.1.1
   type: :runtime
   version_requirements: *id003
 - !ruby/object:Gem::Dependency