ACP authorization code grant flow with PKCE

Learn what an authorization code grant with the Proof Key of Code Exchange is and what its process is. Find out which applications can use the authorization code grant flow with PKCE in a safe and secure manner.

Authorization code grant flow with PKCE in a nutshell

Authorization code grant with the Proof Key of Code Exchange (PKCE) is an extension of the standard authorization code grant OAuth flow. It is designed to be a secure substitute for the implicit flow for single page applications (SPA) or native applications.

Read more

To learn more about PKCE, see the RFC7636 PKCE OAuth specification.

Authorization code grant with PKCE in depth

Both SPAs and native applications are considered to be public clients. It means that they are not able to securely store client secrets in their code. Single page apps have their entire source code available in the browser. Native applications can be decompiled and the client secret that is available for all of the application’s users and devices becomes exposed as a result.

Prerequisites

To use the ACP authorization code grant flow type, the client must match the following criteria:

  • It must be able to interact with the resource owner’s user-agent, for example, a web browser.

  • It must be capable of receiving incoming requests (via redirection) from the authorization server.

Grant flow diagram

[mermaid-begin]
sequenceDiagram participant User participant Client application participant ACP tenant participant API activate User User->>Client application: Access activate Client application Client application->>Client application: Generate the code verifier and the code challenge activate ACP tenant Client application->>ACP tenant: Authorization code request + code challenge to /authorize deactivate Client application ACP tenant->>User:Display consent User->>ACP tenant: Authenticate and give consent deactivate User ACP tenant->>Client application: Issue authorization code activate Client application Client application->>ACP tenant: Authorization code + code verifier to /token ACP tenant->>ACP tenant: Verify the authorization code, code verifier and code challenge ACP tenant->>Client application: Return token deactivate ACP tenant Client application->>API: Call API with token activate API API->>Client application: Return data deactivate API deactivate Client application

Authorization code grant with PKCE process

Note

The authorization code grant with PKCE flow is very similar to a standard authorization code grant flow. The difference lies in the process of client authentication. To learn more about it, see the Client authentication set to none and with the use of PKCE documentation.

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

  2. The client redirects the user to the authorize endpoint.

    Note

    The client must inform ACP of its desired grant type by using the response_type parameter. For the authorization code grant flow type, the value of the response_type parameter must be code.

  3. ACP authenticates the user and displays a consent screen if there is an authorization scope to be granted.

    Note

    ACP does not display the consent screen when there is no authorization scope to be granted.

  4. The user gives their consent.

  5. ACP issues an authorization code.

    Note

    After ACP generates the authorization code, it is redirected to the redirection endpoint configured for the registered client. The client must have at least one registered redirection URI. If there are multiple registered redirection URIs, the request to the authorize endpoint must always include the redirect_uri parameter. If there is only one registered redirection URI for the client, it does not have to include the redirect_uri parameter in the request to the authorize endpoint.

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

    Read more

    To learn more about token endpoint authentication methods, see the client authentication documentation.

  7. ACP validates the request.

  8. ACP returns the token.

  9. The client 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 the requested resources.

Cloudentity Auth JS

Cloudentity-auth-js is a library that provides you with a client that makes it possible for JavaScript single page applications to use the authorization code grant flow with PKCE. To make use of the library, see the cloudentity-auth-js library dedicated GitHub repository.