OAuth 2.0 Provider Engine

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.

Installation

For the OAuth 2.0 Provider Engine to work you need to have

Ruby 1.9.2 (use rvm to manage versions).
MongoDB.

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

$ rails s

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.

Users: list with all registered users.
Scopes: authorization scopes administration.
Accesses: clients that access the user’s data.
Clients: registered clients (third party application)

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.

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 name/name) or to an existing scope name.

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“

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.

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.

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.

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”.

OAuth 2.0 flows explained

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)

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

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"
}

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

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"
}

Going deep

If you are curious and you want to find more check the acceptance tests 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

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.

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 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:

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"
}

Getting additional access tokens

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"
}

Going deep

If you are curious and you want to find more check the acceptance tests 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

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.

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.

OauthClient: represents the credentials of a client application.
OauthToken: represents the token used to access user’s resources.
OauthAuthorizarion: represents the authorization token used to exchange an access token.
OauthAccess: represents the relation between a client and a user, whenever a user grant an authorization.
OauthDailyRequests: represents a daily request from the client on behalf of a specific user.

Basic authentication system

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.

Blocking system explained

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.

Testing solutions

Tests are made using Steak, Capybara and RSpec. If you want to know more check the tests about models and acceptance tests.

Other OAuth2 Ruby Implementations

Contributing

Follow MongoID guidelines

Authors

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.

Changelog

See CHANGELOG

License

Rest OAuth 2.0 Server is available under the MIT license.

OAuth 2.0 Provider Engine

Installation

Admin user definition

Scopes explained

Action specific values

Scope name values

Protect your resources

Client definition

Block clients

Granted Clients (aka accesses)

OAuth 2.0 flows explained

OAuth 2.0 for server-side web applications

Getting an access token

Getting additional access tokens

Going deep

OAuth 2.0 for client-side web applications

Getting a user’s permission

Getting additional access tokens

Going deep

OAuth 2.0 for native applications

Getting an access token

Getting additional access tokens

Going deep

How to use Access Token

Miscellaneous

OAuth 2.0 options

OAuth 2.0 Models

Basic authentication system

Blocking system explained

Testing solutions

Other OAuth2 documentation

Other OAuth2 Ruby Implementations

Contributing

Authors

Changelog

License