Understand the Clover v2/OAuth flow
This topic explains how Clover implements OAuth principles in its application authentication paradigm. The Clover v2/OAuth flow is only available in North America.
Auth code acquisition flows
Clover apps use the following authorization token acquisition flows:
Auth flow | Description |
---|---|
Implicit flow | Also called response type token, 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: Clover plans to deprecate the response type token (implicit) flow. If your app uses response type tokens, migrate your app to use the auth code flow with PKCE. See Migrate legacy OAuth API tokens to v2/OAuth expiring tokens for more information. |
Authorization code flow | Used by high trust apps to exchange an authorization code for an access_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 . |
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
.
Terminology
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 bit) to one-way hash the code verifier. Other algorithms may be added in the future. |
OAuth flow with PKCE
The OAuth flow with PKCE is as follows:
- Generate code verifier and code challenge—The app generates a random string called the
code_verifier
and then creates acode_challenge
by hashing thecode_verifier
using SHA256. - Authorization request—The app redirects the user to the authorization server with the
code_challenge
included in the request. - User authentication—The merchant logs in and authorizes the app to access their data.
- Authorization code—The authorization server redirects the user back to the client app with an authorization code.
- Token request—The app sends a request to the token endpoint, including the authorization code and the original
code_verifier
. - Token response—The authorization server verifies the
code_verifier
against thecode_challenge
and, if they match, issues anaccess_token
and arefresh_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.
Related topics
Updated about 1 month ago