Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
tree: cc01c1e783
Fetching contributors…

Octocat-spinner-32-eaf2f5

Cannot retrieve contributors at this time

file 210 lines (142 sloc) 9.991 kb

Rest OAuth 2 Server

Rest Oauth2 Server is a gem to easily create your OAuth2 Server so that you can start sharing your API in a secure way. The actual implementation is based on draft 13 and it allows you to obtain the access tokens using one of the following 3 flows

Installation

For the project to work, is required ruby 1.9.2 and MongoDB which is the default database system (we use the handy Mondoid library to access it). To install it clone the repository, install the gems with bundler and run the tests. If everything works correctly, you have your OAuth2 server working.

git clone git@github.com:Lelylan/rest-oauth2-server.git
bundle install
rake spec

We are working on a gem and a generator to easily integrate the OAuth server into your project. This is what we want to reach.

gem install rest-oauth2-server
rails g oauth2

How to use

Rest OAuth2 Server actually supports 3 authorization flows. Each of them can be used in specific situations and is important to use the correct one for the correct goal.

Authorization Code Flow (aka OAuth2 for server side app)

The Authorization Code is suitable for clients capable of maintaining their client credentials confidential (for authenticating with the authorization server) such as a client implemented on a secure server side. As a redirection-based flow, the client must be capable of interacting with typically a web browser and capable of receiving incoming requests from the authorization server. In greater detail, the authorization flow goes like this.

Authorization Code

The client construct the redirect URI to your {authorization endpoint}[localhost:3000/oauth/authorize] by adding the following parameters in the query component (to create a client go to the rails console and type Factory(:oauth_client), soon there will be a UI where you will be able to easily create your clients)

GET http://localhost:3000/oauth/authorize?
    response_type=code&
    client_id=http://localhost:3000/users/alic/clients/example&
    redirect_uri=http://example.com/callback&
    scope=write&
    state=2af5D3vds

Lets explain in detail the authorization request params

  • response_type (REQUIRED): always use “code” as response type

  • client_id (REQUIRED): client identifier (in our case is the uri field of the client model)

  • redirect_uri (REQUIRED): callback URI to the client application

  • scope (REQUIRED): privileges given to the client (TODO: make section)

  • state (OPTIONAL): opaque value used by the client to maintain state between the request and callback

In the authorization page the resource owner will be asked to grand or deny the access to the specific client for a specif scope. If the resource owner 'grant' the access, the client will get back an authorization code that will be used in a second step to have the access token, otherwise an error will be sent.

# The resource owner grants the access request
https://example.com/callback?code=g2VDXwrT0S6iZeUeYQBYi2stxRy&state=2af5D3vds

# The resource owner denies the access request
https://example.com/callback?access=denied&state=2af5D3vds

Access Token

Supposing the resource owner grant the access request, the client uses the authorization code to get the access token. This is done by making a POST request to the /oauth/token resource and by sending the following params in the JSON format.

curl -i http://localhost:3000/oauth/token \
     -H "Accept: application/json" \
     -X POST -d \ '{
        "code": "g2VDXwrT0S6iZeUeYQBYi2stxRy", \
        "grant_type": "authorization_code", \
        "client_id": "http://localhost:3000/users/alice/client/lelylan", \
        "client_secret": "a34a7afe4731e745de9d61iZeUeY", \
        "scope": "write" }'

Lets explain in detail the Access Token Request params

  • 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

The response is a JSON structure containing the final access token.

{ "access_token":"SlAV32hkKG" }

We are working on the definition of a refresh token mechanism to improve the OAuth security system

Implicit Grant Flow (aka OAuth2 for client side app)

The Implicit Grant flow is suitable for clients incapable of maintaining their client credentials confidential (for authenticating with the authorization server) such as client applications residing in a user-agent, typically implemented in a browser using a scripting language such as JavaScript or ActionScript. In greater detail, the authorization flow goes like this.

The client redirect the resource owner's user-agent to the {authorization endpoint}[localhost:3000/oauth/authorize] by adding the following parameters in the query component.

GET http://localhost:3000/oauth/authorize?
    response_type=token&
    client_id=http://localhost:3000/users/alic/clients/example&
    redirect_uri=http://example.com/callback&
    scope=write&
    state=2af5D3vds

Lets explain in detail the implicit request params

  • response_type (REQUIRED): always use “token” as response type

  • client_id (REQUIRED): client identifier (in our case is the uri field of the client model)

  • redirect_uri (REQUIRED): callback URI to the client application

  • scope (REQUIRED): privileges given to the client (TODO: make section)

  • state (OPTIONAL): opaque value used by the client to maintain state between the request and callback

In the authorization page the resource owner will be asked to grand or deny the access to the specific client for a specif scope. If the resource owner 'grant' the access, the client will get back the final access token that will be used to access the resource owner resources.

# The resource owner grants the access request
https://example.com/callback#token=g2VDXwrT0S6iZeUeYQBYi2stxRy&state=2af5D3vds

# The resource owner denies the access request
https://example.com/callback#access=denied&state=2af5D3vds

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 applications like Javascript and ActionScipt.

Resource Owner Password Credentials Flow (aka OAuth2 for native app)

The Resource Owner Password Credential 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.

To have the access token the client make a POST request to the /oauth/token resource by sending the username and password given from the resource owner, plus the following params in the JSON format.

curl -i http://localhost:3000/oauth/token \
     -H "Accept: application/json" \
     -X POST -d \ '{
        "grant_type": "password", \
        "client_id": "http://localhost:3000/users/alice/client/lelylan", \
        "client_secret": "a34a7afe4731e745de9d61iZeUeY", \
        "username": "alice@example.com", \
        "password": "example", \
        "scope": "write" }'
  • grant_type (REQUIRED): always use “password” as grant type

  • client_id (REQUIRED): client identifier (in our case is the uri field of the client model)

  • redirect_uri (REQUIRED): callback URI to the client application

  • username (REQUIRED): resource owner username

  • password (REQUIRED): resource owner password

  • scope (REQUIRED): privileges given to the client (TODO: make section)

The response is a JSON structure containing the final access token.

{ "access_token":"SlAV32hkKG" }

We are working on the definition of a refresh token mechanism to improve the OAuth security system

OAuth2 documentation

If the way OAuth2 works is not clear, you can find great documentation on the web.

OAuth2 Ruby Implementations

Author

Andrea Reginato & The Lelylan Project

Changelog

See CHANGELOG

License

Rest OAuth2 Server is available under the MIT license.

Something went wrong with that request. Please try again.