Skip to content

HTTPS clone URL

Subversion checkout URL

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