Authorization Basics

OAuth 2.0 Authorization Code Flow

Learn what an authorization code grant is and what its process is. Find out what type of applications can use the authorization code grant flow in a safe and secure manner.

In a Nutshell

According to the OAuth authorization code grant flow, an authorization server sends a temporary (authorization) code to a client. The code is exchanged for a token. This flow is available for confidential clients, for example, web applications with a backend that can store credentials securely. This way, the client can obtain one or more of the following token types:

The authorization code proves to the authorization server that the client requesting a token is permitted to do so. The user consents that the client can access the resource before the authorization server passes the code.

Single-page apps cannot leverage it unless they use the Proof Key of Code Exchange (PKCE).

Flow in Depth

For proper and secure flow of authorization code grant, the following is recommended:

  • Configure the redirection endpoint for the client application before making calls.

  • Limit the scope the client application can access when calling the /authorize and /token endpoints.

[mermaid-begin]
sequenceDiagram autoNumber participant User participant Client application participant Authorization server participant Resource server (your API) activate User User->>Client application: Access activate Client application activate Authorization server Client application->>Authorization server: Request authorization deactivate Client application Authorization server->>User: Display consent User->>Authorization server: Give consent deactivate User Authorization server->>Client application: Issue authorization code activate Client application Client application->>Authorization server: Request token Authorization server->>Authorization server: Validate the request Authorization server->>Client application: Return token deactivate Authorization server Client application->>Resource server (your API): Call API with token activate Resource server (your API) Resource server (your API)->>Client application: Return data deactivate Resource server (your API) deactivate Client application

The example diagram above illustrates the interactions that occur during the OAuth authorization code grant flow.

  1. A user tries to access the application (the client).

  2. The client application calls the authorization server’s authorize endpoint.

    Sample call to the authorize endpoint with Cloudentity as an authorization server

    curl --location --request GET \
    --url "https://$TENANT_ID.$REGION_ID.authz.cloudentity.io/$TENANT_ID/$WORKSPACE_ID/oauth2/authorize" \
    --data-raw "response_type=code&client_id=$CLIENT_ID"
    

    Region identifier

    REGION_ID is available for recently created tenants in the tenant URL next to TENANT_ID. The region IDs are assigned as follows:

    • Australia: au

    • Europe: eu

    • USA: us

    For tenants without the region identifier, the REGION_ID parameter must be skipped.

  3. The authorization server responds with the redirect URI. The user gets redirected to the consent form, if any.

  4. The user authenticates with their identity source and gives their consent.

  5. The authorization server issues an authorization code.

  6. The client application requests authentication to the token endpoint using the authentication method configured and the authorization code provided in the previous step.

    • The grant_type value in the API call must be authorization_code.

    Sample call to the token endpoint with Cloudentity as an authorization server

    curl --request POST \
    --url "https://$TENANT_ID.$REGION_ID.authz.cloudentity.io/$TENANT_ID/$WORKSPACE_ID/oauth/token" \
    --data-raw "grant_type=authorization_code&code=$CODE&client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET"
    
  7. The authorization server validates the authorization code, client ID, and client secret.

  8. The authorization server returns the token.

  9. The client application requests protected resources from the resource server and submits the token it received in the previous step.

  10. The resource server validates the token and responds with the requested resources.

Cloudentity as Authorization Server

Cloudentity provides application and security teams with a better way to automate and control how information is shared over APIs. As part of our services, we support authorization code grant.

This section covers the essential steps to try the authorization code grant for applications created with Cloudentity.

In case you need more intro information, take a look at the Quickstart section. It will guide you through the key concepts Cloudentity offers. Take in the fundamentals of access management, find out the conditions of compliance with open banking, and discover how Cloudentity APIs can make your life easier.

Launch a free tenant and use the Demo workspace to explore the authorization code flow. To add users, connect a Sandbox IDP (for testing purposes) or any of IDPs from the wide range of supported by Cloudentity. Alternatively, you can connect the Cloudentity Identity Pools IDP, when you haven’t any preferred ones. Then, try the authorization code flow configured out-of-the-box for the Demo client application to see how the flow goes.

You can set up dynamic scopes for your application, from coarse- to fine-grained. Upon scope modifications, configure the user consent form based on your changes.

More in Cloudentity

Cloudentity supports other grant types as well. So when the authorization code grant isn’t suitable for your use case, you can select another type based on your needs.

For example, use the PAR extension when you need to comply with FAPI advanced requirements—according to Consumer Data Right, Open Banking, or Open Insurance Brazil.

To implement a secure authorization for your native or single-page application, use the PKCE extension.

You can find more info about oauth grant types in our article, namely, what grant types are available in Cloudentity, and choose the type that meets your case.

Updated: Nov 3, 2022