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


             redirect http response from server to user-agent
             HTTP/1.1 302 Found
             Location:'client_redirect_url'   
User-agent <----------------------------------------- Server      
     |
     |
     |
     | User-agent sends a HTTP GET to 'client_redirect_url'
     | HTTP GET 'client_redirect_url'
     |
     |
     |
     |
     |
     |
     |
    \/
   Client
     
             
               

No comments:

Post a Comment