Skip to content
This repository
Newer
Older
100644 155 lines (123 sloc) 6.687 kb
7c9c8da1 » sferik
2011-12-17 Only show status of master branch
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]
94308463 » sferik
2011-12-17 Condense build status and dependency status [ci skip]
2
3 [travis]: http://travis-ci.org/intridea/omniauth
4 [gemnasium]: https://gemnasium.com/intridea/omniauth
aca30f34 » mbleigh
2011-09-03 Update README with 1.0 info
5
a22b677c » mbleigh
2011-11-02 Add breaking changes warning to README
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
5d2c3deb » mbleigh
2011-10-04 Update README
11 ## An Introduction
12
c345c7b9 » filiptepper
2011-12-28 fixed some typos in README.md
13 OmniAuth is a library that standardizes multi-provider authentication for
5d2c3deb » mbleigh
2011-10-04 Update README
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
e39dd81c » sferik
2011-12-01 Add dependency status [ci skip]
21 individually as RubyGems, and you can see a [community maintained list](https://github.com/intridea/omniauth/wiki/List-of-Strategies)
5d2c3deb » mbleigh
2011-10-04 Update README
22 on the wiki for this project.
23
78301c00 » mbleigh
2011-10-16 Add a bit of doc to Developer strategy.
24 One strategy, called `Developer`, is included with OmniAuth and provides
c345c7b9 » filiptepper
2011-12-28 fixed some typos in README.md
25 a completely insecure, non-production-usable strategy that directly
78301c00 » mbleigh
2011-10-16 Add a bit of doc to Developer strategy.
26 prompts a user for authentication information and then passes it
da328e96 » mbleigh
2011-10-18 Bump to 1.0.0.beta1
27 straight through. You can use it as a placeholder when you start
28 development and easily swap in other strategies later.
78301c00 » mbleigh
2011-10-16 Add a bit of doc to Developer strategy.
29
30 ## Getting Started
5d2c3deb » mbleigh
2011-10-04 Update README
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
e47942c7 » jjb
2011-11-09 pretty syntax highlighting, and removed an errant newline
37 ```ruby
38 require 'sinatra'
39 require 'omniauth'
5d2c3deb » mbleigh
2011-10-04 Update README
40
e47942c7 » jjb
2011-11-09 pretty syntax highlighting, and removed an errant newline
41 class MyApplication < Sinatra::Base
42 use Rack::Session
43 use OmniAuth::Strategies::Developer
44 end
45 ```
5d2c3deb » mbleigh
2011-10-04 Update README
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
e47942c7 » jjb
2011-11-09 pretty syntax highlighting, and removed an errant newline
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 ```
5d2c3deb » mbleigh
2011-10-04 Update README
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
e47942c7 » jjb
2011-11-09 pretty syntax highlighting, and removed an errant newline
88 ```ruby
89 match '/auth/:provider/callback', to: 'sessions#create'
90 ```
5d2c3deb » mbleigh
2011-10-04 Update README
91
92 And I might then have a `SessionsController` with code that looks
93 something like this:
94
e47942c7 » jjb
2011-11-09 pretty syntax highlighting, and removed an errant newline
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
5d2c3deb » mbleigh
2011-10-04 Update README
102
e47942c7 » jjb
2011-11-09 pretty syntax highlighting, and removed an errant newline
103 protected
5d2c3deb » mbleigh
2011-10-04 Update README
104
e47942c7 » jjb
2011-11-09 pretty syntax highlighting, and removed an errant newline
105 def auth_hash
106 request.env['omniauth.auth']
107 end
108 end
109 ```
5d2c3deb » mbleigh
2011-10-04 Update README
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
e39dd81c » sferik
2011-12-01 Add dependency status [ci skip]
123 ## <a name="resources"></a>Resources
5d2c3deb » mbleigh
2011-10-04 Update README
124
125 The [OmniAuth Wiki](https://github.com/intridea/omniauth/wiki) has
126 actively maintained in-depth documentation for OmniAuth. It should be
127 your first stop if you are wondering about a more in-depth look at
128 OmniAuth, how it works, and how to use it.
129
e39dd81c » sferik
2011-12-01 Add dependency status [ci skip]
130 ## <a name="versions"></a>Supported Ruby Versions
0e7ec7d6 » mbleigh
2011-11-02 Update README, remove rbx-1.9 since I don't know why it's failing.
131
132 OmniAuth is tested under 1.8.7, 1.9.2, 1.9.3, JRuby, Rubinius (1.8
133 mode), and Ruby Enterprise Edition.
134
e39dd81c » sferik
2011-12-01 Add dependency status [ci skip]
135 ## <a name="license"></a>License
5d2c3deb » mbleigh
2011-10-04 Update README
136
137 Copyright (c) 2011 Intridea, Inc.
138
e39dd81c » sferik
2011-12-01 Add dependency status [ci skip]
139 Permission is hereby granted, free of charge, to any person obtaining a
140 copy of this software and associated documentation files (the "Software"),
141 to deal in the Software without restriction, including without limitation
142 the rights to use, copy, modify, merge, publish, distribute, sublicense,
143 and/or sell copies of the Software, and to permit persons to whom the
5d2c3deb » mbleigh
2011-10-04 Update README
144 Software is furnished to do so, subject to the following conditions:
145
e39dd81c » sferik
2011-12-01 Add dependency status [ci skip]
146 The above copyright notice and this permission notice shall be included
5d2c3deb » mbleigh
2011-10-04 Update README
147 in all copies or substantial portions of the Software.
148
e39dd81c » sferik
2011-12-01 Add dependency status [ci skip]
149 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
5d2c3deb » mbleigh
2011-10-04 Update README
150 OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
e39dd81c » sferik
2011-12-01 Add dependency status [ci skip]
151 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
152 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
5d2c3deb » mbleigh
2011-10-04 Update README
153 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
e39dd81c » sferik
2011-12-01 Add dependency status [ci skip]
154 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
5d2c3deb » mbleigh
2011-10-04 Update README
155 DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.