OmniAuth 1.0

OmniAuth is in the process of shedding its minor versions and heading for 1.0. However, along with this upcoming major release will be a complete re-evaluation of everything OmniAuth does from the ground up. This wiki page is a central hub for an ongoing description of what those changes will be.

Release Schedule

OmniAuth 1.0 is now in beta! If you're a strategy developer, please check out the preview version and give feedback. For more, see OmniAuth Beta.

We are now on a track to move towards the final release of OmniAuth 1.0. The schedule is currently as follows:

• Developer Preview on October 13, 2011
• Beta on October 18, 2011
• Release Candidate on or before October 27, 2011
• Public Release on or before November 3, 2011

Separate Gems

The largest change in OmniAuth 1.0 is that OmniAuth will no longer adopt a centralized model for its strategies. Until now, if you had the omniauth gem you had access to 50+ strategies that were maintained in the central OmniAuth repository. As the project has grown this has become a maintenance problem and so, with 1.0, we are jettisoning the old model and adopting a new, one-gem-per-provider model.

What this means is that if I want my application to have Facebook, Twitter, and GitHub authentication, where once I did this:

gem 'omniauth'

I will now need to do this:

gem 'omniauth-twitter'
gem 'omniauth-facebook'
gem 'omniauth-github'

Note that in addition to the new requirement to add each strategy individually, the gems are now named omniauth-strategyname instead of the existing oa-strategyname. While it means typing a few more characters, I believe this will make things less confusing going forward.

Other than needing to require the gems separately, OmniAuth will otherwise work pretty much the way it does now from the using developer's perspective. Users will still be able to use OmniAuth::Builder to make multiple strategies accessible and so on.

OmniAuth Contrib

To serve as a bridge between the old system and the new, an omniauth-contrib gem will be created (and hosted via git only) and will be a holding zone for OmniAuth strategies that have been quickly converted to the 1.0 style without being fully extracted, tested, and made better. Note that OmniAuth Contrib will be a temporary bridge only and will eventually go away. It is being created to encourage rapid adoption of 1.0 but is not going to be a permanent home for any strategy.

Legacy Support

Once OmniAuth 1.0.0 is officially released, the 0.3.x version of OmniAuth will be locked down except for bugfixes. No further new strategies or features will be accepted as issues and will be closed out immediately. My hope is that the stronger documentation, simpler API, and general benefits of 1.0 will make the transition of many strategies come sooner than later and obviate the need for a long-term split.

Changes to the Auth Hash

Previously the hash that OmniAuth returned was simply that: a hash with a common schema as defined on the Auth Hash Schema page of the wiki. As of OmniAuth 1.0 we will be providing a slightly more powerful mechanism for the Auth Hash in the form of a custom Hash subclass powered by Hashie. This will allow a few new things including:

• Method name access: env['omniauth.auth'].uid will work, for example
• Check for validity: env['omniauth.auth'].valid? will be true if all required schema parts are present.
• Indifferent Access: env['omniauth.auth'][:uid] == env['omniauth.auth']['uid']
• Intelligent "name" assignment: will check first for :name key, then concatenate first and last names, then email if nothing else works.

Along with this is a minor change to the schema: the user_info hash will now just be info. Example:

{
  provider: 'twitter',
  uid: '12345',
  info: {
    name: 'Michael Bleigh',
    location: 'Kansas City, MO',
    image: 'http://example.com/imagejpg'
  }
}

Changes to Dynamic Providers

1.0 will be doing away with the relatively ill-considered dynamic setup system of calling through to the app and responding with whatever the app returned unless it's a 404. This was unclear, confusing, and caused a number of people problems that they didn't exactly know how to fix.

If you wish to dynamically set up a provider, the proper way as of 1.0 is to use the setup phase. The setup phase is a Rack endpoint that is called but not rendered to the user before both the request and callback phases of the OmniAuth lifecycle. For instance, if I wanted to dynamically set the :foo option on the strategy based on the session, I could do something like this:

use OmniAuth::Builder do
  provider :example, :setup => lambda{|env| env['omniauth.strategy'].options[:foo] = env['rack.session']['foo'] }
end

If you are looking to simply replace the default OmniAuth forms with something more friendly to your particular application, you will be able to simply pass a :form option with a Rack endpoint that will render in place of the OmniAuth default form. For example, in a Rails application you might do something like this:

use OmniAuth::Builder do
  provider :example, :form => SessionsController.action(:new)
end

Changes to Strategies

Strategy Initialization Yield

Because strategy authors will be encouraged as of 1.0 to be driven 100% by the options hash instead of instance variables, etc, the Strategy initialization method now yields the options hash instead of the strategy object. This means that if you previously did something like this:

MyStrategy.new do |strategy|
  strategy.options[:my_option] = 'abc'
end

You will now need to do this instead (method access is provided because Options is now a Mash instead of a bare Hash:

MyStrategy.new do |config|
  config.my_option = 'abc'
end

Authoring Strategies

We are trying to clarify a process to author strategies so that newcomers can do so without as much code reading headaches. Part of this is to vastly improve the YARD documentation of the core OmniAuth classes, and the second half of this is the work-in-progess Strategy Contribution Guide which will serve as a kind of how-to manual for writing custom OmniAuth strategies.

Adapting Existing Strategies

If you are working on gemifying an existing OmniAuth strategy to get it to work with 1.0, you should check out the Adapting Strategies for 1.0 page.