Update README
This commit is contained in:
Michael Bleigh
parent
dfb77bfd89
commit
5d2c3deb6a
149
README.md
149
README.md
|
|
@ -1,60 +1,133 @@
|
|||
# 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
|
||||
the current released version, please visit [OmniAuth 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
|
||||
framework upon which authentication strategies can be built. That means
|
||||
where once users would put `gem 'omniauth'` into their Gemfile and be
|
||||
finished, now each provider will have a separate gem (e.g.
|
||||
`oa-twitter`).
|
||||
OmniAuth is a libary that standardizes multi-provider authentication for
|
||||
web applications. It was created to be powerful, flexible, and do as
|
||||
little as possible. Any developer can create **strategies** for OmniAuth
|
||||
that can authenticate users via disparate systems. OmniAuth strategies
|
||||
have been created for everything from Facebook to LDAP.
|
||||
|
||||
This change will bring about better code, faster releases, and hopefully
|
||||
an even more vibrant provider landscape. For more on the rationale of
|
||||
the change, see [this issue](https://github.com/intridea/omniauth/issues/451).
|
||||
In order to use OmniAuth in your applications, you will need to leverage
|
||||
one or more strategies. These strategies are generally released
|
||||
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
|
||||
information. In 1.0, the returned data will be an AuthHash, a special
|
||||
kind of hash that has extra properties special to OmniAuth. In addition,
|
||||
the auth hash schema will be changing slightly. More on that soon.
|
||||
require 'sinatra'
|
||||
require 'omniauth'
|
||||
|
||||
### 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
|
||||
will then apply to all providers. This will make certain things easier.
|
||||
Because OmniAuth is built for *multi-provider* authentication, I may
|
||||
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
|
||||
at runtime) has been somewhat difficult. We will be re-evaluating this
|
||||
process and making sure it's as good as it can be.
|
||||
You should look to the documentation for each provider you use for
|
||||
specific initialization requirements.
|
||||
|
||||
### Declarative Provider Authorship
|
||||
## Integrating OmniAuth Into Your Application
|
||||
|
||||
We hope to provide a more declarative provider authorship system that
|
||||
will make it both easier to write and easier to test strategies. Much of
|
||||
this may have to be implemented in "aggregate" strategy providers such
|
||||
as OAuth and OAuth2, but stay tuned for more on this.
|
||||
OmniAuth is an extremely low-touch library. It is designed to be a
|
||||
black box that you can send your application's users into when you need
|
||||
authentication and then get information back. OmniAuth was intentionally
|
||||
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
|
||||
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.
|
||||
match '/auth/:provider/callback', to: 'sessions#create'
|
||||
|
||||
## 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
|
||||
about progress as we have more information. Thanks!
|
||||
class SessionsController < ApplicationController
|
||||
def create
|
||||
@user = ̈User.find_or_create_from_auth_hash(auth_hash)
|
||||
self.current_user = @user
|
||||
redirect_to '/'
|
||||
end
|
||||
|
||||
# <a name="license">License</a>
|
||||
OmniAuth is released under the MIT License.
|
||||
protected
|
||||
|
||||
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