From 5d2c3deb6a767aa2e5366ad9e4533ded8d82cb69 Mon Sep 17 00:00:00 2001 From: Michael Bleigh Date: Tue, 4 Oct 2011 12:40:53 -0500 Subject: [PATCH] Update README --- README.md | 149 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 111 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index da7f7d8..4369114 100644 --- a/README.md +++ b/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 -# License -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.