Rest OAuth2 Server is a Rails 3 app that let you open up your API and manage end-user authentication and client application authorization implementing the OAuth 2.0 Specifications (draft 13).
= Rest OAuth 2.0 Server is dead
We are sorry to annunce that due to a lack of time rest oauth2 server is now without a mantainer. For this
reason we call the project dead and we suggest you to use more solid solution such as
{Doorkeeper}[https://github.com/applicake/doorkeeper] or {oPRO}[https://github.com/opro/opro].
Anyway, we still think this project can be helpful to understand how a OAuth2 server works so if interested in that
checkout the code and the whole documentation. It was really nice to have such good people collaborating on this project.
P.S. If you are interested about becoming the new mantainer of this project write us.
{The Lelylan Team}[http://lelylan.com]
= Desription
Rest OAuth 2.0 Server 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]
of the OAuth 2.0 protocol with {bearer tokens}[http://tools.ietf.org/html/draft-ietf-oauth-v2-bearer-02]. The spec
is close to settling down, and we intend to update our code to match the final OAuth 2.0 and bearer token standards.
OAuth has often been described as a “valet key for the web.” It lets applications ask users for access to just the
data they need and no more, giving them the ability to enable and disable the accesses whenever they want, most of
the time without sharing their secret credentials.
= Installation
For the Rest OAuth 2.0 Server to work you need to have
To install the project run the following commands (remember to run $ mongod before)
$ git clone [email protected]:lelylan/rest-oauth2-server.git
$ cd rest-oauth2-server
$ bundle install
$ rake spec
$ rails s
If everything works fine, you have your OAuth 2.0 Server up and running! We are also working at a gem and a
generator to easily integrate the Rest OAuth 2.0 server into your project, so stay tuned.
== Admin user definition
When accessing the application for the first time, click to sign up. A message will ask you to create the first
administrator user as no one have been found.
Register, log in and access the admin dashboard where you will find the following sections.
While the Users and Scopes sections are visible only to the admin, Accesses and Clients are available to every
registered user, also the ones that will grant access for their resources. To better understand what you can do
explore the Dashboard and read the following sections.
== Scopes explained
In a short way, scopes tell you what can and can’t be accessed. The Rest OAuth 2.0 Server ships with a
flexible and powerful scope system which can be dynamically built.
http://github.com/Lelylan/rest-oauth2-server/raw/development/public/images/screenshots/scopes.png
To create a new scope click Create a new scope and you will get a simple form with two fields
Going a bit deeper you can define the accessible actions in two ways.
=== Action specific values
You can specify any action present in your rails app. For example if you want to allow the access to the action
create in the controller pizzas you just add the string “pizzas/create”. Here you can see an example on defining the
access to all RESTful actions in a sample pizzas controller.
=== Scope name values
You can specify any group of actions adding a name scope. For example if the scope pizzas allows the access to all
actions in the pizzas controller and the scope pastas allow the access to all actions in pastas controller, then the
“all” "cope could have as values the list “pizzas pastas”
http://github.com/Lelylan/rest-oauth2-server/raw/development/public/images/screenshots/all-scope.png
== Protect your resources
After scopes are defined there is one more step. You need to protect the actions you want to authorize. To do thi
add the filter oauth_authorized in any controller you want to protect.
class PizzasController < ApplicationController
before_filter :oauth_authorized
…
This filter verify if the client can access the specific action, regarding the scope that has been granted from the user.
You can also decide to protect all of your resources (they must accept JSON format) by uncommenting oauth_authorized
line in the {ApplicationController}[https://github.com/Lelylan/rest-oauth2-server/blob/master/app/controllers/application_controller.rb].
Last, you can make some actions public by using the exclude option.
before_filter :oauth_authorized, except: %w(index, show)
== Client definition
Every registered user can define a client (third party application). To do this access the dashboard and create your first
client filling these fields.
Once the client is create the additional field client uri and secret are generated. You will use these info
later on, during the authorization flows.
If you define a scope named all you can use one more functionality. You can click the button Simulate Authorization
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
when granting access to a client.
=== Block clients
The admin can access to all created clients and decide to block any of them, meaning all related access tokens are disabled.
This is pretty useful in cases where a client is considered “not safe”. When a client is blocked every authorization request
will be disabled, until the admin unblock it.
== Granted Clients (aka accesses)
Once users grant the access to their resources, the accesses list is updated. Here a user can see which clients are accessing
their resources, and with which frequency. One important functionality lies on the possibility for a user to block a specific
client, whenever it is considered “not safe”.
http://github.com/Lelylan/rest-oauth2-server/raw/development/public/images/screenshots/access.png
= OAuth 2.0 flows explained
Today Rest OAuth 2.0 Server supports three flows of OAuth 2.0
== OAuth 2.0 for server-side web applications
This flow is meant for web applications with servers that can keep secrets and maintain state.
The server-side flow has two parts. In the first part, your application asks the user for permission to access
their data. If the user approves, instead of sending an access token directly as in the client-side flow, the
Rest OAuth 2.0 Server will send to the client an authorization code. In the second part, the client will POST
that code along with its client secret to the Rest OAuth 2.0 Server in order to get the access token.
=== Getting an access token
This flow begins by sending the user to the authorization endpoint /oauth/authorization
with the following query parameters
Here’s an example URL for a hypothetical app called “Example App” running on https://www.example.com
http://localhost:3000/oauth/authorization?
response_type=code&
client_id=http://localhost:3000/clients/a918F2fs3&
redirect_uri=httsp://www.example.com/callback&
scope=write&
state=2af5D3vds
And this is what you should see.
After the user approves access or chooses not to, we’ll redirect to the redirect_uri you pass us. If the
user denies access, an error code is appended:
https://example.com/callback?error=access_denied&state=2af5D3vds
If the user approves access will be appended an authorization code in the query string of the URL:
https://example.com/callback?code=g2VDXwrT0S6iZeUeYQBYi2stxRy&state=2af5D3vds
Now, the client reached through the redirect_uri should swap that authorization code for an access token by POSTing
it along the following params to the token endpoint /oauth/token using the JSON format.
Using curl the request might look like:
curl -i http://localhost:3000/oauth/token
-H “Accept: application/json”
-X POST -d ‘{
“code”: “g2VDXwrT0S6iZeUeYQBYi2stxRy”,
“grant_type”: “authorization_code”,
“client_id”: “http://localhost:30000/clients/a918F2fs3”,
“client_secret”: “a34a7afe4731e745de9d61iZeUeY”
}’
The response is a JSON Object containing the access token:
{
“access_token”: “SlAV32hkKG”,
“expires_in”: 1800,
“refresh_token”: “Da8i1930LSj”
}
=== Getting additional access tokens
When your access token expires, Rest OAuth 2.0 Server API endpoints will respond with HTTP 401 Unauthorized. At any time,
you can use the token endpoint with your refresh token with the following query parameters
Using curl the request might look like:
curl -i http://localhost:3000/oauth/token
-H “Accept: application/json”
-X POST -d ‘{
“grant_type”: “refresh_token”,
“refresh_token”: “Da8i1930LSj”,
“client_id”: “http://localhost:30000/clients/a918F2fs3”,
“client_secret”: “a34a7afe4731e745de9d61iZeUeY”
}’
The response is a JSON Object containing the new access token.
{
“access_token”: “AlYZ892hsKs”,
“expires_in”: 1800,
“refresh_token”: “Da8i1930LSj”
}
=== Going deep
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]
{tests}[https://github.com/Lelylan/rest-oauth2-server/blob/master/spec/acceptance/oauth/oauth_token_controller_spec.rb]
in the authorization token flow and refresh token context.
== OAuth 2.0 for client-side web applications
This flow is meant for JavaScript-based web applications that can’t maintain state over time (it includes also ActionScript
and SilverLight).
=== Getting a user’s permission
This flow begins by sending the user to the authorization endpoint /oauth/authorization
with the following query parameters
Here’s an example URL for a hypothetical app called “Example App” running on https://www.example.com
http://localhost:3000/oauth/authorization?
response_type=token&
client_id=http://localhost:3000/clients/a918F2fs3&
redirect_uri=httsp://www.example.com/callback&
scope=write&
state=2af5D3vds
And this is what you should see.
After the user approves access or chooses not to, we’ll redirect to the redirect_uri you pass. If the
user denies access, an error code is appended:
https://example.com/callback#error=access_denied&state=2af5D3vds
If the user approves will be appended an access token in the hash fragment of the UR:
https://example.com/callback#token=g2VDXwrT0S6iZeUeYQBYi2stxRy&expires_in=1800&state=2af5D3vds
JavaScript running on that page can grab that access token from the window.location.hash and either store it in a
cookie or POST it to a server. Note that the token is added to the {fragment URI}[http://en.wikipedia.org/wiki/Fragment_identifier].
This is done because the fragment URI can not be read from server side, but only from client-based applications.
=== Getting additional access tokens
When your access token expires, our API endpoints will respond with HTTP 401 Unauthorized. At any time, you can send
your user to the same authorization endpoint you used in the previous step. If the user has already authorized your
application for the scopes you’re requesting, Rest OAuth Server won’t show the OAuth dialog and will immediately redirect
to the redirect_uri you pass us with a new access token.
=== Going deep
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]
in the implicit token flow and refresh implicit token flow context.
== OAuth 2.0 for native applications
This flow is meant for mobile, and desktop installed applications that want access to user data (native apps).
This flow is suitable in cases where the resource owner has a trust relationship with the client, such as its computer operating
system or a highly privileged application. The authorization server should take special care when enabling the grant type, and
only when other flows are not viable, because username and password are shared with the client.
=== Getting an access token
The client should POST to the token endpoint /oauth/token along with the following params
using the JSON format:
Using curl the request might look like:
curl -i http://localhost:3000/oauth/token
-H “Accept: application/json”
-X POST -d ‘{
“grant_type”: “password”,
“client_id”: “http://localhost:3000/clients/a918F2fs3”,
“client_secret”: “a34a7afe4731e745de9d61iZeUeY”,
“username”: “[email protected]”,
“password”: “example”,
“scope”: “write”
}’
The response is a JSON Object containing the access token:
{
“access_token”: “AlYZ892hsKs”,
“expires_in”: 1800,
“refresh_token”: “Da8i1930LSj”
}
=== Getting additional access tokens
When your access token expires, Rest OAuth 2.0 Server API endpoints will respond with HTTP 401 Unauthorized. At any time,
you can use the token endpoint with your refresh token with the following query parameters
Using curl the request might look like:
curl -i http://localhost:3000/oauth/token
-H “Accept: application/json”
-X POST -d ‘{
“grant_type”: “refresh_token”,
“refresh_token”: “Da8i1930LSj”,
“client_id”: “http://localhost:30000/clients/a918F2fs3”,
“client_secret”: “a34a7afe4731e745de9d61iZeUeY”
}’
The response is a JSON Object containing the new access token.
{
“access_token”: “AlYZ892hsKs”,
“expires_in”: 1800,
“refresh_token”: “Da8i1930LSj”
}
=== Going deep
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]
in the password credentials flow and refresh token context.
= How to use Access Token
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
in the request body when making a POST request.
Query string example.
GET /pizzas?token=AlYZ892hsKs
Header example.
GET /pizzas
Authorization: OAuth2 AlYZ892hsKs
Request body example.
POST /pizzas
token=AlYZ892hsKs&…
Note that all requests must be done using HTTPS.
= Miscellaneous
== OAuth 2.0 options
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]
== OAuth 2.0 Models
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
them, check the source code, which is clearly documented.
== Basic authentication system
In addition to the models above there is a basic authentication system
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],
{Devise}[https://github.com/plataformatec/devise] or {Warden}[https://github.com/hassox/warden]. Just remember that your user model must
define an uri field, which is used as identifier on the OAuth 2.0 flows. Any help on integration is appreciated.
== Blocking system explained
One important feature lie in the ability of to block a client. Rest OAuth 2.0 server enables you two possibilities:
In the first two cases it is possible to unblock the client using the unblock! method.
== Testing solutions
Tests are made using {Steak}[https://github.com/cavalle/steak], {Capybara}[https://github.com/jnicklas/capybara]
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]
and {acceptance tests}[https://github.com/Lelylan/rest-oauth2-server/tree/development/spec/acceptance].
= Other OAuth2 documentation
If the way OAuth2 works is not clear, you can find great documentation on the web.
= Other OAuth2 Ruby Implementations
= Contributing
Follow {MongoID guidelines}[http://mongoid.org/docs/contributing.html]
= Authors
{Andrea Reginato}[mailto:[email protected]] &
{The Lelylan Team}[http://lelylan.com]
A special thanks to the OAuth 2.0 specification team, to the Flowtown Rack Oauth2 Server which gave the
initial ideas of the project and to Google OAuth 2.0 specification for making them so clear to understand.
= Changelog
See {CHANGELOG}[link:blob/master/CHANGELOG.rdoc]
= License
Rest OAuth 2.0 Server is available under the MIT license.
