Omniauth::Thecity

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"=>"[email protected]",
      "gender"=>"Male",
      "birthdate"=>"1977-10-13"
    },
    "user"=> {
      "id"=>14347,
      "title"=>"Deacon",
      "member"=>false,
      "staff"=>true,
      "first"=>"Bob",
      "last"=>"Robertson",
      "email"=>"[email protected]",
      "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:

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.