Skip to content

HTTPS clone URL

Subversion checkout URL

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