Powered By Blogger

Wednesday, May 1, 2013

OAuth 2.0 - Implict Grant Requests and Response Constructs



Request and Response Constructs during the various steps of Implicit Grant workFlow


Implicit Grant Type workflow involves two different kind of Requests. See the pictorial description of this workflow

Implicit Grant Request

The Client constructs the Request URI by appending, the below, query parameters to the Authorisation End Point URI. The Query Parameters using 'application/x-www-form-urlencoded' format, required to construct the request URI are illustrated in the table below:



























The Client directs the Resource owner's user-agent to this constructed URI, with the above query parameters, via http redirection or some other means. This redirection involves a transport layer security.

The Authorisation server validates this request against the Error Conditions, and returns either a access token or an error response.

Authorisation Server Responsibilities :

  • Must ensure that all the required parameters are present and valid
  • Required conditions enumerated in the 'Error Conditions' are met
  • If the request is valid, the authorisation server must validate the resource owner's credentials.This can be done via a separate login page. This page must have control elements that the user can access , either to accept or deny the authorisation request,like separate html buttons for 'allow access' and 'deny access'. This login page must explicitly display the Client name and scope of the resources   which the client would be accessing upon user's permission

Implicit Grant Response


The Authorisation Server,On successful authenticating and having explicitly asked for user's permission to access the resource , and also successfully validating against the Error Conditions, returns an 'access token'. It appends the below parameters to the Redirection URI in the URL hash fragment, using 'application/x-www-form-urlencoded' format. These paramters are shown in the table below:


























No Refresh tokens are issued in this Grant type. The Authorisation server, returns the URI constructed with the above hash parameters, to the Resource owner's user-agent.
The authorisation server also directs the user-agent to extract and store the hash fragment and use the rest of the Url for redirection. This can be achieved by a simple javascript, to be implemented by the client :


#########################

function handleRedirect(redirectUriWithhashFragment) {


var originalUrl = store(redirectUriWithhashFragment);



relocate(originalUrl);

}



##################################

 a.)    function store(originalUrl) {

var urlStr = originalUrl;

   var host = get_host();



var queryStr = get_query(urlStr);

var queryParams = get_queryMap(queryStr);


var urlFragment = get_urlfragment(urlStr);
if ( urlFragment ) {
var fragment = get_fragmentMap(urlFragment);
set_cookie("access_token", fragment["access_token"], 1, host);
}  

set_cookie("client_id", queryParams["client_id"], 1, host);
set_cookie("state", queryParams["state"], 1, host);


var originalUrl = get_url(urlStr);
return originalUrl;
}

b.) function relocate(originalUrl){
window.location = originalUrl;
}

Download the complete Application

Implicit Grant Error Response


The Authorisation server returns an Error response on various Error conditions.

  • Redirection URI is missing or invalid
  • Redirection URI does not match with the Redirection URI that was registered during Client Registration
  • Client Identifier is missing or invalid
For both the above conditions, The Authorisation server should inform the Resource owner of the Error and NOT redirect the user-agent to the Invalid Redirection URI

Other Error conditions, for which the error response is redirected to the Client
  • Invalid Request -
    • If required or mandatory parameter from the request is missing
    • request parameter has invalid value
    • request parameters are repeated more than once. Parameter repetition, may be an indicator or 'Man in Midddle attack'
  • UnAuthorised Client
    • Client not authorised to get an authorisation grant. May be beacuse of invalid client id, or using unsupported method
  • Access Denied
    • User denies access to client
  • Unsupported Response Type
    • Not a valid or Unsupported response type
  • Invalid Scope
    • Invalid or malformed request scope
  • Server Error
    • Internal server error. Corresponds to 500 http error code
  • Temporarily Unavailable
    • Server is temporarily unable to fulfill the request. Corresponds to 503 http error code
The Authorisation , for the above error conditions, constructs an URI by adding to the Redirection End Pointthe below uri hash fragment parameters in the 'application/x-www-form-urlencoded'  format. These query parameters, as illustrated in the table below:






















                                                                         

The Authorisation server, uses the URI constructed with the above query parameters, to redirect the Resource owner's user-agent to the Client App. ( See HTTP Redirection )

