Authorization Process

The Authorization Code Flow

The Authorization Code grant type is used by web and mobile apps. It differs from most of the other grant types by first requiring the app launch a browser to begin the flow. At a high level, the flow has the following steps:

  • The application opens a browser to send the user to the OAuth server;
  • The user sees the authorization prompt, log in and approves the app’s request and grant the necessary permissions;
  • The user is redirected back to the application with an authorization code in the query string;
  • The application exchanges the authorization code for an access token.

Get the User’s Permission

OAuth is all about enabling users to grant limited access to applications. The application first needs to decide which permissions it is requesting, then send the user to a browser to get their permission. To begin the authorization flow, the application constructs a URL like the following and opens a browser to that URL.

https://identity.dskbank.bg/connect/authorize

response_type=code

client_id=29352915982374239857

redirect_uri=https%3A%2F%2Fexample-app.com%2Fcallback

scope=ais.sandbox state=xcoiv98y2kd22vusuye3kch

Here’s each query parameter explained:

  • response_type=code - This tells the authorization server that the application is initiating the authorization code flow;
  • client_id - The public identifier for the application, obtained when the developer first registered the application;
  • redirect_uri - Tells the authorization server where to send the user back to after they approve the request;
  • scope - One or more space-separated strings indicating which permissions the application is requesting. The specific OAuth API you’re using will define the scopes that it supports;
  • state - The application generates a random string and includes it in the request. It should then check that the same value is returned after the user authorizes the app. This is used to prevent CSRF attacks.

When the user visits this URL, the authorization server will present them with a login page asking for user credentials.

 

When the user successfully logs in, the authorization server will present them with a prompt asking if they would like to authorize this application’s request.

 

Redirect Back to the Application

If the user approves the request, the authorization server will redirect the browser back to the redirect_uri specified by the application, adding a code and state to the query string.

For example, the user will be redirected back to a URL such as:

https://example-app.com/redirect

code=g0ZGZmNjVmOWIjNTk2NTk4ZTYyZGI3

scope=ais.sandbox

state=xcoiv98y2kd22vusuye3kch

The state value will be the same value that the application initially set in the request. The application is expected to check that the state in the redirect matches the state it originally set. This protects against CSRF and other related attacks.

The code is the authorization code generated by the authorization server. This code is relatively short-lived, typically lasting between 1 to 10 minutes depending on the OAuth service.

Exchange the Authorization Code for an Access Token

We’re about ready to wrap up the flow. Now that the application has the authorization code, it can use that to get an access token.

The application makes a POST request to the service’s token endpoint with the following parameters:

Header:

  • Content-Type= application/x-www-form-urlencoded

Body:

  • grant_type=authorization_code - This tells the token endpoint that the application is using the Authorization Code grant type;
  • code - The application includes the authorization code it was given in the redirect;
  • redirect_uri - The same redirect URI that was used when registering the application;
  • client_id - The application’s client ID;
  • client_secret - The application’s client secret. This ensures that the request to get the access token is made only from the application, and not from a potential attacker that may have intercepted the authorization code.

HTTP/1.1 200 OK

Content-Type: application/json

Cache-Control: no-store

Pragma: no-cache

{

"access_token":"MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3",

"token_type":"bearer",

"expires_in":3600

"refresh_token":eyJhbGciOiJSUzI1NiIsImtpZCI6ImZjNWEx

}

The Authorization Code flow is complete! The application now has an access token it can use when making API requests.

Exchange Refresh Token for an Access Token

We can use the refresh token from the previous request for getting access token, that was generated in the response body to get new access token when the old one is expired.Refresh tokens can be used only one time!

The application makes a POST request to the service’s token endpoint with the following parameters:

Header:

  • Content-Type= application/x-www-form-urlencoded

Body:

  • grant_type=refresh_token - This tells the token endpoint that the application is using the Refresh Token grant type;
  • refresh_token - The application includes the refresh token, that was found in the previous post request for access token;
  • client_id - The application’s client ID;
  • client_secret - The application’s client secret. This ensures that the request to get the access token is made only from the application, and not from a potential attacker that may have intercepted the authorization code.

HTTP/1.1 200 OK

Content-Type: application/json

Cache-Control: no-store

Pragma: no-cache

{

"access_token":"MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3",

"token_type":"bearer",

"expires_in":3600

"refresh_token":eyJhbGciOiJSUzI1NiIsImtpZCI6ImZjNWEx

}

The Authorization Code flow is complete! The application now has an access token it can use when making API requests.