{"id":15637938,"url":"https://github.com/fphilipe/warden-github-rails","last_synced_at":"2025-04-09T10:09:11.560Z","repository":{"id":6778496,"uuid":"8025579","full_name":"fphilipe/warden-github-rails","owner":"fphilipe","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.","archived":false,"fork":false,"pushed_at":"2017-05-16T08:35:54.000Z","size":141,"stargazers_count":98,"open_issues_count":0,"forks_count":17,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-02T03:46:36.659Z","etag":null,"topics":["authentication","authorization","gem","github","oauth","ruby","warden","warden-github"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fphilipe.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-02-05T08:51:41.000Z","updated_at":"2024-06-25T14:03:51.000Z","dependencies_parsed_at":"2022-08-31T22:01:53.043Z","dependency_job_id":null,"html_url":"https://github.com/fphilipe/warden-github-rails","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fphilipe%2Fwarden-github-rails","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fphilipe%2Fwarden-github-rails/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fphilipe%2Fwarden-github-rails/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fphilipe%2Fwarden-github-rails/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fphilipe","download_url":"https://codeload.github.com/fphilipe/warden-github-rails/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248018061,"owners_count":21034048,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["authentication","authorization","gem","github","oauth","ruby","warden","warden-github"],"created_at":"2024-10-03T11:15:39.758Z","updated_at":"2025-04-09T10:09:11.536Z","avatar_url":"https://github.com/fphilipe.png","language":"Ruby","readme":"# warden-github-rails\n\n[![Build Status][build-image]][build-link]\n[![Gem Version][gem-image]][gem-link]\n[![Dependency Status][deps-image]][deps-link]\n[![Code Climate][gpa-image]][gpa-link]\n[![Coverage Status][cov-image]][cov-link]\n\nA gem for rails that provides easy GitHub OAuth integration.\nIt is built on top of [warden-github](https://github.com/atmos/warden-github), which gives you an easy to use [warden](https://github.com/hassox/warden) strategy to authenticate GitHub users.\n\n## Motivation\n\n**Wouldn't it be nice to**\n\n- use your organization and its teams for user access control?\n- add a new employee to your GitHub organization or team in order to grant them access to your app's admin area?\n\nThe 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.\nThe provided routing helpers do exactly that.\nThey allow you to restrict access to members of your organization or a certain team.\n\nThis is how your rails `routes.rb` could look like:\n\n```ruby\nconstraints(subdomain: 'admin') do\n  github_authenticate(org: 'my_company_inc') do\n    resources :users\n    resources :projects\n\n    github_authenticated(team: 'sysadmins') do\n      resource :infrastructure\n    end\n  end\nend\n```\n\nOf course, this gem can also be used for user registration and authentication.\nSeveral helper methods are available in the controller to accomplish this:\n\n```ruby\nclass UsersController \u003c ApplicationController\n  # ...\n\n  def new\n    github_authenticate! # Performs OAuth flow when not logged in.\n    @user = User.new(name: github_user.name, email: github_user.email)\n  end\n\n  def create\n    attrs = params.require(:user).permit(:name, :email).merge(github_id: github_user.id)\n    @user = User.create(attrs)\n\n    if @user.persisted?\n      redirect_to :show\n    else\n      render :new\n    end\n  end\n\n  # ...\nend\n```\n\n## Example App\n\nThis repository includes an example app in [example/](example/).\nTo play with it, follow these steps:\n\n1.  [Create an OAuth application in your GitHub settings](https://github.com/settings/applications/new).\n    Set the callback URL to `http://localhost:3000/`\n\n2.  Check out this repo and run:\n\n    ```\n    $ bundle\n    $ cd example\n    $ GITHUB_CLIENT_ID=your_id_from_step1 GITHUB_CLIENT_SECRET=your_secret_from_step1 bundle exec rails s\n    ```\n\n3.  Point your browser to [http://localhost:3000/](http://localhost:3000/) and enjoy!\n\n## Installation\n\nTo use this gem, add it to your `Gemfile`:\n\n```ruby\ngem 'warden-github-rails'\n```\n\nIf you're using devise, make sure to use version 2.2.4 or newer.\nPrevious versions are not compatible with warden-github-rails and thus will not work.\nSee the note at [*Using alongside Devise and other Warden Gems*](#using-alongside-devise-and-other-warden-gems) for an explanation.\n\n## Usage\n\n### Configuration\n\nFirst off, you might want to configure this gem by creating an initializer such as `config/initializers/warden_github_rails.rb`.\nThere you can define:\n\n- various scopes and their configs (scopes are types of users with different configs)\n- the default scope (which is `:user` by default)\n- team aliases (GitHub teams are identified by a numerical ID; defining an alias for a team makes it easier to use)\n\nHere's how such a config might look like:\n\n```ruby\nWarden::GitHub::Rails.setup do |config|\n  config.add_scope :user,  client_id:     'foo',\n                           client_secret: 'bar',\n                           scope:         'user:email'\n\n  config.add_scope :admin, client_id:     'abc',\n                           client_secret: 'xyz',\n                           redirect_uri:  '/admin/login/callback',\n                           scope:         'read:org'\n\n  config.default_scope = :admin\n\n  config.add_team :marketing, 456\nend\n```\n\nFor a list of allowed config parameters to use in `#add_scope`, read the [warden-github documentation](https://github.com/atmos/warden-github#parameters).\n\n### Inside `routes.rb`\n\nThe available routing helpers are defined and documented in [lib/warden/github/rails/routes.rb](lib/warden/github/rails/routes.rb).\nThey all accept an optional scope that, when omitted, falls back to the default_scope configured in the initializer.\n\nExamples:\n\n```ruby\n# Performs login if not logged in already.\ngithub_authenticate do\n  resource :profile\nend\n\n# Does not perform login when not logged in.\ngithub_authenticated do\n  delete '/logout' =\u003e 'sessions#delete'\nend\n\n# Only matches when not logged in. Does not perform login.\ngithub_unauthenticated do\n  resource :registration\nend\n\n# Only matches when member of the organization. Initiates login if not logged in.\ngithub_authenticate(org: 'my_company') do\n  resource :admin\nend\n\n# Only matches when member of the team. Does not initiate login if not logged in.\ngithub_authenticated(team: 'markting') do\n  get '/dashboard' =\u003e 'dashboard#show'\nend\n\n# Matches if a member of any of the teams given. Does not initiate login if not logged in.\ngithub_authenticated(team: ['markting', 'graphic-design']) do\n  get '/dashboard' =\u003e 'dashboard#show'\nend\n\n# Using dynamic membership values:\ngithub_authenticate(org: lambda { |req| req.params[:id] }) do\n  get '/orgs/:id' =\u003e 'orgs#show'\nend\n```\n\n### Inside a Controller\n\nThe available controller helpers are defined and documented in [lib/warden/github/rails/controller_helpers.rb](lib/warden/github/rails/controller_helpers.rb).\nThey all accept an optional scope that, when omitted, falls back to the default_scope configured in the initializer.\n\n```ruby\nclass SomeController \u003c ActionController::Base\n  def show\n    @is_admin = github_authenticated?(:admin)\n  end\n\n  def delete\n    github_logout\n    redirect_to '/'\n  end\n\n  def settings\n    github_authenticate!\n    @settings = UserSettings.find_by(github_user_id: github_user.id)\n  end\n\n  def finish_wizard\n    github_session[:wizard_completed] = true\n  end\n\n  def followers\n    @followers = github_user.api.followers\n  end\nend\n```\n\n### Communicating with the GitHub API\n\nOnce a user is logged in, you'll have access to it in the controller using `github_user`.\nIt is an instance of `Warden::GitHub::User` which is defined in the [warden-github](https://github.com/atmos/warden-github/blob/master/lib/warden/github/user.rb) gem.\nThe instance has several methods to access user information such as `#name`, `#id`, `#email`, etc.\nIt also features a method `#api` which returns a preconfigured [Octokit](https://github.com/octokit/octokit.rb) client for that user.\n\n### Test Helpers\n\nThis gems comes with a couple test helpers to make your life easier:\n\n-   A method is added to `Rack::Response` called `#github_oauth_redirect?` which\n    returns true if the response is a redirect to a url that starts with\n    `https://github.com/login/oauth/authorize`. You can use it in your request\n    tests to make sure the OAuth dance is initiated. In rspec you could verify\n    this as follows:\n\n    ```ruby\n    subject { get '/some-url-that-triggers-oauth' }\n    it { is_expected.to be_github_oauth_redirect }\n    ```\n\n-   A mock user that allows you to stub team and organization memberships:\n\n    ```ruby\n    user = Warden::GitHub::Rails::TestHelpers::MockUser.new\n    user.stub_membership(team: [234, 987], org: 'some-inc')\n    user.team_member?(234) # =\u003e true\n    user.organization_member?('rails') # =\u003e false\n    ```\n\n-   A method that creates a mock user and logs it in. If desired, the scope can\n    be specified. The method returns the mock user so that you can manipulate it\n    further:\n\n    ```ruby\n    user = github_login(:admin)\n\n    get '/org/rails/admin'\n    expect(response).to be_not_found\n\n    user.stub_membership(org: 'rails')\n    get '/org/rails/admin'\n    expect(response).to be_ok\n    ```\n\nIn order to use the mock user and the `#github_login` method, make sure to `require 'warden/github/rails/test_helpers'` and to `include Warden::GitHub::Rails::TestHelpers` in your tests.\n\n## Using alongside Devise and other Warden Gems\n\nCurrently this gem does not play nicely with other gems that setup a warden middleware.\nThe reason is that warden simply does not have support for multiple middlewares.\nThe warden middleware configures a warden instance and adds it to the rack environment.\nAny other warden middleware downstream checks for any existing warden instance in the environment and, if present, skips itself.\nI've opened an [issue](https://github.com/hassox/warden/issues/67) on the warden repository to discuss possible workarounds.\n\nNevertheless, this gem is compatible with devise for version 2.2.4 and newer.\ndevise allows you to specify a block that will be invoked when the warden middleware is configured.\nThis functionality is used in this gem in order to setup the github strategy for warden instead of inserting our own middleware.\n\n## Additional Information\n\n### Dependencies\n\n- [warden-github](https://github.com/atmos/warden-github)\n    - [warden](https://github.com/hassox/warden)\n    - [octokit](https://github.com/octokit/octokit.rb)\n\n### Author\n\nPhilipe Fatio ([@fphilipe][fphilipe twitter])\n\n[![Support via Gittip][tip-image]][tip-link]\n\n### License\n\nMIT License. Copyright 2013 Philipe Fatio\n\n[build-image]: https://travis-ci.org/fphilipe/warden-github-rails.svg\n[build-link]:  https://travis-ci.org/fphilipe/warden-github-rails\n[gem-image]:   https://badge.fury.io/rb/warden-github-rails.svg\n[gem-link]:    https://rubygems.org/gems/warden-github-rails\n[deps-image]:  https://gemnasium.com/fphilipe/warden-github-rails.svg\n[deps-link]:   https://gemnasium.com/fphilipe/warden-github-rails\n[gpa-image]:   https://codeclimate.com/github/fphilipe/warden-github-rails.svg\n[gpa-link]:    https://codeclimate.com/github/fphilipe/warden-github-rails\n[cov-image]:   https://coveralls.io/repos/fphilipe/warden-github-rails/badge.svg\n[cov-link]:    https://coveralls.io/r/fphilipe/warden-github-rails\n[tip-image]:   https://rawgithub.com/twolfson/gittip-badge/0.1.0/dist/gittip.png\n[tip-link]:    https://www.gittip.com/fphilipe/\n\n[fphilipe twitter]: https://twitter.com/fphilipe\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffphilipe%2Fwarden-github-rails","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffphilipe%2Fwarden-github-rails","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffphilipe%2Fwarden-github-rails/lists"}