Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Update README

  • Loading branch information...
commit 5d2c3deb6a767aa2e5366ad9e4533ded8d82cb69 1 parent dfb77bf
Michael Bleigh authored
Showing with 127 additions and 54 deletions.
  1. +127 −54 README.md
View
181 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
-
-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`).
-
-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).
-
-## Technical Changes Coming in 1.0
-
-### The AuthHash Class
-
-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.
-
-### Universal Options
-
-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.
-
-### Simpler Dynamic Workflow
-
-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.
-
-### Declarative Provider Authorship
-
-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.
-
-### Testing, Testing, Testing!
-
-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.
-
-## Stay Tuned!
-
-OmniAuth 1.0 is a work in progress. We will keep the community updated
-about progress as we have more information. Thanks!
-
-# <a name="license">License</a>
-OmniAuth is released under the MIT License.
+## An Introduction
+
+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.
+
+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.
+
+## Adding OmniAuth to Your Application
+
+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:
+
+ require 'sinatra'
+ require 'omniauth'
+
+ class MyApplication < Sinatra::Base
+ use Rack::Session
+ use OmniAuth::Strategies::Developer
+ end
+
+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`:
+
+ Rails.application.config.middleware.use OmniAuth::Builder do
+ provider :developer unless Rails.env.production?
+ provider :twitter, ENV['TWITTER_KEY'], ENV['TWITTER_SECRET']
+ end
+
+You should look to the documentation for each provider you use for
+specific initialization requirements.
+
+## Integrating OmniAuth Into Your Application
+
+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.
+
+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:
+
+ match '/auth/:provider/callback', to: 'sessions#create'
+
+And I might then have a `SessionsController` with code that looks
+something like this:
+
+ class SessionsController < ApplicationController
+ def create
+ @user = ̈User.find_or_create_from_auth_hash(auth_hash)
+ self.current_user = @user
+ redirect_to '/'
+ end
+
+ 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.
Please sign in to comment.
Something went wrong with that request. Please try again.