The 'error' parameter is a USASCII error code from the following:  
  • invalid_request
  • unathorised_client
  • access_denied
  • unsupported_response_type
  • invalid_scope
  • server_error
  • temporarily_unavailable
These 'error' conditions have already been explained above.
See OAuth 2.0 Specs for Details



HTTP Redirection

Wednesday, April 17, 2013

Svn Repository to the Web App Demostrating OAuth2.0 Protocol Flow

Simple Web App to Demonstrate OAuth2.0 Authorisation Grants

Download the complete web app at ( google code svn repo ):

https://oauth2-0.googlecode.com/svn/trunk/restful

Deploy the app in a web container and test it on firefox
Start Url :
http://localhost:8080/restful/register

This brings up a 'Client Registration Page'

Successfull registration returns a page showing the system generated Client Credential like ClientId and Client Key.

Click on the link 'Try out this App.....'
This link will take you on a tour to different Authorisation grant workflow:
  • Authorisation Code grant
  • Implicit grant via a javascript client

Authenticate with following credentials ( at the Authentication End Point Login page ) :
username : nk
password : nk

 

If Any time you get access Denied message, then see the error message for the cause.

Expiry time of access token = 3 secs

If access denied, then begin again with the start url


Expiry Token Expiration time is currently set to 3 secs.  You can change this value by modifying the vairable 'DEFAULT_TOKEN_EXPIRY_IN_SECS' which resides in com.goraksh.rest.auth.Constants java file

Snapshot to the Authetication Login page:


 


Wednesday, April 10, 2013

OAuth 2.0 - Authorisation Code Requests and Response Constructs


Request and Response Constructs during the various steps of Authorisation Code Grant workFlow

Authorisation Grant Type workflow involves two different kind of Requests. See the pictorial description of this workflow

  • Authorisation Request - This request is used for User authentication as well to redirect to the Client App with an 'authorisation code'
  • Access Token Request - Once the Authorisation request is successfull and the Client, having fetched the 'authorisation code' , makes Access token request to procure 'access tokens' from the Authorisation Server.

Authorisation Request

The request URI is constructed by adding some query parameters to the Authorisation End PointThe Query Parameters using 'application/x-www-form-urlencoded', format required to construct the request URI are illustrated in the table below:



























The Client directs the Resource owner's user-agent to this constructed URI, with the above query parameters, via http redirection. This redirection involves a transport layer security.

The Authorisation server validates this request against the Error Conditions, and returns either a authorisation code or an error response.

Authorisation Server Responsibilities :

  • Must ensure that all the required parameters are present and valid

Authorisation Response

The Authorisation server on successfully authenticating the Resource owner's credentials and also successfully validating against the Error Conditions, returns an authorisation code. 

The response URI is constructed by adding some query parameters to the Redirection End Point. The Query parameters to be added in 'application/x-www-form-urlencoded' format, as illustrated in the table below:


























The Authorisation server, uses the URI constructed with the above query parameters, to redirect the Resource owner's user-agent to the Client App. ( See HTTP Redirection )

Authorisation Error Response

The Authorisation request can fail under various conditions, under which the Authorisation server returns an Error response. Various Error conditions are enumerated below:

  • Redirection URI is missing or invalid
  • Redirection URI does not match with the Redirection URI that was registered during Client Registration
For both the above conditions, The Authorisation server should inform the Resource owner of the Error and NOT redirect the user-agent to the Invalid Redirection URI

Other Error conditions, for which the error response is redirected to the Client
  • Invalid Request -
    • If required or mandatory parameter from the request is missing
    • request parameter has invalid value
    • request parameters are repeated more than once. Parameter repetition, may be an indicator or 'Man in Midddle attack'
  • UnAuthorised Client
    • Client not authorised to get an authorisation grant. May be beacuse of invalid client id, or using unsupported method
  • Access Denied
    • User denies access to client
  • Unsupported Response Type
    • Not a valid or Unsupported response type
  • Invalid Scope
    • Invalid or malformed request scope
  • Server Error
    • Internal server error. Corresponds to 500 http error code
  • Temporarily Unavailable
    • Server is temporarily unable to fulfill the request. Corresponds to 503 http error code
The Authorisation server, for the above error conditions, constructs an Error Response URI by adding the below query parameters, in the 'application/x-www-form-urlencoded' format, to the Redirection End Point. The Query parameters required are illustrated in the table below:






















                                                                           

