Authorization Code

The purpose of the Authorization Code flow is to acquire an Access Token, which can be added as Bearer token to REST calls made towards a Resource Server.

This flow may be used by classic Web applications which have server-side processing and are able to store an OAuth 2.0 client secret in a safe place.

SPA and native applications should use the more secure Authorization Code flow with PKCE instead.

Authorization Code flow

The user clicks Login in the Web App.

The App redirects the user to the Identity Cloud Authorization endpoint. Example URL ¹:

https://yourinstance.id.nevis.cloud/auth/oauth2/authorize
  ?response_type=code
  &client_id=a2091050cfdd15be
  &redirect_uri=https://app.my-company.com
  &scope=openid%20offline_access

See Authorization endpoint for a description of the query parameters.

Identity Cloud shows a login page.
The user authenticates by entering their credentials.
Upon successful authentication, the authorization endpoint generates an Authorization Code and redirects the user to the return_uri. The Authorization Code is handed over as a query parameter code.
Example URL ¹:
```
https://app.my-company.com?code=WyZIgDiGQ0DIvbZM7vmBW2ADw6hzwekZac0oe_ucfYo
```
Your app sends the code to the Identity Cloud Token endpoint. The grant_type must be authorization_code and the redirect_uri must be allowed for this application. For security reasons, the call should be done by a server-side component as it includes the client_secret.
Example POST request ¹:
```
POST /auth/oauth2/token HTTP/1.1
grant_type=authorization_code
&client_id=a2091050cfdd15be
&client_secret=c091a151f0ce9635
&code=WyZIgDiGQ0DIvbZM7vmBW2ADw6hzwekZac0oe_ucfYo
&redirect_uri=https%3A%2F%app.my-company.com
```
The token endpoint returns an Access Token. Depending on the scopes requested in step 2 additional tokens will be returned:
1. ID Token: scope openid
2. Refresh Token: scope offline_access
Example JSON response ¹:
```
{
  "access_token":"ey...",
  "refresh_token":"...",
  "id_token":"ey...",
  "token_type":"Bearer",
  "expires_in":3600
}
```
The access token and ID token are JWT tokens, while the refresh token is opaque.

¹ line-breaks have been added to make the example more readable.