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.
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. The user can use any username and password for sandbox.
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.
When the user successfully selects his information he will be directed to SCA page (Strong Customer Authentication), where he will need to enter the authentication code from his SCA Mobile App. Since there is currently only a mobile application for testing purposes (not public), validation will not be performed on that field if it is not filled in.
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:
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:
- Content-Type= application/x-www-form-urlencoded
- 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
The Authorization Code flow is complete! The application now has an access token it can use when making API requests.