The Authorisation server, uses the URI constructed with the above query parameters, to redirect the Resource owner's user-agent to the Client App. ( See HTTP Redirection )

The 'error' parameter is a USASCII error code from the following:  


  • invalid_request 
  • unauthorized_client
  • access_denied
  • unsupported_response_type
  • invalid_scope
  • server_error
  • temporarily_unavailable


All of these error conditions have already been explained above


Token Request


The Client sends the request to fetch 'Access Tokens', to the Token End Point, using the parameters, as described in the table below:



















These parameters must be included in the http message body and use http POST method. These parameters must be in the 'application/x-www-form-urlencoded' format using utf-8 charset encoding.

Authorisation Server Responsibilities:
  • Must authenticate the Client credentials, either if the client were issued client credentials while Client Registration OR if the client is a confidential client
  • Must Authenticate the client if client provides client credentials in the request parameter
  • Must ensure that 'authentication code' was issued to the client making the request and matches with the code parameter provided in the request. Client identity is recognized by either, the client credentials , or, in case of public client by the client_id parameter
  • Must match the 'redirect_uri' parameter value, if redirect_uri parameter was also present during the Authorisation Request, with the 'request_uri' parameter value  of the Authorisation Request.

Token Response


The Authorisation serves on successfully validating the Token request, returns back the access token and optional refresh token in the http response message body. Example Parameters returned as described in the table below:


 







                           
Response parameters are send in the http message body with 'application/json' as the the media type. Http response header 'Cache-Control' must be set to 'no-store' and the heaer 'Pragma' must be set to 'no-cache'. This ensures that access_token or any other sensitive information is never cached by the user-agent

Token Error Response

For an invalid Token Request, the Authorisation returns an Error response with 400 HTTP error code. The Error response parameters as illustrated in the table below:




These parameters are included in the Http response message body, with 'application/json' as the media type.

The 'error' parameter is a USACII code from the following :

  • invalid_request
    • If required or mandatory parameter from the request is missing
    • request parameter has invalid value
    • request parameters are repeated more than once. Parameter repetition, may be an indicator or 'Man in Midddle attack'
  • invalid_client
    • Client authentication failed
  • invalid_grant
    • The authorisation grant i.e authorisation code or resource owner's credentials are invalid, expired or revoked
  • unauthorised_client
    • Client not authorised to get an authorisation grant. May be beacuse of invalid client id, or using unsupported method
  • unsupported_grant_type
    • Authorisation grant not supported
  • invalid_scope
    • scope request is invalid or not allowed

HTTP Redirection

Oauth 2.0 - Protocol EndPoints


Different Protocol EndPoint

Endpoints are the URI to the resources. OAuth 2.0 protocol involves different EndPoints residing on different servers, either Client App, Resource Server or Authorisation Server.
They are 

  • Authorisation EndPoint
  • Redirection EndPoint
  • Token EndPoint


Authorisation EndPoint

The Authorisation EndPoint resides on the Authorisation server. It serves two purposes
    • It is used to authenticate the resource owner. This happens with an interation between the Resource owner ( user via the user-agent ) and the Resource server
    • It also contains a 'Redirect Url' component ( as a query parameter ) which is used to convey to the client, that the resource owner has been authenticated ( successfully or with failure )
This end point can be procured from the OAuth Documentation      pages of the Resource server. Since this End point is used to authenticate the Resource owner's credentials, hence this must necessarily involve the user or transport layer security ( TLS ).
Http methods supported on this endpoint :
GET - Fetch the authentication page, e.g Login page
POST - ( may not be supported as per OAuth 2.0 Specs ) To post the Login Form parameters.

Authorisation Server Responsibilites - The Authorisation server must take care of the following execution points while interacting with request to the Authorisation endpoint ( may be of interest to the guys working on writing their own OAuth server )
    1. Query paramter without a value must be ignored. They must, nevertheless, be returned back as it is
    2. Unrecognised query params should be ignored. Again, they can be returned back
    3. Query paramters in request and response must not be included more than once
    4. Query paramter 'response_type' is must and the Authorisation must return an Error Response, if this paramter is missing.



Redirection EndPoint

