Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 523 lines (330 sloc) 23.677 kb
3fbfb55 @andreareginato Added help us message
andreareginato authored
1 http://github.com/Lelylan/rest-oauth2-server/raw/development/public/images/help-us.png
2
50dfa82 @andreareginato Updated help us message
andreareginato authored
3 {The Lelylan Team}[http://lelylan.com]
3fbfb55 @andreareginato Added help us message
andreareginato authored
4
5
4feefca @andreareginato Updated introduction description
andreareginato authored
6 = Rest OAuth 2.0 Server
c1f6b1d @andreareginato First version Oauth2
andreareginato authored
7
50a0818 @andreareginato Added screenshots documentation
andreareginato authored
8 <b>Rest OAuth 2.0 Server</b> is a project that easily allows the generation of an OAuth 2.0 Server following the {draft 13}[http://tools.ietf.org/html/draft-ietf-oauth-v2-13]
58d6854 @andreareginato updated implicit grant flow
andreareginato authored
9 of the OAuth 2.0 protocol with {bearer tokens}[http://tools.ietf.org/html/draft-ietf-oauth-v2-bearer-02]. The spec
10 is close to settling down, and we intend to update our code to match the final OAuth 2.0 and bearer token standards.
11 OAuth has often been described as a "valet key for the web." It lets applications ask users for access to just the
12 data they need and no more, giving them the ability to enable and disable the accesses whenever they want, most of
13 the time without sharing their secret credentials.
2f51b3b @andreareginato New basic documentation
andreareginato authored
14
c201f69 @andreareginato Completed new version documentation
andreareginato authored
15
16 = Installation
17
18 For the Rest OAuth 2.0 Server to work you need to have
19
50a0818 @andreareginato Added screenshots documentation
andreareginato authored
20 * {Ruby 1.9.2}[www.ruby-lang.org/en/] (use rvm[http://screencasts.org/episodes/how-to-use-rvm?utm_source=rubyweekly&utm_medium=email] to manage versions).
c201f69 @andreareginato Completed new version documentation
andreareginato authored
21 * {MongoDB}[http://www.mongodb.org/].
22
50a0818 @andreareginato Added screenshots documentation
andreareginato authored
23 To install the project run the following commands (remember to run <tt>$ mongod</tt> before)
c201f69 @andreareginato Completed new version documentation
andreareginato authored
24
25 $ git clone git@github.com:Lelylan/rest-oauth2-server.git
26 $ cd rest-oauth2-server
27 $ bundle install
28 $ rake spec
29 $ rails s
30
50a0818 @andreareginato Added screenshots documentation
andreareginato authored
31 If everything works fine, you have your OAuth 2.0 Server up and running! We are also working at a gem and a
7a08c57 @andreareginato Admin registration documentation complete
andreareginato authored
32 generator to easily integrate the Rest OAuth 2.0 server into your project, so stay tuned.
c201f69 @andreareginato Completed new version documentation
andreareginato authored
33
34
35 == Admin user definition
36
624359e @andreareginato Completed user admin definition section
andreareginato authored
37 When accessing the application for the first time, click to sign up. A message will ask you to create the first
38 administrator user as no one have been found.
c201f69 @andreareginato Completed new version documentation
andreareginato authored
39
b9c1533 @andreareginato Admin registration documentation complete
andreareginato authored
40 http://github.com/Lelylan/rest-oauth2-server/raw/development/public/images/screenshots/first-user-creation.png
7a08c57 @andreareginato Admin registration documentation complete
andreareginato authored
41
42 Register, log in and access the admin dashboard where you will find the following sections.
43
44 * <b>Users</b>: list with all registered users.
45 * <b>Scopes</b>: authorization scopes administration.
46 * <b>Accesses</b>: clients that access the user's data.
c201f69 @andreareginato Completed new version documentation
andreareginato authored
47 * <b>Clients</b>: registered clients (third party application)
48
7a08c57 @andreareginato Admin registration documentation complete
andreareginato authored
49 While the Users and Scopes sections are visible only to the admin, Accesses and Clients are available to every
50 registered user, also the ones that will grant access for their resources. To better understand what you can do
51 explore the Dashboard and read the following sections.
52
b9c1533 @andreareginato Admin registration documentation complete
andreareginato authored
53 http://github.com/Lelylan/rest-oauth2-server/raw/development/public/images/screenshots/admin-dashboard.png
c201f69 @andreareginato Completed new version documentation
andreareginato authored
54
55
56 == Scopes explained
57
f2a1879 @andreareginato Scope documentation with images
andreareginato authored
58 In a short way, scopes tell you <b>what can and can't be accessed</b>. The Rest OAuth 2.0 Server ships with a
b9d8b17 @andreareginato Added documentation to scope explained
andreareginato authored
59 flexible and powerful scope system which can be dynamically built.
c201f69 @andreareginato Completed new version documentation
andreareginato authored
60
0b13bff @andreareginato Scope documentation with images
andreareginato authored
61 http://github.com/Lelylan/rest-oauth2-server/raw/development/public/images/screenshots/scopes.png
c201f69 @andreareginato Completed new version documentation
andreareginato authored
62
f2a1879 @andreareginato Scope documentation with images
andreareginato authored
63 To create a new scope click <b>Create a new scope</b> and you will get a simple form with two fields
64
65 * <b>Name</b>: unique alphanumeric key that identify a scope.
5416265 @andreareginato Scope documentation with images
andreareginato authored
66 * <b>Values</b>: list of space separated alphanumeric strings, each of one refers to an action (built following the convention <b>{controller name}/{action name}</b>) or to an existing scope name.
c201f69 @andreareginato Completed new version documentation
andreareginato authored
67
b9d8b17 @andreareginato Added documentation to scope explained
andreareginato authored
68 Going a bit deeper you can define the accessible actions in two ways.
89e58dc @andreareginato Added documentation to scope explained
andreareginato authored
69
1003e84 @andreareginato Added documentation to scope explained
andreareginato authored
70 === Action specific values
71
72 You can specify *any* action present in your rails app. For example if you want to allow the access to the action
73 create in the controller pizzas you just add the string "pizzas/create". Here you can see an example on defining the
74 access to all RESTful actions in a sample pizzas controller.
89e58dc @andreareginato Added documentation to scope explained
andreareginato authored
75
76 http://github.com/Lelylan/rest-oauth2-server/raw/development/public/images/screenshots/pizzas-scope.png
77
1003e84 @andreareginato Added documentation to scope explained
andreareginato authored
78 === Scope name values
79
80 You can specify any group of actions adding a name scope. For example if the scope pizzas allows the access to all
81 actions in the pizzas controller and the scope pastas allow the access to all actions in pastas controller, then the
82 "all" "cope could have as values the list "pizzas pastas"
89e58dc @andreareginato Added documentation to scope explained
andreareginato authored
83
84 http://github.com/Lelylan/rest-oauth2-server/raw/development/public/images/screenshots/all-scope.png
85
c201f69 @andreareginato Completed new version documentation
andreareginato authored
86
49cee87 @andreareginato resource protection
andreareginato authored
87 == Protect your resources
c201f69 @andreareginato Completed new version documentation
andreareginato authored
88
49cee87 @andreareginato resource protection
andreareginato authored
89 After scopes are defined there is one more step. You need to protect the actions you want to authorize. To do thi
90 add the filter <tt>oauth_authorized</tt> in any controller you want to protect.
c201f69 @andreareginato Completed new version documentation
andreareginato authored
91
92 class PizzasController < ApplicationController
93 before_filter :oauth_authorized
94 ...
95
49cee87 @andreareginato resource protection
andreareginato authored
96 This filter verify if the client can access the specific action, regarding the scope that has been granted from the user.
97 You can also decide to protect all of your resources (they must accept JSON format) by uncommenting <tt>oauth_authorized</tt>
0bde792 @andreareginato resource protection
andreareginato authored
98 line in the {ApplicationController}[https://github.com/Lelylan/rest-oauth2-server/blob/master/app/controllers/application_controller.rb].
c201f69 @andreareginato Completed new version documentation
andreareginato authored
99
49cee87 @andreareginato resource protection
andreareginato authored
100 Last, you can make some actions public by using the <tt>exclude</tt> option.
c201f69 @andreareginato Completed new version documentation
andreareginato authored
101
49cee87 @andreareginato resource protection
andreareginato authored
102 before_filter :oauth_authorized, except: %w(index, show)
c201f69 @andreareginato Completed new version documentation
andreareginato authored
103
104
105 == Client definition
106
0bde792 @andreareginato resource protection
andreareginato authored
107 Every registered user can define a client (third party application). To do this access the dashboard and create your first
108 client filling these fields.
c201f69 @andreareginato Completed new version documentation
andreareginato authored
109
110 * <b>Name</b>: client name.
0bde792 @andreareginato resource protection
andreareginato authored
111 * <b>Siti URI</b>: client web site URI.
112 * <b>Redirect URI</b>: client redirect URI, used as callback after the user grant or deny the access.
20844e0 @andreareginato Added new documentation for scope tag and graph with accesses
andreareginato authored
113 * <b>Scope</b>: one or more scope names, separated by spaces (limit the possible accesses a client can have). By default a
114 scope named "all" is set as default. For this reason follow the convention to call "all" the scope that give all accesses.
0bde792 @andreareginato resource protection
andreareginato authored
115 * <b>Info</b>: additional information.
116
c22336f @andreareginato resource protection
andreareginato authored
117 Once the client is create the additional field <b>client uri</b> and <b>secret</b> are generated. You will use these info
118 later on, during the authorization flows.
119
120 http://github.com/Lelylan/rest-oauth2-server/raw/development/public/images/screenshots/client-show.png
c201f69 @andreareginato Completed new version documentation
andreareginato authored
121
d2fdb7f @andreareginato Added blocked client section
andreareginato authored
122 If you define a scope named <b>all</b> you can use one more functionality. You can click the button <b>Simulate Authorization</b>
63c2d4b @andreareginato Client documentation completes
andreareginato authored
123 that you can find in the end of the client detail page, and you will see the authorization page that a user would normally see
124 when granting access to a client.
125
126 http://github.com/Lelylan/rest-oauth2-server/raw/development/public/images/screenshots/authorization.png
127
c201f69 @andreareginato Completed new version documentation
andreareginato authored
128
d2fdb7f @andreareginato Added blocked client section
andreareginato authored
129 === Block clients
130
131 The admin can access to all created clients and decide to block any of them, meaning all related access tokens are disabled.
132 This is pretty useful in cases where a client is considered "not safe". When a client is blocked every authorization request
133 will be disabled, until the admin unblock it.
134
135 http://github.com/Lelylan/rest-oauth2-server/raw/development/public/images/screenshots/block-clients.png
c201f69 @andreareginato Completed new version documentation
andreareginato authored
136
137
d17c4bc @andreareginato Added access section with images and bearer token
andreareginato authored
138 == Granted Clients (aka accesses)
139
140 Once users grant the access to their resources, the accesses list is updated. Here a user can see which clients are accessing
141 their resources, and with which frequency. One important functionality lies on the possibility for a user to block a specific
142 client, whenever it is considered "not safe".
143
144 http://github.com/Lelylan/rest-oauth2-server/raw/development/public/images/screenshots/access.png
c201f69 @andreareginato Completed new version documentation
andreareginato authored
145
146
147
148
3fb1be3 @andreareginato small update on documentation order
andreareginato authored
149 = OAuth 2.0 flows explained
150
4feefca @andreareginato Updated introduction description
andreareginato authored
151 Today Rest OAuth 2.0 Server supports three flows of OAuth 2.0
152 * The server-side flow for web applications with servers that can securely store persistent information ({Authorization Code Flow}[http://tools.ietf.org/html/draft-ietf-oauth-v2-13#section-4.1])
cb10615 @andreareginato Final check documentation
andreareginato authored
153 * The client-side flow for JavaScript applications running in a browser ({Implicit Grant Flow}[http://tools.ietf.org/html/draft-ietf-oauth-v2-13#section-4.2])
154 * The native application flow for desktop and mobile applications ({Resource Owner Password Credentials Flow}[http://tools.ietf.org/html/draft-ietf-oauth-v2-13#section-4.3])
2f51b3b @andreareginato New basic documentation
andreareginato authored
155
c1f6b1d @andreareginato First version Oauth2
andreareginato authored
156
2d53227 @andreareginato Updated doc about server flow
andreareginato authored
157 == OAuth 2.0 for server-side web applications
d8b5984 @andreareginato initial description Authorization Code Flow
andreareginato authored
158
cb10615 @andreareginato Final check documentation
andreareginato authored
159 This flow is meant for web applications with servers that can keep secrets and maintain state.
d8b5984 @andreareginato initial description Authorization Code Flow
andreareginato authored
160
2d53227 @andreareginato Updated doc about server flow
andreareginato authored
161 The server-side flow has two parts. In the first part, your application asks the user for permission to access
162 their data. If the user approves, instead of sending an access token directly as in the client-side flow, the
cb10615 @andreareginato Final check documentation
andreareginato authored
163 Rest OAuth 2.0 Server will send to the client an authorization code. In the second part, the client will POST
cb0a806 @andreareginato Adde documentation on scope definition and resource protection
andreareginato authored
164 that code along with its client secret to the Rest OAuth 2.0 Server in order to get the access token.
36c3f52 @andreareginato Complete first step authorization code documentation
andreareginato authored
165
2d53227 @andreareginato Updated doc about server flow
andreareginato authored
166 === Getting an access token
e4c1625 @andreareginato Added implicit grant flow documentation
andreareginato authored
167
ff6ab9b @andreareginato Correct link doc
andreareginato authored
168 This flow begins by sending the user to the authorization endpoint <tt>/oauth/authorization</tt>
2d53227 @andreareginato Updated doc about server flow
andreareginato authored
169 with the following query parameters
aced9d3 @andreareginato Added second step in the authorization code flow
andreareginato authored
170
171 * <b>response_type</b> (REQUIRED): always use "code" as response type
cb0a806 @andreareginato Adde documentation on scope definition and resource protection
andreareginato authored
172 * <b>client_id</b> (REQUIRED): client identifier (the URI of the client model)
aced9d3 @andreareginato Added second step in the authorization code flow
andreareginato authored
173 * <b>redirect_uri</b> (REQUIRED): callback URI to the client application
cb10615 @andreareginato Final check documentation
andreareginato authored
174 * <b>scope</b> (REQUIRED): privileges given to the client
aced9d3 @andreareginato Added second step in the authorization code flow
andreareginato authored
175 * <b>state</b> (OPTIONAL): opaque value used by the client to maintain state between the request and callback
d8b5984 @andreareginato initial description Authorization Code Flow
andreareginato authored
176
2d53227 @andreareginato Updated doc about server flow
andreareginato authored
177 Here's an example URL for a hypothetical app called "Example App" running on https://www.example.com
178
822fc5c @andreareginato correct documentation on error code and authorization uri
andreareginato authored
179 http://localhost:3000/oauth/authorization?
2d53227 @andreareginato Updated doc about server flow
andreareginato authored
180 response_type=code&
181 client_id=http://localhost:3000/clients/a918F2fs3&
182 redirect_uri=httsp://www.example.com/callback&
183 scope=write&
184 state=2af5D3vds
36c3f52 @andreareginato Complete first step authorization code documentation
andreareginato authored
185
ec7c29b @andreareginato Added image to better explain flow
andreareginato authored
186 And this is what you should see.
187
188 http://github.com/Lelylan/rest-oauth2-server/raw/development/public/images/screenshots/authorization.png
189
2d53227 @andreareginato Updated doc about server flow
andreareginato authored
190 After the user approves access or chooses not to, we'll redirect to the <tt>redirect_uri</tt> you pass us. If the
191 user denies access, an error code is appended:
36c3f52 @andreareginato Complete first step authorization code documentation
andreareginato authored
192
822fc5c @andreareginato correct documentation on error code and authorization uri
andreareginato authored
193 https://example.com/callback?error=access_denied&state=2af5D3vds
e4c1625 @andreareginato Added implicit grant flow documentation
andreareginato authored
194
2d53227 @andreareginato Updated doc about server flow
andreareginato authored
195 If the user approves access will be appended an authorization code in the query string of the URL:
36c3f52 @andreareginato Complete first step authorization code documentation
andreareginato authored
196
cb10615 @andreareginato Final check documentation
andreareginato authored
197 https://example.com/callback?code=g2VDXwrT0S6iZeUeYQBYi2stxRy&state=2af5D3vds
36c3f52 @andreareginato Complete first step authorization code documentation
andreareginato authored
198
cb10615 @andreareginato Final check documentation
andreareginato authored
199 Now, the client reached through the <tt>redirect_uri</tt> should swap that authorization code for an access token by POSTing
ff6ab9b @andreareginato Correct link doc
andreareginato authored
200 it along the following params to the token endpoint <tt>/oauth/token</tt> using the JSON format.
aced9d3 @andreareginato Added second step in the authorization code flow
andreareginato authored
201
2d53227 @andreareginato Updated doc about server flow
andreareginato authored
202 * <b>code</b> (REQUIRED): authorization code (from the previous step)
203 * <b>grant_type</b> (REQUIRED): always use "authorization_code" as grant type
204 * <b>client_id</b> (REQUIRED): client identifier (in our case is the uri field of the client)
205 * <b>client_secred</b> (REQUIRED): client secret code
206
207 Using curl the request might look like:
208
59988ec @andreareginato Added resource owner password credential flow
andreareginato authored
209 curl -i http://localhost:3000/oauth/token \
54b13a3 @andreareginato Completed access token description
andreareginato authored
210 -H "Accept: application/json" \
2d53227 @andreareginato Updated doc about server flow
andreareginato authored
211 -X POST -d '{
9d6ddef @andreareginato minor changes
andreareginato authored
212 "code": "g2VDXwrT0S6iZeUeYQBYi2stxRy", \
213 "grant_type": "authorization_code", \
cb10615 @andreareginato Final check documentation
andreareginato authored
214 "client_id": "http://localhost:30000/clients/a918F2fs3", \
7f01e15 @andreareginato Added new configuration params
andreareginato authored
215 "client_secret": "a34a7afe4731e745de9d61iZeUeY" \
2d53227 @andreareginato Updated doc about server flow
andreareginato authored
216 }'
54b13a3 @andreareginato Completed access token description
andreareginato authored
217
2d53227 @andreareginato Updated doc about server flow
andreareginato authored
218 The response is a JSON Object containing the access token:
54b13a3 @andreareginato Completed access token description
andreareginato authored
219
ed115b7 @andreareginato Added refresh token documentation
andreareginato authored
220 {
221 "access_token": "SlAV32hkKG",
222 "expires_in": 1800,
223 "refresh_token": "Da8i1930LSj"
224 }
225
226 === Getting additional access tokens
227
228 When your access token expires, Rest OAuth 2.0 Server API endpoints will respond with HTTP 401 Unauthorized. At any time,
229 you can use the token endpoint with your refresh token with the following query parameters
230
231 * <b>grant_type</b> (REQUIRED): always use "refresh_token" as grant type
232 * <b>client_id</b> (REQUIRED): client identifier (in our case is the uri field of the client)
233 * <b>client_secred</b> (REQUIRED): client secret code
234 * <b>refresh_token</b> (REQUIRED): refresh token previusly received
235
236 Using curl the request might look like:
237
238 curl -i http://localhost:3000/oauth/token \
239 -H "Accept: application/json" \
240 -X POST -d '{
241 "grant_type": "refresh_token", \
242 "refresh_token": "Da8i1930LSj", \
243 "client_id": "http://localhost:30000/clients/a918F2fs3", \
244 "client_secret": "a34a7afe4731e745de9d61iZeUeY" \
245 }'
246
247 The response is a JSON Object containing the new access token.
248
249 {
250 "access_token": "AlYZ892hsKs",
251 "expires_in": 1800,
252 "refresh_token": "Da8i1930LSj"
253 }
aced9d3 @andreareginato Added second step in the authorization code flow
andreareginato authored
254
d17c4bc @andreareginato Added access section with images and bearer token
andreareginato authored
255
72d61d0 @andreareginato Completed documentation
andreareginato authored
256 === Going deep
609969a @andreareginato Added documentation on acceptance test for the flows
andreareginato authored
257
c9f7526 @andreareginato Fixed broken links doc
andreareginato authored
258 If you are curious and you want to find more check the {acceptance}[https://github.com/Lelylan/rest-oauth2-server/blob/master/spec/acceptance/oauth/oauth_authorize_controller_spec.rb]
259 {tests}[https://github.com/Lelylan/rest-oauth2-server/blob/master/spec/acceptance/oauth/oauth_token_controller_spec.rb]
260 in the <b>authorization token flow</b> and <b>refresh token</b> context.
609969a @andreareginato Added documentation on acceptance test for the flows
andreareginato authored
261
e4c1625 @andreareginato Added implicit grant flow documentation
andreareginato authored
262
263
58d6854 @andreareginato updated implicit grant flow
andreareginato authored
264 == OAuth 2.0 for client-side web applications
e4c1625 @andreareginato Added implicit grant flow documentation
andreareginato authored
265
cb10615 @andreareginato Final check documentation
andreareginato authored
266 This flow is meant for JavaScript-based web applications that can't maintain state over time (it includes also ActionScript
267 and SilverLight).
58d6854 @andreareginato updated implicit grant flow
andreareginato authored
268
269 === Getting a user's permission
e4c1625 @andreareginato Added implicit grant flow documentation
andreareginato authored
270
cb10615 @andreareginato Final check documentation
andreareginato authored
271
ff6ab9b @andreareginato Correct link doc
andreareginato authored
272 This flow begins by sending the user to the authorization endpoint <tt>/oauth/authorization</tt>
58d6854 @andreareginato updated implicit grant flow
andreareginato authored
273 with the following query parameters
e4c1625 @andreareginato Added implicit grant flow documentation
andreareginato authored
274
275 * <b>response_type</b> (REQUIRED): always use "token" as response type
cb10615 @andreareginato Final check documentation
andreareginato authored
276 * <b>client_id</b> (REQUIRED): client identifier (the uri of the client model)
e4c1625 @andreareginato Added implicit grant flow documentation
andreareginato authored
277 * <b>redirect_uri</b> (REQUIRED): callback URI to the client application
cb10615 @andreareginato Final check documentation
andreareginato authored
278 * <b>scope</b> (REQUIRED): privileges given to the client
e4c1625 @andreareginato Added implicit grant flow documentation
andreareginato authored
279 * <b>state</b> (OPTIONAL): opaque value used by the client to maintain state between the request and callback
280
ef6dbe6 @andreareginato updated implicit grant flow
andreareginato authored
281 Here's an example URL for a hypothetical app called "Example App" running on https://www.example.com
e4c1625 @andreareginato Added implicit grant flow documentation
andreareginato authored
282
822fc5c @andreareginato correct documentation on error code and authorization uri
andreareginato authored
283 http://localhost:3000/oauth/authorization?
58d6854 @andreareginato updated implicit grant flow
andreareginato authored
284 response_type=token&
285 client_id=http://localhost:3000/clients/a918F2fs3&
ef6dbe6 @andreareginato updated implicit grant flow
andreareginato authored
286 redirect_uri=httsp://www.example.com/callback&
58d6854 @andreareginato updated implicit grant flow
andreareginato authored
287 scope=write&
288 state=2af5D3vds
289
ec7c29b @andreareginato Added image to better explain flow
andreareginato authored
290 And this is what you should see.
291
292 http://github.com/Lelylan/rest-oauth2-server/raw/development/public/images/screenshots/authorization.png
293
2d53227 @andreareginato Updated doc about server flow
andreareginato authored
294 After the user approves access or chooses not to, we'll redirect to the <tt>redirect_uri</tt> you pass. If the
58d6854 @andreareginato updated implicit grant flow
andreareginato authored
295 user denies access, an error code is appended:
e4c1625 @andreareginato Added implicit grant flow documentation
andreareginato authored
296
822fc5c @andreareginato correct documentation on error code and authorization uri
andreareginato authored
297 https://example.com/callback#error=access_denied&state=2af5D3vds
e4c1625 @andreareginato Added implicit grant flow documentation
andreareginato authored
298
2d53227 @andreareginato Updated doc about server flow
andreareginato authored
299 If the user approves will be appended an access token in the hash fragment of the UR:
58d6854 @andreareginato updated implicit grant flow
andreareginato authored
300
ed115b7 @andreareginato Added refresh token documentation
andreareginato authored
301 https://example.com/callback#token=g2VDXwrT0S6iZeUeYQBYi2stxRy&expires_in=1800&state=2af5D3vds
58d6854 @andreareginato updated implicit grant flow
andreareginato authored
302
cb10615 @andreareginato Final check documentation
andreareginato authored
303 JavaScript running on that page can grab that access token from the <tt>window.location.hash</tt> and either store it in a
304 cookie or POST it to a server. Note that the token is added to the {fragment URI}[http://en.wikipedia.org/wiki/Fragment_identifier].
305 This is done because the fragment URI can not be read from server side, but only from client-based applications.
2d53227 @andreareginato Updated doc about server flow
andreareginato authored
306
ed115b7 @andreareginato Added refresh token documentation
andreareginato authored
307 === Getting additional access tokens
308
309 When your access token expires, our API endpoints will respond with HTTP 401 Unauthorized. At any time, you can send
310 your user to the same authorization endpoint you used in the previous step. If the user has already authorized your
311 application for the scopes you're requesting, Rest OAuth Server won't show the OAuth dialog and will immediately redirect
312 to the <tt>redirect_uri</tt> you pass us with a new access token.
313
609969a @andreareginato Added documentation on acceptance test for the flows
andreareginato authored
314 === Going deep
315
c9f7526 @andreareginato Fixed broken links doc
andreareginato authored
316 If you are curious and you want to find more check the {acceptance tests}[https://github.com/Lelylan/rest-oauth2-server/blob/master/spec/acceptance/oauth/oauth_authorize_controller_spec.rb]
08b3387 @andreareginato Corretion typo on documentation
andreareginato authored
317 in the <b>implicit token flow</b> and <b>refresh implicit token flow</b> context.
609969a @andreareginato Added documentation on acceptance test for the flows
andreareginato authored
318
e4c1625 @andreareginato Added implicit grant flow documentation
andreareginato authored
319
320
3c7ac7e @andreareginato rewritten documentation to make it easier
andreareginato authored
321 == OAuth 2.0 for native applications
59988ec @andreareginato Added resource owner password credential flow
andreareginato authored
322
cb10615 @andreareginato Final check documentation
andreareginato authored
323 This flow is meant for mobile, and desktop installed applications that want access to user data (native apps).
59988ec @andreareginato Added resource owner password credential flow
andreareginato authored
324
3c7ac7e @andreareginato rewritten documentation to make it easier
andreareginato authored
325 This flow is suitable in cases where the resource owner has a trust relationship with the client, such as its computer operating
326 system or a highly privileged application. The authorization server should take special care when enabling the grant type, and
f3b7b5b @andreareginato minor changes
andreareginato authored
327 <b>only when other flows are not viable</b>, because username and password are shared with the client.
59988ec @andreareginato Added resource owner password credential flow
andreareginato authored
328
3c7ac7e @andreareginato rewritten documentation to make it easier
andreareginato authored
329 === Getting an access token
59988ec @andreareginato Added resource owner password credential flow
andreareginato authored
330
ff6ab9b @andreareginato Correct link doc
andreareginato authored
331 The client should POST to the token endpoint <tt>/oauth/token</tt> along with the following params
cb10615 @andreareginato Final check documentation
andreareginato authored
332 using the JSON format:
59988ec @andreareginato Added resource owner password credential flow
andreareginato authored
333
334 * <b>grant_type</b> (REQUIRED): always use "password" as grant type
cb10615 @andreareginato Final check documentation
andreareginato authored
335 * <b>username</b> (REQUIRED): resource owner email address
59988ec @andreareginato Added resource owner password credential flow
andreareginato authored
336 * <b>password</b> (REQUIRED): resource owner password
cb10615 @andreareginato Final check documentation
andreareginato authored
337 * <b>client_id</b> (REQUIRED): client identifier (the uri of the client model)
3c7ac7e @andreareginato rewritten documentation to make it easier
andreareginato authored
338 * <b>redirect_uri</b> (REQUIRED): callback URI to the client application
cb10615 @andreareginato Final check documentation
andreareginato authored
339 * <b>scope</b> (REQUIRED): privileges given to the client
59988ec @andreareginato Added resource owner password credential flow
andreareginato authored
340
3c7ac7e @andreareginato rewritten documentation to make it easier
andreareginato authored
341 Using curl the request might look like:
342
343 curl -i http://localhost:3000/oauth/token \
344 -H "Accept: application/json" \
345 -X POST -d '{
346 "grant_type": "password", \
cb10615 @andreareginato Final check documentation
andreareginato authored
347 "client_id": "http://localhost:3000/clients/a918F2fs3", \
3c7ac7e @andreareginato rewritten documentation to make it easier
andreareginato authored
348 "client_secret": "a34a7afe4731e745de9d61iZeUeY", \
349 "username": "alice@example.com", \
350 "password": "example", \
7f01e15 @andreareginato Added new configuration params
andreareginato authored
351 "scope": "write" \
3c7ac7e @andreareginato rewritten documentation to make it easier
andreareginato authored
352 }'
353
354 The response is a JSON Object containing the access token:
59988ec @andreareginato Added resource owner password credential flow
andreareginato authored
355
ed115b7 @andreareginato Added refresh token documentation
andreareginato authored
356 {
357 "access_token": "AlYZ892hsKs",
358 "expires_in": 1800,
359 "refresh_token": "Da8i1930LSj"
360 }
361
362 === Getting additional access tokens
363
364 When your access token expires, Rest OAuth 2.0 Server API endpoints will respond with HTTP 401 Unauthorized. At any time,
365 you can use the token endpoint with your refresh token with the following query parameters
366
367 * <b>grant_type</b> (REQUIRED): always use "refresh_token" as grant type
368 * <b>client_id</b> (REQUIRED): client identifier (in our case is the uri field of the client)
369 * <b>client_secred</b> (REQUIRED): client secret code
370 * <b>refresh_token</b> (REQUIRED): refresh token previusly received
371
372 Using curl the request might look like:
373
374 curl -i http://localhost:3000/oauth/token \
375 -H "Accept: application/json" \
376 -X POST -d '{
377 "grant_type": "refresh_token", \
378 "refresh_token": "Da8i1930LSj", \
379 "client_id": "http://localhost:30000/clients/a918F2fs3", \
380 "client_secret": "a34a7afe4731e745de9d61iZeUeY" \
381 }'
382
383 The response is a JSON Object containing the new access token.
384
385 {
386 "access_token": "AlYZ892hsKs",
387 "expires_in": 1800,
388 "refresh_token": "Da8i1930LSj"
389 }
59988ec @andreareginato Added resource owner password credential flow
andreareginato authored
390
609969a @andreareginato Added documentation on acceptance test for the flows
andreareginato authored
391 === Going deep
392
c9f7526 @andreareginato Fixed broken links doc
andreareginato authored
393 If you are curious and you want to find more check the {acceptance tests}[https://github.com/Lelylan/rest-oauth2-server/blob/master/spec/acceptance/oauth/oauth_token_controller_spec.rb]
08b3387 @andreareginato Corretion typo on documentation
andreareginato authored
394 in the <b>password credentials flow</b> and <b>refresh token</b> context.
59988ec @andreareginato Added resource owner password credential flow
andreareginato authored
395
396
cb0a806 @andreareginato Adde documentation on scope definition and resource protection
andreareginato authored
397
72d61d0 @andreareginato Completed documentation
andreareginato authored
398 = How to use Access Token
399
400 To make API requests on the behalf of a user, pass the OAuth token in the query string, as a header, or as a parameter
401 in the request body when making a POST request.
402
403 Query string example.
404
405 GET /pizzas?token=AlYZ892hsKs
406
407 Header example.
408
409 GET /pizzas
410 Authorization: OAuth2 AlYZ892hsKs
411
412 Request body example.
413
414 POST /pizzas
3afb8b4 @andreareginato Corretion typo on documentation
andreareginato authored
415 token=AlYZ892hsKs&...
72d61d0 @andreareginato Completed documentation
andreareginato authored
416
417 Note that all requests must be done using HTTPS.
418
419
420
c201f69 @andreareginato Completed new version documentation
andreareginato authored
421 = Miscellaneous
cb0a806 @andreareginato Adde documentation on scope definition and resource protection
andreareginato authored
422
c201f69 @andreareginato Completed new version documentation
andreareginato authored
423 == OAuth 2.0 options
9fd9de6 @andreareginato Added options documentation
andreareginato authored
424
0a06a4c @andreareginato Fixed broken links doc
andreareginato authored
425 Rest OAuth 2.0 Server allows you to personalize some options changing {oauth.yml}[https://github.com/Lelylan/rest-oauth2-server/blob/master/config/oauth.yml]
9fd9de6 @andreareginato Added options documentation
andreareginato authored
426
7f01e15 @andreareginato Added new configuration params
andreareginato authored
427 * <b>token_expires_in</b>: define the seconds after which the access token expires.
428 * <b>authorization_expires_in</b>: define the seconds after which the authorization code expires.
429 * <b>secure_random</b>: define the lenght of tokens, code and secret keys.
cb0a806 @andreareginato Adde documentation on scope definition and resource protection
andreareginato authored
430 * <b>scope_separator</b>: define the separator used between different scope keys.
431
432
c201f69 @andreareginato Completed new version documentation
andreareginato authored
433 == OAuth 2.0 Models
a5dd7ae @andreareginato Added model definition
andreareginato authored
434
ec4de25 @andreareginato local file linkage
andreareginato authored
435 Rest OAuth 2.0 Server is working on top of 5 models. They are pretty simple so if you want to have more information about
436 them, check the source code, which is clearly documented.
437
6d66e13 @andreareginato Fixed broken links doc
andreareginato authored
438 * {OauthClient}[https://github.com/Lelylan/rest-oauth2-server/blob/master/app/models/client.rb]: represents the credentials of a client application.
0a06a4c @andreareginato Fixed broken links doc
andreareginato authored
439 * {OauthToken}[https://github.com/Lelylan/rest-oauth2-server/blob/master/app/models/oauth/oauth_token.rb]: represents the token used to access user's resources.
440 * {OauthAuthorizarion}[https://github.com/Lelylan/rest-oauth2-server/blob/master/app/models/oauth/oauth_authorization.rb]: represents the authorization token used to exchange an access token.
441 * {OauthAccess}[https://github.com/Lelylan/rest-oauth2-server/blob/master/app/models/oauth/oauth_access.rb]: represents the relation between a client and a user, whenever a user grant an authorization.
442 * {OauthDailyRequests}[https://github.com/Lelylan/rest-oauth2-server/blob/master/app/models/oauth/oauth_daily_request.rb]: represents a daily request from the client on behalf of a specific user.
ec4de25 @andreareginato local file linkage
andreareginato authored
443
5bf5e5f @andreareginato added block! method documentation
andreareginato authored
444
0a06a4c @andreareginato Fixed broken links doc
andreareginato authored
445 == Basic authentication system
5bf5e5f @andreareginato added block! method documentation
andreareginato authored
446
447 In addition to the models above there is a basic authentication system
448
0a06a4c @andreareginato Fixed broken links doc
andreareginato authored
449 * {User}[https://github.com/Lelylan/rest-oauth2-server/blob/master/app/models/user.rb]: represents the basic user authentication functionalities
450 * {UsersController}[https://github.com/Lelylan/rest-oauth2-server/blob/master/app/controllers/users_controller.rb]: represents the user definition
451 * {SessionsController}[https://github.com/Lelylan/rest-oauth2-server/blob/master/app/controllers/sessions_controller.rb]: represents the session definition
5bf5e5f @andreareginato added block! method documentation
andreareginato authored
452
c201f69 @andreareginato Completed new version documentation
andreareginato authored
453 This model is kept simple on purpose, but you can easily change it with the authentication system you prefer like {Authlogic}[https://github.com/binarylogic/authlogic],
2d008db @andreareginato small changes on doc
andreareginato authored
454 {Devise}[https://github.com/plataformatec/devise] or {Warden}[https://github.com/hassox/warden]. Just remember that your user model <b>must</b>
c201f69 @andreareginato Completed new version documentation
andreareginato authored
455 define an <tt>uri</tt> field, which is used as identifier on the OAuth 2.0 flows. Any help on integration is appreciated.
5bf5e5f @andreareginato added block! method documentation
andreareginato authored
456
a5dd7ae @andreareginato Added model definition
andreareginato authored
457
c201f69 @andreareginato Completed new version documentation
andreareginato authored
458 == Blocking system explained
a5dd7ae @andreareginato Added model definition
andreareginato authored
459
5bf5e5f @andreareginato added block! method documentation
andreareginato authored
460 One important feature lie in the ability of to block a client. Rest OAuth 2.0 server enables you two possibilities:
461
2c9dd29 @andreareginato minor changes
andreareginato authored
462 * <b>Client block</b> via <tt>client.block!</tt>: used to block a not safe client for all users.
463 * <b>User block a client</b> via <tt>access.block!</tt>: used when a user want to revoke any access to his resources to a specific client.
464 * <b>User block an access token</b> via <tt>token.block!</tt>: used when a user logout from the client and want to revoke the token access.
b0f943c @andreareginato Added logout with token.block
andreareginato authored
465
466 In the first two cases it is possible to unblock the client using the <tt>unblock!</tt> method.
a5dd7ae @andreareginato Added model definition
andreareginato authored
467
468
c201f69 @andreareginato Completed new version documentation
andreareginato authored
469 == Testing solutions
a5dd7ae @andreareginato Added model definition
andreareginato authored
470
c201f69 @andreareginato Completed new version documentation
andreareginato authored
471 Tests are made using {Steak}[https://github.com/cavalle/steak], {Capybara}[https://github.com/jnicklas/capybara]
91fd864 @andreareginato Corretion typo on documentation
andreareginato authored
472 and {RSpec}[https://github.com/rspec/rspec-rails]. If you want to know more check the tests about {models}[https://github.com/Lelylan/rest-oauth2-server/tree/development/spec/models]
78701db @andreareginato Corretion typo on documentation
andreareginato authored
473 and {acceptance tests}[https://github.com/Lelylan/rest-oauth2-server/tree/development/spec/acceptance].
b9e6b86 @andreareginato Added info on testing solution
andreareginato authored
474
475
a5dd7ae @andreareginato Added model definition
andreareginato authored
476
3c7ac7e @andreareginato rewritten documentation to make it easier
andreareginato authored
477 = Other OAuth2 documentation
cc01c1e @andreareginato Added links to other documentation
andreareginato authored
478
479 If the way OAuth2 works is not clear, you can find great documentation on the web.
480
481 * {Oauth2 Specifications}[http://tools.ietf.org/html/draft-ietf-oauth-v2-13]
482 * {Google OAuth2}[http://code.google.com/apis/accounts/docs/OAuth2.html]
483 * {Facebook OAuth2}[http://developers.facebook.com/docs/authentication]
484 * {Gowalla OAuth2}[http://gowalla.com/api/docs/oauth]
485 * {Foursquare OAuth2}[http://developer.foursquare.com/docs/oauth.html]
486 * {Instagram OAuth2}[http://instagram.com/developer/auth/]
487
c1f6b1d @andreareginato First version Oauth2
andreareginato authored
488
3c7ac7e @andreareginato rewritten documentation to make it easier
andreareginato authored
489
9d83bfd @andreareginato minor doc changes
andreareginato authored
490 = Other OAuth2 Ruby Implementations
36c3f52 @andreareginato Complete first step authorization code documentation
andreareginato authored
491
cc01c1e @andreareginato Added links to other documentation
andreareginato authored
492 * {Flowtown Rack OAuth2 Server}[https://github.com/flowtown/rack-oauth2-server]
493 * {Nov Rack OAuth2}[https://github.com/nov/rack-oauth2]
494 * {ThoughWorks OAuth2 Provider}[https://github.com/ThoughtWorksStudios/oauth2_provider]
495 * {Freerange OAuth2 Provider}[https://github.com/freerange/oauth2-provider/blob/master/lib/oauth2/provider/models/access_token.rb]
36c3f52 @andreareginato Complete first step authorization code documentation
andreareginato authored
496
3c7ac7e @andreareginato rewritten documentation to make it easier
andreareginato authored
497
498
c201f69 @andreareginato Completed new version documentation
andreareginato authored
499 = Contributing
cc01c1e @andreareginato Added links to other documentation
andreareginato authored
500
c201f69 @andreareginato Completed new version documentation
andreareginato authored
501 Follow {MongoID guidelines}[http://mongoid.org/docs/contributing.html]
cc01c1e @andreareginato Added links to other documentation
andreareginato authored
502
3c7ac7e @andreareginato rewritten documentation to make it easier
andreareginato authored
503
c201f69 @andreareginato Completed new version documentation
andreareginato authored
504 = Authors
3c7ac7e @andreareginato rewritten documentation to make it easier
andreareginato authored
505
a591a1f @andreareginato Updated contact references
andreareginato authored
506 {Andrea Reginato}[mailto:andrea.reginato@gmail.com] &
507 {The Lelylan Team}[http://lelylan.com]
c201f69 @andreareginato Completed new version documentation
andreareginato authored
508
509 A special thanks to the OAuth 2.0 specification team, to the Flowtown Rack Oauth2 Server which gave the
510 initial ideas of the project and to Google OAuth 2.0 specification for making them so clear to understand.
3c7ac7e @andreareginato rewritten documentation to make it easier
andreareginato authored
511
512
513
cc01c1e @andreareginato Added links to other documentation
andreareginato authored
514 = Changelog
c1f6b1d @andreareginato First version Oauth2
andreareginato authored
515
c201f69 @andreareginato Completed new version documentation
andreareginato authored
516 See {CHANGELOG}[link:blob/master/CHANGELOG.rdoc]
36c3f52 @andreareginato Complete first step authorization code documentation
andreareginato authored
517
cc01c1e @andreareginato Added links to other documentation
andreareginato authored
518
3c7ac7e @andreareginato rewritten documentation to make it easier
andreareginato authored
519
cc01c1e @andreareginato Added links to other documentation
andreareginato authored
520 = License
36c3f52 @andreareginato Complete first step authorization code documentation
andreareginato authored
521
c201f69 @andreareginato Completed new version documentation
andreareginato authored
522 Rest OAuth 2.0 Server is available under the MIT license.
Something went wrong with that request. Please try again.