OAuth 2.0 Provider Engine is a project that easily allows the generation of an OAuth 2.0 Server following the draft 13 of the OAuth 2.0 protocol with bearer tokens. 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.
For the OAuth 2.0 Provider Engine to work you need to have
-
Ruby 1.9.2 (use rvm to manage versions).
To create an oauth2 server from scratch:
$ gem install bundler $ git clone git://github.com/RailsApps/rails3-mongoid-devise.git $ cd rails3-mongoid-devise $ echo "" >> Gemfile $ echo "gem 'oauth2_provider_engine'" >> Gemfile $ bundle install
Add ‘mount Oauth2Provider::Engine, at: ’oauth’‘ to config/routes.rb Add `def admin?; true; end` to app/models/user.rb
$ rails s
Log in at localhost:3000/ All oauth administrations is at: localhost:3000/oauth
Log in and access the admin dashboard where you will find the following sections.
-
Accesses: clients that access the user’s data.
-
Clients: registered clients (third party application)
-
Scopes: authorization scopes administration.
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.
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.
To create a new scope click Create a new scope and you will get a simple form with two fields
-
Name: unique alphanumeric key that identify a scope.
-
Values: list of space separated alphanumeric strings, each of one refers to an action (built following the convention {controller name}/{action name}) or to an existing scope name.
Going a bit deeper you can define the accessible actions in two ways.
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”.
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“
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.
Last, you can make some actions public by using the exclude option.
before_filter :oauth_authorized, except: %w(index, show)
Every registered user can define a client (third party application). To do this access the dashboard and create your first client filling these fields.
-
Name: client name.
-
Siti URI: client web site URI.
-
Redirect URI: client redirect URI, used as callback after the user grant or deny the access.
-
Scope: one or more scope names, separated by spaces (limit the possible accesses a client can have). By default a
scope named “all” is set as default. For this reason follow the convention to call “all” the scope that give all accesses.
-
Info: additional information.
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.
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.
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”.
Today Rest OAuth 2.0 Server supports three flows of OAuth 2.0
-
The server-side flow for web applications with servers that can securely store persistent information (Authorization Code Flow)
-
The client-side flow for JavaScript applications running in a browser (Implicit Grant Flow)
-
The native application flow for desktop and mobile applications (Resource Owner Password Credentials Flow)
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.
This flow begins by sending the user to the authorization endpoint /oauth/authorization with the following query parameters
-
response_type (REQUIRED): always use “code” as response type
-
client_id (REQUIRED): client identifier (the URI of the client model)
-
redirect_uri (REQUIRED): callback URI to the client application
-
scope (REQUIRED): privileges given to the client
-
state (OPTIONAL): opaque value used by the client to maintain state between the request and callback
Here’s an example URL for a hypothetical app called “Example App” running on 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.
-
code (REQUIRED): authorization code (from the previous step)
-
grant_type (REQUIRED): always use “authorization_code” as grant type
-
client_id (REQUIRED): client identifier (in our case is the uri field of the client)
-
client_secred (REQUIRED): client secret code
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"
}
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
-
grant_type (REQUIRED): always use “refresh_token” as grant type
-
client_id (REQUIRED): client identifier (in our case is the uri field of the client)
-
client_secred (REQUIRED): client secret code
-
refresh_token (REQUIRED): refresh token previusly received
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"
}
If you are curious and you want to find more check the acceptance tests in the authorization token flow and refresh token context.
This flow is meant for JavaScript-based web applications that can’t maintain state over time (it includes also ActionScript and SilverLight).
This flow begins by sending the user to the authorization endpoint /oauth/authorization with the following query parameters
-
response_type (REQUIRED): always use “token” as response type
-
client_id (REQUIRED): client identifier (the uri of the client model)
-
redirect_uri (REQUIRED): callback URI to the client application
-
scope (REQUIRED): privileges given to the client
-
state (OPTIONAL): opaque value used by the client to maintain state between the request and callback
Here’s an example URL for a hypothetical app called “Example App” running on 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. This is done because the fragment URI can not be read from server side, but only from client-based applications.
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.
If you are curious and you want to find more check the acceptance tests in the implicit token flow and refresh implicit token flow context.
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.
The client should POST to the token endpoint /oauth/token along with the following params using the JSON format:
-
grant_type (REQUIRED): always use “password” as grant type
-
username (REQUIRED): resource owner email address
-
password (REQUIRED): resource owner password
-
client_id (REQUIRED): client identifier (the uri of the client model)
-
redirect_uri (REQUIRED): callback URI to the client application
-
scope (REQUIRED): privileges given to the client
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"
}
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
-
grant_type (REQUIRED): always use “refresh_token” as grant type
-
client_id (REQUIRED): client identifier (in our case is the uri field of the client)
-
client_secred (REQUIRED): client secret code
-
refresh_token (REQUIRED): refresh token previusly received
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"
}
If you are curious and you want to find more check the acceptance tests in the password credentials flow and refresh token context.
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.
Rest OAuth 2.0 Server allows you to personalize some options changing oauth.yml
-
token_expires_in: define the seconds after which the access token expires.
-
authorization_expires_in: define the seconds after which the authorization code expires.
-
secure_random: define the lenght of tokens, code and secret keys.
-
scope_separator: define the separator used between different scope keys.
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.
-
OauthClient: represents the credentials of a client application.
-
Token: represents the token used to access user’s resources.
-
OauthAuthorizarion: represents the authorization token used to exchange an access token.
-
Access: represents the relation between a client and a user, whenever a user grant an authorization.
-
DailyRequests: represents a daily request from the client on behalf of a specific user.
In addition to the models above there is a basic authentication system
-
User: represents the basic user authentication functionalities
-
UsersController: represents the user definition
-
SessionsController: represents the session definition
This model is kept simple on purpose, but you can easily change it with the authentication system you prefer like Authlogic, Devise or 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.
One important feature lie in the ability of to block a client. Rest OAuth 2.0 server enables you two possibilities:
-
Client block via
client.block!: used to block a not safe client for all users. -
User block a client via
access.block!: used when a user want to revoke any access to his resources to a specific client. -
User block an access token via
token.block!: used when a user logout from the client and want to revoke the token access.
In the first two cases it is possible to unblock the client using the unblock! method.
Tests are made using Steak, Capybara and RSpec. If you want to know more check the tests about models and acceptance tests.
If the way OAuth2 works is not clear, you can find great documentation on the web.
Follow MongoID guidelines
Andrea Reginato & The Lelylan Team
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.
See CHANGELOG
Rest OAuth 2.0 Server is available under the MIT license.