The Redirection Endpoint resides on the Client App ( or the Client server ). The Authorisation server uses this endpoint to redirect the user ( via the user-agent ) to the Client App. Once over with Resource owner's authentication, the Authorisation server, redirects the user-agent to the Redirection EndPoint. This redirection serves the purpose of
    • Client App gets aware of the status of the Resource owner's authentication. On successfull authenticates, the Authorisation server returns back 'code' or 'access_token' in query paramater. Else the Authorisation server returns 'error' and 'error_description'  
Redirection Endpoint must be registered by the Client, before 
any attempt is made on using this endpoint. Request containg this endpoint is   validated by the Authorisation server against the registered redirect urls, so it is necessary the Redirection Endpoint matches with the ones already registeres during Client Registration.

Authorisation server responsiblities - The Authorisation   must take care of the following execution points while dealing with Redirection Endpoint 
    1. This endpoint should be an absolute URI
    2. It must not contain any fragment part
    3. 'code' or 'acccess_token' getting trasmitted between different roles, should be guarded via TLS ( though this isn't mandatory by the OAuth 2.0 Specs )
    4. If this Endpoint is missing or is blank then the Authorisation sever must let the User know about the missing Redirection EndPoint by an error response, rather than redirection the user-agent to the Redirection Endpoint.

Token EndPoint

The Token EndPoint is used by the Client to fetch access tokens.
In the Authorisation Code workflow, the client uses this endpoint  to get the access tokens by including the 'authorisation code' in the http request. i.e The Client must authenticate itself before it can be issued access tokens by the Authorisation Server. This Client authentication is valid for all the Authorisation Grnat Types excpet for Implicit Grant Types. This authentication also requires that the Client sends back its Client credential i.e Client Id and Client secret ( obtained during client registration ) Token endpoint is not required in the Implicit grant type as access tokens are returned by the authorisation server right at the time of user authentication, wherein the authorisation server sends back the access token ( instead of a'authorisation code' ) as a query parameter appended in the Redirection Url. Client and Authorisaion server interaction on this endpoint must necessarily involve Transport Layer Security ( TLS ).

Authorisation Server responsibilities - The Authorisation server must take care of the following execution points while dealing with Token Endpoints
  1. This endpoint should be an absolute URI
  2. It must not contain any fragment part
  3. Only Http POST method should be supported on this endpoint

<< previous   Grant Types     >> next


Tuesday, April 9, 2013

OAuth 2.0 - Implicit Grant WorkFlow


Implicit WorkFlow

A pictorial representation of the OAuth 2.0 WorkFlow to obtain Authorisation Grant through the Implicit mechanism




















The workflow described in the above picture succinctly portrays the interaction between the four roles, i,e the User, the Client App, the Resource Server and the Authorisation Server. This flow is similar to the 'Authorisation Code WorkFlow'
In this Type of workflow, the Client App runs within the User's user-agent, i.e within the Browser itself. See also Different Types of Authorisation Grants

  1. User to Clien App - End User via User-agent, like Browser makes a request to access Client App.
  2. Client App to User - Client App sends back a Authentication Url to the user. This Authentication Url which can also be referred to as 'Authorisation End Point' , is a Url to the Authorisation server, which resides on the OAuth Server and is used to Authenticate the Credential of User i.e User login and Password on the Resource Server. Client Apps maintain these End Points, pre downloaded, perhaps through Resource Server's OAuth Documentation page.
  3. User to Authorisation Server - User , via the user-agent, accesses the 'Authorisation End Point' given to it by the Client App. This Request goes to the Authorisation Server, which then serves a Login page to the User, and asks User to enter its Login Username and Password. These are User's private credentials, which the User uses to access its resources on the Resource Server. At this point, to ensure complete security, User must verify that the login page is indeed served by its Resource Server, and not by some malicious website which can steal away its Credentials. This interaction necessarily involves TLS( Transport layer security )Needless to say, that authentication of user credentials also involves a interaction between Authorisation Server and Resource Server. This interaction between the two serves is out of the scope of the OAuth 2.0 Specifications.
  4. Authorisation Server to user-agent to Client App - Authorisation server, on successful validation of User Credentials, redirects user-agent to a Redirect Url on the Client App. This Redirect Url can be referred to as 'Redirection End Point' and it resides on the Client App. This Redirect Url is an already Registered Url on Client App Registration ( see Client Registration ). The Authorisation server appends a Query parameter 'access_token' to the pre Registered Redirection Url of the Client. The Client ( on redirection via the user-agent ) receives this 'access_token', which is all that the Client App requires to access the Resources on the Resource Server. Thus, this flow allows the Client to bypass the extra step of Client Authorisation via the Authorisation code. Hence it involves fewer number of requests to access a proctected resource. If the User authentication fails, the redirect url then would contain different query parameters like 'error'' and 'error_description'.
  5. Client to Resource Server - Client now uses 'Access Token' to access Resources ( requested by the User ) on the Resource server. This 'Access Token' serves as an indicator to both, a valid User Authentication as well as a Authorised Access of resources by the Client. As the Client runs within the User's Browser, hence, the Access Token is not confined within the scope of the Client app and is exposed to the user-agent. 
  6. Steps 6, 7 of the above pictorial representation, demonstrates the different user requests to the client app, which are served by the Client App with the use of Access Token, wherein, this Access Token is exchanged between the Client App and Resource Server with every http request

   >> next      client registration         << previous

Oauth 2.0 - Different types of Authorisation Grants

Authorisation Grant

An Authorisation Grant is the credetial representation the Resource Owner's authorisation of the Client's access to its protected resources. The specifications define four Grant types, described below.

  1. Authorisation Code
  2. Implicit
  3. Resource Owner password Credentials
  4. Client Credentials

Authorisation Code

The Authorisation code is obtained by using an Authorisation server as an intermediary between the client and the resource owner. Instead of requesting authorisation directly from the resource owner, the client directs the resource owner, via the user-agent, to the authorisation server. The Authorisation server redirects the resource owner, via the user-agent, back to the client with an Authorisation code. This authorisation code is then used by the client to authenticate itself and fetch Access tokens. Access tokens are, finally, used by the client to access the protected resources ( residing on Resource server) of the resource owner.

Before directly the resource owner back to the client with the authorisation code, the Authorisation server authenticates the resource owner ( through an Authorisation server and Resource server interaction ) and obtains authorisation. Because resource owner authenticates with authorisation only, hence the resource owner's credentials are hidden from the client.

The Authorisation code provides important security benefits, such as
  • Ability to authenticate the Client
  • Transmission of Access token directly to the Client, without passing it through the Resource owner's user-agent. Hence keeping the access token within the scope of the Client, without exposing it to the user or the user-agent.


Implicit

Implicit Grant is a simplified Authorisation code workflow. Here the client is issued the Access tokens, just after the Resources owner's authentication. The access token is thus returned, when the user-agent is redirected to the Client. 

This implies that
  • No Authorisation Code is required by the Client to obtain Access tokens. They are issued directly on redirection, immediately after resource owner authentication.
  • Authorisation server does not Authenticate the Client
  • Access tokens issued are now visible to the user-agent. This can pose some security loops
Because of the above three restrictions, this type authorisation grant workflow is optimised for Clients that are implemented in the Browser


Resource Owner Password Credentials

The Resource Owner's Login Credentials i.e username and password can be used directly as an authorisation grant, by the Client, to obtain Access Tokens. This workflow should be used only when there is high degree of trust be the resource owner and the client. e.g client is a part of highly privileged application, and used privately by the resource owner.

This grant type should eliminate the need for the client to store  the resource owner's credentials for future use, instead should use long term access tokens or refresh tokens.


Client Credentials

The Client Credentials, or any form of Client Authentication, can be as an Authorisation grant to obtain Access tokens. Here, the authorisation scope is limited to the protected resources, controlled by the client. i.e when the client is itself the owner of the protected resources. This workflow is also valid when the proctected are of the nature that they can be publicly accessed by multiple client, i.e when the proctected resources are now owned by any user in particluar.








OAuth 2 .0 - Protocol WorkFlow

Protocol Workflow

A pictorial representation of abstract OAuth 2.0 workflow

















Abstract protocol workflow, describes the interaction of Client with the Resource Owner, Authentication Server and Resource Server.

  1. Client requests an authorisation from the Resource Owner. This request can be made directly to the Resource Owner or preferable, indirectly via the Authorisation Server as Intermediatry.
  2. Client receives an Authorisation Grant, which represents Resource Owner's authorisation, expressed using one of the four Grant types. The Authorisation Grant types depends upon the method used by the Client to request authorisation and the types supported by the Authorisation Server.
  3. Client requests an Access Token by authenticating with the Authorisation Server and presenting it with the Authorisation Grant.
  4. Authorisation Server, authenticates the Client and validates its Authorisation Grant. If valid, issues an Access token to the Client.
  5. Client accesses the protected resource on the Resource server, by presenting the access token.
  6. Resource server validates the access token. If valid, returns the desired resource representation to the Client.

<< previous       client registration          >> next

Monday, April 8, 2013

OAuth 2.0 - Authorisation Code Grant WorkFlow

Authorisation Code WorkFlow

A pictorial representation of  OAuth 2.0 WorkFlow to obtain the Authorisation Grant through the Authorisation Code
















The workflow described in the above picture succinctly potrays the interaction between the four roles, ie. The User, Client App, Authorisation Server and Resource Server. 

Movement of web Requests, right when the User makes the first http request to access Client app, till the Client App is able to serve the desired resource to the User.Between these two ends lies various other steps of the Workflow, which are all described, in details, below.

Different Url End Points, residing on either Client Apps or the Authorisation Server, are also described below.

  1. User to Clien App - End User via User-agent, like Browser makes a request to access Client App.
  2. Client App to User - Client App sends back a Authentication Url to the user. This Authentication Url which can also be referred to as 'Authorisation End Point' , is a Url to the Authorisation server, which resides on the OAuth Server and is used to Authenticate the Credential of User i.e User login and Password on the Resource Server. Client Apps maintain these End Points, pre downloaded, perhaps through Resource Server's OAuth Documentation page.
  3. User to Authorisation Server - User , via the user-agent, accesses the 'Authorisation End Point' given to it by the Client App. This Request goes to the Authorisation Server, which then serves a Login page to the User, and asks User to enter its Login Username and Password. These are User's private credentials, which the User uses to access its resources on the Resource Server. At this point, to ensure complete security, User must verify that the login page is indeed served by its Resource Server, and not by some malicious website which can steal away its Credentials. This interaction necessarily involves TLS( Transport layer security ). Needless to say, that authentication of user credentials also involves a interaction between Authorisation Server and Resource Server. This interaction between the two serves is out of the scope of the OAuth 2.0 Specifications.
  4. Authorisation Server to user-agent to Client App - Authorisation server, on successful validation of User Credentials, redirects user-agent to a Redirect Url on the Client App. This Redirect Url can be referred to as 'Redirection End Point' and it resides on the Client App. This Redirect Url is an already Registered Url during Client App Registration ( see Client Registration ). The Authorisation server appends a Query paramter 'code' to the pre Registered Redirection Url of the Client. Client ( on redirection via the user-agent ) recives this 'code', which serves as an indicator to the Client that User had been successfully authenticated. This can be referred to as 'Authorisation Code'. If the User authentication fails, the redirect url then would contain different query parameters like 'error'' and 'error_description'. 
  5. Client App to Authorisation Server - After successfully procuring the 'Authorisation code' , client exchanges this code for an 'Access Token'. For this the Client submits ( POST ) 'Authorisation Code' along with the 'Client Id' and 'Client Secret' ( these client_id and client_secret keys were received by the Client during Client Registration ). This submission of the authorisation code, client id and client secret is directed to an Url which can be referred to as 'Token End Point', which resides on the Authorisation Server. The Authorisation Server, upon validating the Client code, id and secret, responds with an 'Access Token'. This interation, again, necessarily involves TLS ( Transport layer security ).
  6. Client to Resource Server - Client now uses 'Access Token' to access Resources ( requested by the User ) on the Resource server. This 'Access Token' serves as an indicator to both, a valid User Authentication as well as a Authorised Access of resources by the Client. Access Token is confined within the scope of the Client app and is not exposed to the user-agent. Steps 7, 8, 9, 10, 11 portrayed in the above pictorial representation, demonstrates, different user requests to the Client App which are served by the Client app with the use of 'Acccess Token', wherein this 'access token' is exchaged between the Client App and the Resource Server with every http request.