Omniauth Strategy for Accessing The City OAuth2 Provider
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib
spec
.DS_Store
.gitignore
.rspec
.travis.yml
Gemfile
Gemfile.lock
Guardfile
LICENSE.txt
README.md
Rakefile
omniauth-thecity.gemspec

README.md

Omniauth::Thecity

Gem Version Dependency Status Build Status

This gem contains The City strategy for OmniAuth.

Before You Begin

You should have already installed OmniAuth into your app; if not, read the OmniAuth README to get started.

Installation

Add this line to your application's Gemfile:

gem 'omniauth-thecity'

Or install it yourself as:

$ gem install omniauth-thecity

Usage

Tell OmniAuth about this provider. For a Rails app, your config/initializers/omniauth.rb file should look like this:

Rails.application.config.middleware.use OmniAuth::Builder do
  provider :thecity, "APPID", "SECRET", :scope => 'user_basic user_extended'
end

The City subdomains

City users have one global user, and then a local user for each subdomain (City) they have an active account.

When a user successfully authenticates, omnniauth-thecity returns an array of local users belonging to the City global user. If you pass along a subdomain, The City authentication service will only return an active local user for the subdomain you passed in.

If your app only cares about one City subdomain (e.g. gracechurch.onthecity.org ), you can configure omniauth-thecity globally like this:

Rails.application.config.middleware.use OmniAuth::Builder do
  provider :thecity, "APPID", "SECRET", :scope => 'user_basic user_extended', :subdomain => 'gracechurch'}
end

Otherwise, you can set the subdomain per request as a query parameter, or header.

For example, when using devise you can pass the subdomain using the route helper:

user_omniauth_authorize_path(:thecity, params: {subdomain: 'gracechurch'})

or as a custom header in your request:

X_THECITY_SUBDOMAIN: gracechurch

Authentication Hash

An example auth hash available in request.env['omniauth.auth']:

{
  "provider"=>:thecity,
  "uid"=>216612,
	"info"=> {
    "global_user"=> {
      "id"=>216612,
      "first"=>"Robert",
      "last"=>"Robertson",
      "email"=>"robert.son@email.com",
      "gender"=>"Male",
      "birthdate"=>"1977-10-13"
    },
    "user"=> {
      "id"=>14347,
      "title"=>"Deacon",
      "member"=>false,
      "staff"=>true,
      "first"=>"Bob",
      "last"=>"Robertson",
      "email"=>"robert.son@email.com",
      "account_id"=>12345678,
      "profile_picture"=> "https://....a4bfe58666_thumb.png",
      "admin_privileges"=>[
        { "title"=>"Account Admin" },
        { "group_id"=>12345, "title"=>"Group Admin" },
        { "title"=>"User Admin" }
      ]
    }
  },
  "credentials"=> {
    "token"=>"3551fe753551355144dc88b45173551f9e69dde79f355180db35516c11b357e9",
    "expires"=>false
  },
  "extra"=>{}
}

Watch the RailsCast

Ryan Bates has put together an excellent RailsCast on OmniAuth:

RailsCast #241

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request

License

Copyright (c) 2013 Mark Blair See LICENSE for details.