Skip to content
Newer
Older
100644 144 lines (111 sloc) 6.09 KB
c6e8f8a @sferik Switch up Markdown syntax for headers [ci skip]
sferik authored Aug 19, 2011
1 # OmniAuth: Standardized Multi-Provider Authentication
aca30f3 Update README with 1.0 info
Michael Bleigh authored Sep 3, 2011
2
5d2c3de Update README
Michael Bleigh authored Oct 4, 2011
3 ## An Introduction
4
5 OmniAuth is a libary that standardizes multi-provider authentication for
6 web applications. It was created to be powerful, flexible, and do as
7 little as possible. Any developer can create **strategies** for OmniAuth
8 that can authenticate users via disparate systems. OmniAuth strategies
9 have been created for everything from Facebook to LDAP.
10
11 In order to use OmniAuth in your applications, you will need to leverage
12 one or more strategies. These strategies are generally released
13 individually as RubyGems, and you can see a [community maintained list](https://github.com/intridea/omniauth/wiki/List-of-Strategies)
14 on the wiki for this project.
15
78301c0 Add a bit of doc to Developer strategy.
Michael Bleigh authored Oct 16, 2011
16 One strategy, called `Developer`, is included with OmniAuth and provides
17 a completely unsecure, non-production-usable strategy that directly
18 prompts a user for authentication information and then passes it
da328e9 Bump to 1.0.0.beta1
Michael Bleigh authored Oct 18, 2011
19 straight through. You can use it as a placeholder when you start
20 development and easily swap in other strategies later.
78301c0 Add a bit of doc to Developer strategy.
Michael Bleigh authored Oct 16, 2011
21
22 ## Getting Started
5d2c3de Update README
Michael Bleigh authored Oct 4, 2011
23
24 Each OmniAuth strategy is a Rack Middleware. That means that you can use
25 it the same way that you use any other Rack middleware. For example, to
26 use the built-in Developer strategy in a Sinatra application I might do
27 this:
28
29 require 'sinatra'
30 require 'omniauth'
31
32 class MyApplication < Sinatra::Base
33 use Rack::Session
34 use OmniAuth::Strategies::Developer
35 end
36
37 Because OmniAuth is built for *multi-provider* authentication, I may
38 want to leave room to run multiple strategies. For this, the built-in
39 `OmniAuth::Builder` class gives you an easy way to specify multiple
40 strategies. Note that there is **no difference** between the following
41 code and using each strategy individually as middleware. This is an
42 example that you might put into a Rails initializer at
43 `config/initializers/omniauth.rb`:
44
45 Rails.application.config.middleware.use OmniAuth::Builder do
46 provider :developer unless Rails.env.production?
47 provider :twitter, ENV['TWITTER_KEY'], ENV['TWITTER_SECRET']
48 end
49
50 You should look to the documentation for each provider you use for
51 specific initialization requirements.
52
53 ## Integrating OmniAuth Into Your Application
54
55 OmniAuth is an extremely low-touch library. It is designed to be a
56 black box that you can send your application's users into when you need
57 authentication and then get information back. OmniAuth was intentionally
58 built not to automatically associate with a User model or make
59 assumptions about how many authentication methods you might want to use
60 or what you might want to do with the data once a user has
61 authenticated. This makes OmniAuth incredibly flexible. To use OmniAuth,
62 you need only to redirect users to `/auth/:provider`, where `:provider`
63 is the name of the strategy (for example, `developer` or `twitter`).
64 From there, OmniAuth will take over and take the user through the
65 necessary steps to authenticate them with the chosen strategy.
66
67 Once the user has authenticated, what do you do next? OmniAuth simply
68 sets a special hash called the Authentication Hash on the Rack
69 environment of a request to `/auth/:provider/callback`. This hash
70 contains as much information about the user as OmniAuth was able to
71 glean from the utilized strategy. You should set up an endpoint in your
72 application that matches to the callback URL and then performs whatever
73 steps are necessary for your application. For example, in a Rails app I
74 would add a line in my `routes.rb` file like this:
75
76 match '/auth/:provider/callback', to: 'sessions#create'
77
78 And I might then have a `SessionsController` with code that looks
79 something like this:
80
81 class SessionsController < ApplicationController
82 def create
b11bd38 Fix weird character in README
Michael Bleigh authored Oct 16, 2011
83 @user = User.find_or_create_from_auth_hash(auth_hash)
5d2c3de Update README
Michael Bleigh authored Oct 4, 2011
84 self.current_user = @user
85 redirect_to '/'
86 end
87
88 protected
89
90 def auth_hash
91 request.env['omniauth.auth']
92 end
93 end
94
95 The `omniauth.auth` key in the environment hash gives me my
96 Authentication Hash which will contain information about the just
97 authenticated user including a unique id, the strategy they just used
98 for authentication, and personal details such as name and email address
99 as available. For an in-depth description of what the authentication
100 hash might contain, see the [Auth Hash Schema wiki page](https://github.com/intridea/omniauth/wiki/Auth-Hash-Schema).
101
102 Note that OmniAuth does not perform any actions beyond setting some
103 environment information on the callback request. It is entirely up to
104 you how you want to implement the particulars of your application's
105 authentication flow.
106
107 ## Resources
108
109 The [OmniAuth Wiki](https://github.com/intridea/omniauth/wiki) has
110 actively maintained in-depth documentation for OmniAuth. It should be
111 your first stop if you are wondering about a more in-depth look at
112 OmniAuth, how it works, and how to use it.
113
0e7ec7d Update README, remove rbx-1.9 since I don't know why it's failing.
Michael Bleigh authored Nov 2, 2011
114 ## Supported Rubies
115
116 OmniAuth is tested under 1.8.7, 1.9.2, 1.9.3, JRuby, Rubinius (1.8
117 mode), and Ruby Enterprise Edition.
118
119 [![CI Build
120 Status](http://secure.travis-ci.org/intridea/omniauth.png)](https://travis-ci.org/intridea/omniauth)
121
122
5d2c3de Update README
Michael Bleigh authored Oct 4, 2011
123 ## License
124
125 Copyright (c) 2011 Intridea, Inc.
126
127 Permission is hereby granted, free of charge, to any person obtaining a
128 copy of this software and associated documentation files (the "Software"),
129 to deal in the Software without restriction, including without limitation
130 the rights to use, copy, modify, merge, publish, distribute, sublicense,
131 and/or sell copies of the Software, and to permit persons to whom the
132 Software is furnished to do so, subject to the following conditions:
133
134 The above copyright notice and this permission notice shall be included
135 in all copies or substantial portions of the Software.
136
137 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
138 OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
139 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
140 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
141 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
142 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
143 DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.