Authorization Code

This authorization flow is used for server-side code and is using the official OAuth 2.0 Authorization Framework's Authorization Code.

The authorization code is obtained by using our Unified Login as an intermediary between the client and resource owner. Instead of requesting authorization directly from the resource owner, the client directs the resource owner to an authorization server (via its user-agent), which in turn directs the resource owner back to the client with the authorization code. Before directing the resource owner back to the client with the authorization code, the authorization server authenticates the resource owner and obtains authorization. Because the resource owner only authenticates with the authorization server, the resource owner's credentials are never shared with the client. The authorization code provides a few important security benefits, such as the ability to authenticate the client, as well as the transmission of the access token directly to the client without passing it through the resource owner's user-agent and potentially exposing it to others, including the resource owner.

The request

Authorization Code Flow

 

 
  1. The client website initiates the flow by redirecting the resource owner's user-agent to the Unified Login.
  2. The client website includes its client identifier, requested scope(s), local state (optional), the response type and a redirection URI to which the Unified Login will send the user-agent back once access is granted (or denied). The Unified Login authenticates the resource owner (at AdultWork.com) via the user-agent and establishes whether the resource owner grants or denies the client's access request.
  3. Assuming the resource owner grants access, the Unified Login redirects the user-agent back to the client website using the redirection URI provided earlier.
  4. The user-agent follows the redirection instructions by making a request to the client website. The redirection URI always includes the 'code' and the 'state' if this was supplied earlier in the query string.
  5. The client website gets the 'code' from the query string and posts this with the grant type, redirection URI, client id, client secret to the Unified Login.
  6. The Unified Login will process the request and returns the access token, token type, expiration and refresh token.
 
 

 

The client website constructs the request URI by adding the following parameters to the query component of the authorization endpoint URI using the "application/x-www-form-urlencoded" format:

  • response_type
    • The value must be set to "code".
  • client_id
    • The client identifier. This can be found in the project details page under the Unified Login tab.
  • redirect_uri
    • The absolute URI to which the Unified Login will send the code.
  • scope
    • The scope of the requested permissions. The Unified Login requires at least the scope userid.
  • state
    • This is a value used by the client to maintain state between the request and callback. The Unified Login includes this value when redirecting the user-agent back to the client. You can use this to protect against CSRF issues.

 

For example, the client directs the user-agent to make the following HTTP request using TLS (with extra line breaks for display purposes only):

GET /OAuth/Authorize?response_type=code&client_id=s6BhdRkqt3&
state=xyz&redirect_uri=https%3A%2F%2Fclientwebsite%2Ecom%2Fcb 
HTTP/1.1
Host: platform.AdultWork.com

 

 

 

 

The Unified Login validates the request to ensure that all required parameters are present and valid. The Unified Login will verify that the redirection URI to which it will redirect the authorization code matches the redirection URI located in the project details page under the Unified Login tab.

If the request is valid, the Unified Login authenticates the resource owner and obtains an authorization decision (by asking the resource owner to grant their permission to the scopes issued by the client website).

When a decision is established, the Unified Login directs the user-agent to the provided client redirection URI using an HTTP redirection response.

 

The response

If the resource owner grants the access request, the Unified Login issues an authorization code and delivers it to the client by adding the following parameters to the query string of the redirection URI using the "application/x-www-form-urlencoded" format:

  • code
    • The authorization code generated by the Unified Login.
  • state
    • This is a value used by the client to maintain state between the request and callback. The Unified Login includes this value when redirecting the user-agent back to the client. You can use this to protect against CSRF issues.

 

It is up to you to get this code from the query string to exchange it for a valid access token. Exchanging an authorization code for an access token is quite easy. Post the code as well as the client_id, client_secret, grant_type and the redirect_uri to the Unified Login. Below is an example how to do so.

POST /OAuth/token HTTP/1.1
Host: platform.AdultWork.com     
Content-Type: application/x-www-form-urlencoded
code=SplxlOBeZQQYbYS6WxSbIA&client_id=s6BhdRkqt3&&client_secret=tRdVreBio20190802&grant_type=authorization_code&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb

 

 

 

 

 

 

The response

The Unified Login validates the posted data to ensure that all required parameters are present and valid. The Unified Login will verify that the redirection URI to which it will redirect the access token matches the redirection URI located in the project details page under the Unified Login tab.

  • access_token
    • The access token issued by the Unified Login.
  • token_type
    • The Unified Login is using the "bearer" token type.
  • expires_in
    • The lifetime in seconds of the access token.  For example, the value "3600" denotes that the access token will expire in one hour from the time the response was generated.
  • scope
    • The scope of the requested permissions. The Unified Login requires at least the scope userid.
  • state
    • This is a value used by the client to maintain state between the request and callback. The Unified Login includes this value when redirecting the user-agent back to the client.
  • refresh_token
    • This token can be used to obtain a new access token when it almost expires. You are responsible to get a new access token before the access token expires.

 

An example successful response: 

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
    {
       "access_token":"2YotnFZFEjr1zCsicMWpAA",
       "token_type":"bearer",
       "expires_in":3600,
       "state": "jau95cbrbut20isok7wd1908zp",
       "refresh_token": "3Vtn6eOPE123Dl1JoMiQBBQC"
     }