Update README
This commit is contained in:
parent
dfb77bfd89
commit
5d2c3deb6a
149
README.md
149
README.md
|
@ -1,60 +1,133 @@
|
||||||
# OmniAuth: Standardized Multi-Provider Authentication
|
# OmniAuth: Standardized Multi-Provider Authentication
|
||||||
|
|
||||||
**NOTICE:** This documentation and code is toward OmniAuth 1.0 in which
|
**NOTICE:** This documentation and code is for OmniAuth 1.0 in which
|
||||||
each provider will become its own separate gem. If you're looking for
|
each provider will become its own separate gem. If you're looking for
|
||||||
the current released version, please visit [OmniAuth 0.3 Stable
|
the current released version, please visit [OmniAuth 0.3 Stable
|
||||||
Branch](https://github.com/intridea/omniauth/tree/0-3-stable).
|
Branch](https://github.com/intridea/omniauth/tree/0-3-stable).
|
||||||
|
|
||||||
## Structural Changes Coming in 1.0
|
## An Introduction
|
||||||
|
|
||||||
In version 1.0, the `omniauth` gem will become simply the underlying
|
OmniAuth is a libary that standardizes multi-provider authentication for
|
||||||
framework upon which authentication strategies can be built. That means
|
web applications. It was created to be powerful, flexible, and do as
|
||||||
where once users would put `gem 'omniauth'` into their Gemfile and be
|
little as possible. Any developer can create **strategies** for OmniAuth
|
||||||
finished, now each provider will have a separate gem (e.g.
|
that can authenticate users via disparate systems. OmniAuth strategies
|
||||||
`oa-twitter`).
|
have been created for everything from Facebook to LDAP.
|
||||||
|
|
||||||
This change will bring about better code, faster releases, and hopefully
|
In order to use OmniAuth in your applications, you will need to leverage
|
||||||
an even more vibrant provider landscape. For more on the rationale of
|
one or more strategies. These strategies are generally released
|
||||||
the change, see [this issue](https://github.com/intridea/omniauth/issues/451).
|
individually as RubyGems, and you can see a [community maintained list](https://github.com/intridea/omniauth/wiki/List-of-Strategies)
|
||||||
|
on the wiki for this project.
|
||||||
|
|
||||||
## Technical Changes Coming in 1.0
|
## Adding OmniAuth to Your Application
|
||||||
|
|
||||||
### The AuthHash Class
|
Each OmniAuth strategy is a Rack Middleware. That means that you can use
|
||||||
|
it the same way that you use any other Rack middleware. For example, to
|
||||||
|
use the built-in Developer strategy in a Sinatra application I might do
|
||||||
|
this:
|
||||||
|
|
||||||
In the past, OmniAuth has provided a simple hash of authentication
|
require 'sinatra'
|
||||||
information. In 1.0, the returned data will be an AuthHash, a special
|
require 'omniauth'
|
||||||
kind of hash that has extra properties special to OmniAuth. In addition,
|
|
||||||
the auth hash schema will be changing slightly. More on that soon.
|
|
||||||
|
|
||||||
### Universal Options
|
class MyApplication < Sinatra::Base
|
||||||
|
use Rack::Session
|
||||||
|
use OmniAuth::Strategies::Developer
|
||||||
|
end
|
||||||
|
|
||||||
In 1.0, it will be possible to set certain configuration options that
|
Because OmniAuth is built for *multi-provider* authentication, I may
|
||||||
will then apply to all providers. This will make certain things easier.
|
want to leave room to run multiple strategies. For this, the built-in
|
||||||
|
`OmniAuth::Builder` class gives you an easy way to specify multiple
|
||||||
|
strategies. Note that there is **no difference** between the following
|
||||||
|
code and using each strategy individually as middleware. This is an
|
||||||
|
example that you might put into a Rails initializer at
|
||||||
|
`config/initializers/omniauth.rb`:
|
||||||
|
|
||||||
### Simpler Dynamic Workflow
|
Rails.application.config.middleware.use OmniAuth::Builder do
|
||||||
|
provider :developer unless Rails.env.production?
|
||||||
|
provider :twitter, ENV['TWITTER_KEY'], ENV['TWITTER_SECRET']
|
||||||
|
end
|
||||||
|
|
||||||
To date, the workflow for "dynamic" providers (being able to change them
|
You should look to the documentation for each provider you use for
|
||||||
at runtime) has been somewhat difficult. We will be re-evaluating this
|
specific initialization requirements.
|
||||||
process and making sure it's as good as it can be.
|
|
||||||
|
|
||||||
### Declarative Provider Authorship
|
## Integrating OmniAuth Into Your Application
|
||||||
|
|
||||||
We hope to provide a more declarative provider authorship system that
|
OmniAuth is an extremely low-touch library. It is designed to be a
|
||||||
will make it both easier to write and easier to test strategies. Much of
|
black box that you can send your application's users into when you need
|
||||||
this may have to be implemented in "aggregate" strategy providers such
|
authentication and then get information back. OmniAuth was intentionally
|
||||||
as OAuth and OAuth2, but stay tuned for more on this.
|
built not to automatically associate with a User model or make
|
||||||
|
assumptions about how many authentication methods you might want to use
|
||||||
|
or what you might want to do with the data once a user has
|
||||||
|
authenticated. This makes OmniAuth incredibly flexible. To use OmniAuth,
|
||||||
|
you need only to redirect users to `/auth/:provider`, where `:provider`
|
||||||
|
is the name of the strategy (for example, `developer` or `twitter`).
|
||||||
|
From there, OmniAuth will take over and take the user through the
|
||||||
|
necessary steps to authenticate them with the chosen strategy.
|
||||||
|
|
||||||
### Testing, Testing, Testing!
|
Once the user has authenticated, what do you do next? OmniAuth simply
|
||||||
|
sets a special hash called the Authentication Hash on the Rack
|
||||||
|
environment of a request to `/auth/:provider/callback`. This hash
|
||||||
|
contains as much information about the user as OmniAuth was able to
|
||||||
|
glean from the utilized strategy. You should set up an endpoint in your
|
||||||
|
application that matches to the callback URL and then performs whatever
|
||||||
|
steps are necessary for your application. For example, in a Rails app I
|
||||||
|
would add a line in my `routes.rb` file like this:
|
||||||
|
|
||||||
OmniAuth 1.0 will be strongly tested and solid. Because we can release
|
match '/auth/:provider/callback', to: 'sessions#create'
|
||||||
it one piece at a time (starting with the core gem and expanding out
|
|
||||||
into the other provider gems) we will be able to maintain much higher
|
|
||||||
code quality and the project will generally be more manageable.
|
|
||||||
|
|
||||||
## Stay Tuned!
|
And I might then have a `SessionsController` with code that looks
|
||||||
|
something like this:
|
||||||
|
|
||||||
OmniAuth 1.0 is a work in progress. We will keep the community updated
|
class SessionsController < ApplicationController
|
||||||
about progress as we have more information. Thanks!
|
def create
|
||||||
|
@user = ̈User.find_or_create_from_auth_hash(auth_hash)
|
||||||
|
self.current_user = @user
|
||||||
|
redirect_to '/'
|
||||||
|
end
|
||||||
|
|
||||||
# <a name="license">License</a>
|
protected
|
||||||
OmniAuth is released under the MIT License.
|
|
||||||
|
def auth_hash
|
||||||
|
request.env['omniauth.auth']
|
||||||
|
end
|
||||||
|
end
|
||||||
|
|
||||||
|
The `omniauth.auth` key in the environment hash gives me my
|
||||||
|
Authentication Hash which will contain information about the just
|
||||||
|
authenticated user including a unique id, the strategy they just used
|
||||||
|
for authentication, and personal details such as name and email address
|
||||||
|
as available. For an in-depth description of what the authentication
|
||||||
|
hash might contain, see the [Auth Hash Schema wiki page](https://github.com/intridea/omniauth/wiki/Auth-Hash-Schema).
|
||||||
|
|
||||||
|
Note that OmniAuth does not perform any actions beyond setting some
|
||||||
|
environment information on the callback request. It is entirely up to
|
||||||
|
you how you want to implement the particulars of your application's
|
||||||
|
authentication flow.
|
||||||
|
|
||||||
|
## Resources
|
||||||
|
|
||||||
|
The [OmniAuth Wiki](https://github.com/intridea/omniauth/wiki) has
|
||||||
|
actively maintained in-depth documentation for OmniAuth. It should be
|
||||||
|
your first stop if you are wondering about a more in-depth look at
|
||||||
|
OmniAuth, how it works, and how to use it.
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
Copyright (c) 2011 Intridea, Inc.
|
||||||
|
|
||||||
|
Permission is hereby granted, free of charge, to any person obtaining a
|
||||||
|
copy of this software and associated documentation files (the "Software"),
|
||||||
|
to deal in the Software without restriction, including without limitation
|
||||||
|
the rights to use, copy, modify, merge, publish, distribute, sublicense,
|
||||||
|
and/or sell copies of the Software, and to permit persons to whom the
|
||||||
|
Software is furnished to do so, subject to the following conditions:
|
||||||
|
|
||||||
|
The above copyright notice and this permission notice shall be included
|
||||||
|
in all copies or substantial portions of the Software.
|
||||||
|
|
||||||
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
|
||||||
|
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||||
|
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
|
||||||
|
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||||
|
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
|
||||||
|
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
|
||||||
|
DEALINGS IN THE SOFTWARE.
|
||||||
|
|
Loading…
Reference in New Issue