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