Name: warden-github-rails
Owner: HuBoard
Description: Use GitHub as authorization and more. Use organizations and teams as means of authorization by simply wrapping your rails routes in a block. Also useful to get a user's details through OAuth.
Created: 2015-02-22 21:23:09.0
Updated: 2016-07-04 22:18:23.0
Pushed: 2015-03-05 16:24:49.0
Size: 216
Language: Ruby
GitHub Committers
| User | Most Recent Commit | # Commits |
|---|
Other Committers
| User | Most Recent Commit | # Commits |
|---|
A gem for rails that provides easy GitHub OAuth integration. It is built on top of warden-github, which gives you an easy to use warden strategy to authenticate GitHub users.
Wouldn't it be nice to
The motivation for this gem was to provide a very easy authorization (not authentication) mechanism to existing rails apps for admins, especially in combination with organization and team memberships. The provided routing helpers do exactly that. They allow you to restrict access to members of your organization or a certain team.
This is how your rails routes.rb could look like:
traints(subdomain: 'admin') do
thub_authenticate(org: 'my_company_inc') do
resources :users
resources :projects
github_authenticated(team: 'sysadmins') do
resource :infrastructure
end
d
Of course, this gem can also be used for user registration and authentication. Several helper methods are available in the controller to accomplish this:
s UsersController < ApplicationController
...
f new
github_authenticate! # Performs OAuth flow when not logged in.
@user = User.new(name: github_user.name, email: github_user.email)
d
f create
attrs = params.require(:user).permit(:name, :email).merge(github_id: github_user.id)
@user = User.create(attrs)
if @user.persisted?
redirect_to :show
else
render :new
end
d
...
This repository includes an example app in example/. To play with it, follow these steps:
Create an OAuth application in your GitHub settings.
Set the callback URL to http://localhost:3000/
Check out this repo and run:
ndle
example
THUB_CLIENT_ID=your_id_from_step1 GITHUB_CLIENT_SECRET=your_secret_from_step1 bundle exec rails s
Point your browser to http://localhost:3000/ and enjoy!
To use this gem, add it to your Gemfile:
'warden-github-rails', '~> 1.1.0'
If you're using devise, make sure to use version 2.2.4 or newer. Previous versions are not compatible with warden-github-rails and thus will not work. See the note at Using alongside Devise and other Warden Gems for an explanation.
First off, you might want to configure this gem by creating an initializer such as config/initializers/warden_github_rails.rb.
There you can define:
:user by default)Here's how such a config might look like:
en::GitHub::Rails.setup do |config|
nfig.add_scope :user, client_id: 'foo',
client_secret: 'bar',
scope: 'user:email'
nfig.add_scope :admin, client_id: 'abc',
client_secret: 'xyz',
redirect_uri: '/admin/login/callback',
scope: 'read:org'
nfig.default_scope = :admin
nfig.add_team :marketing, 456
For a list of allowed config parameters to use in #add_scope, read the warden-github documentation.
routes.rbThe available routing helpers are defined and documented in lib/warden/github/rails/routes.rb. They all accept an optional scope that, when omitted, falls back to the default_scope configured in the initializer.
Examples:
rforms login if not logged in already.
ub_authenticate do
source :profile
es not perform login when not logged in.
ub_authenticated do
lete '/logout' => 'sessions#delete'
ly matches when not logged in. Does not perform login.
ub_unauthenticated do
source :registration
ly matches when member of the organization. Initiates login if not logged in.
ub_authenticate(org: 'my_company') do
source :admin
ly matches when member of the team. Does not initiate login if not logged in.
ub_authenticated(team: 'markting') do
t '/dashboard' => 'dashboard#show'
ing dynamic membership values:
ub_authenticate(org: lambda { |req| req.params[:id] }) do
t '/orgs/:id' => 'orgs#show'
The available controller helpers are defined and documented in lib/warden/github/rails/controller_helpers.rb. They all accept an optional scope that, when omitted, falls back to the default_scope configured in the initializer.
s SomeController < ActionController::Base
f show
@is_admin = github_authenticated?(:admin)
d
f delete
github_logout
redirect_to '/'
d
f settings
github_authenticate!
@settings = UserSettings.find_by(github_user_id: github_user.id)
d
f finish_wizard
github_session[:wizard_completed] = true
d
f followers
@followers = github_user.api.followers
d
Once a user is logged in, you'll have access to it in the controller using github_user.
It is an instance of Warden::GitHub::User which is defined in the warden-github gem.
The instance has several methods to access user information such as #name, #id, #email, etc.
It also features a method #api which returns a preconfigured Octokit client for that user.
This gems comes with a couple test helpers to make your life easier:
A method is added to Rack::Response called #github_oauth_redirect? which
returns true if the response is a redirect to a url that starts with
https://github.com/login/oauth/authorize. You can use it in your request
tests to make sure the OAuth dance is initiated. In rspec you could verify
this as follows:
ect { get '/some-url-that-triggers-oauth' }
is_expected.to be_github_oauth_redirect }
A mock user that allows you to stub team and organization memberships:
= Warden::GitHub::Rails::TestHelpers::MockUser.new
.stub_membership(team: [234, 987], org: 'some-inc')
.team_member?(234) # => true
.organization_member?('rails') # => false
A method that creates a mock user and logs it in. If desired, the scope can be specified. The method returns the mock user so that you can manipulate it further:
= github_login(:admin)
'/org/rails/admin'
ct(response).to be_not_found
.stub_membership(org: 'rails')
'/org/rails/admin'
ct(response).to be_ok
In order to use the mock user and the #github_login method, make sure to
include Warden::GitHub::Rails::TestHelpers in your tests.
Currently this gem does not play nicely with other gems that setup a warden middleware. The reason is that warden simply does not have support for multiple middlewares. The warden middleware configures a warden instance and adds it to the rack environment. Any other warden middleware downstream checks for any existing warden instance in the environment and, if present, skips itself. I've opened an issue on the warden repository to discuss possible workarounds.
Nevertheless, this gem is compatible with devise for version 2.2.4 and newer. devise allows you to specify a block that will be invoked when the warden middleware is configured. This functionality is used in this gem in order to setup the github strategy for warden instead of inserting our own middleware.
Philipe Fatio (@fphilipe)
MIT License. Copyright 2013 Philipe Fatio