Clover v2/OAuth flow overview
Clover OAuth processes for high-trust and low-trust apps with PKCE
This topic explains how Clover implements OAuth principles in its application authentication paradigm.
Auth code acquisition flows
Clover apps use the following authorization token acquisition flows:
| Auth flow | Description |
|---|---|
| Implicit flow | Also called response_type token method, this is the least secure authorization flow. Implicit flow is a simplified auth flow that cannot securely store a client secret. The access_token is returned immediately without an extra authorization code exchange step. Implicit flow was previously recommended for native and JavaScript apps that can not securely store a client secret.🚧 Important: If your app uses response_type token method, migrate your app to use the auth code flow with PKCE. See Migrate legacy OAuth tokens to v2/OAuth expiring tokens for more information. |
| Authorization code flow | Used by high-trust apps to exchange an authorization code for an expiring authentication token. After the redirect URL returns the merchant to the application, the app receives the authorization code from the URL and uses it to request an access_token and a refresh_token pair. |
| Authorization code flow with proof key for code exchange (PKCE) | Required for all low-trust apps that can not securely store a client secret, such as standalone mobile, desktop, and single-page applications. |
Low-trust and high-trust apps
| App security | Description | Reference |
|---|---|---|
| High-trust apps | Securely store and use a Client Secret (app_secret). High-trust apps can use the standard auth code flow to generate auth tokens. | High-trust apps—Auth code flow |
| Low-trust apps | Do not securely store and use a Client Secret (app_secret)—such as mobile, single-page, and native desktop applications. Low-trust apps use the response type token (implicit) auth code flow.Important! Clover now requires that low-trust apps use the auth code flow with PKCE. If your app uses the implicit flow and is considered to be a low-trust app, migrate your app to use the auth code flow with PKCE. | Low-trust apps—Auth code flow with PKCE |
Proof key for code exchange (PKCE)
Proof Key for Code Exchange (PKCE) is an extension to the OAuth 2.0 authorization code flow designed to enhance security, especially for public clients, such as mobile and single-page applications that cannot securely store the Client Secret. PKCE ensures that even if an authorization code is intercepted, it cannot be exchanged for tokens without the original code_verifier.
PKCE uses the following parameters in the app to remove the need to pass the Client Secret:
| Term | Description |
|---|---|
Code verifiercode_verifier | Unique random string that the app creates for every authorization request. |
Code challengecode_challenge | App hashes the code verifier, resulting in the code challenge. Clover currently supports SHA256 (secure hash algorithm 256 bits) to one-way hash the code verifier. Other algorithms may be added in the future. |
Steps: OAuth flow with PKCE
| Step | Action | Description |
|---|---|---|
| 1. | Generate code verifier and code challenge | The app generates a random string called the code_verifier and then creates a code_challenge by hashing the code_verifier using SHA256. |
| 2. | Authorization request | The app redirects the user to the authorization server with the code_challenge included in the request. |
| 3. | User authentication | The merchant logs in and authorizes the app to access their data. |
| 4. | Authorization code | The authorization server redirects the user back to the client app with an authorization code. |
| 5. | Token request | The app sends a request to the token endpoint, including the authorization code and the original code_verifier. |
| 4. | Token response | The authorization server verifies the code_verifier against the code_challenge and, if they match, issues an access_token and a refresh_token to the app. |
For details, see Low-trust apps—Auth code flow with PKCE.
Compare legacy response type token (implicit) flow with PKCE flow
Comparing the implicit flow and auth code flow with PKCE illustrates the added security steps in the auth code flow with PKCE.
Implicit flow compared to auth code flow with PKCE
Related topics
Updated 18 days ago