Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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