Skip to content

OAuth Flow

Jump to bottom
Daniel James edited this page Nov 12, 2024 · 12 revisions

Note

This page updated as of SDK version 1.1.2

Clover implements a three legged OAuth flow to authenticate your users, merchants, and apps.

Key terminology

Environment

During development, you typically interact with the sandbox environment. When you deploy, you deploy to production.

Sandbox
Sandbox environment provides production-like code in an environment that does not impact your production systems in any way. Any payments taken in sandbox are validated as if they were real; however, no money moves in the real world. Test credit cards allow you to take "test" payments. Create accounts and applications in sandbox the same as in production. Use sandbox to test your app in a safe environment.
Production
When you are ready to deploy your application, create accounts and applications in the production environment. Payments taken in production are real and move money in the real world.

Clover app

To authorize OAuth for your mobile app, create a Clover app at https://sandbox.dev.clover.com/developer-home (sandbox) and https://www.dev.clover.com/developer-home (production). The app goes through Clover app approval processes, and provides the App ID and App Secret which will be used by your mobile app during OAuth.

App ID & Secret

Provides authentication that your client app, Clover app, and merchant are all authorized to interoperate. Provide these values to the CloverPaymentSDK in your mobile app.

Site URL

Provides a validated URL that can be used as the redirect URI during the OAuth flow.

Merchant

A Clover merchant:

  • Needs a Clover account to process payments.
  • Must have your Clover app installed to their Merchant Dashboard to perform OAuth.
  • Has one or more employees configured on the Merchant Dashboard.

Access the Merchant Dashboard through https://sandbox.dev.clover.com/ (sandbox) and https://www.clover.com/ (production).

Employee

An employee:

  • Is the person using your application.
  • Has an account on https://sandbox.dev.clover.com/ (sandbox) or https://www.clover.com/ (production).
  • Is tied to a merchant as an employee in the Merchant Dashboard.
  • Uses their employee login credentials to log in to the OAuth login screen.

Note

The passcode in the employee configuration is not used by the Go SDK. Instead, employees must have an email/password login and then be assigned to the merchant as an employee using the same email.

Mobile app

Your mobile app, running on iOS, and consuming the CloverPaymentSDK. Configure your mobile app by providing it with the App ID and Secret, OAuth redirect URI, and an environment to talk to. There are multiple ways to implement OAuth in your app, which are discussed in detail below.

OAuth Flow Integration Levels

The SDK supports several levels of OAuth Integration in order to best support your app and branding strategies.

Full OAuth

The quick start guide walks you through the simplest and recommended integration: Full OAuth, where the SDK takes care of the managing the OAuth process for you, and your app only needs to provide the interconnects between the SDK and iOS.

  • When to Use: Use Full OAuth when you would like the SDK to manage the full OAuth flow for you.
    • Pros:
      • The SDK will manage refresh tokens for you, and will ensure you always have a usable token.
      • The SDK will call out to an external browser with the Clover login page
    • Cons:
      • You will need to monitor incoming URLs in your Scene Delegate, and pass those onto the SDK. The incoming URL following a successful login will contain the code used to obtain the auth token.
      • No opportunity for branding the login screen
      • The app will exit to the default browser for the login, and then pass back utilizing the redirect URL and your applinks definition.

Full OAuth Flow

  1. Add a token change callback using CloverPaymentSDK.shared.addOnTokenChangeCallback.
  2. Attempt to initialize the SDK by calling CloverPaymentSDK.shared.setup, passing in your configuration object. In the configuration object, include a CloverPaymentSDK.FullOAuth object for full OAuth Support.
  3. CloverPaymentSDK attempts to recover a valid token stored securely in Keychain. If it finds a valid token, it completes initialization and calls your success callback registered in Step 2.
  4. If no valid token is found, CloverPaymentSDK initiates OAuth login using the default browser on the device. This opens the login page in your configured environment for the user to log in. Identifying information from your configuration is passed in at this point to ensure your app is authorized to log in for the merchant and employee.
  5. Upon successful completion of the login, a code is provided using a callback to your registered associated domain. This enters back into your app using the scene delegate or other appropriate path. Refer to Apple documentation for options. In your handler, pass the full URL containing the code back using CloverPaymentSDK.shared.receivedOAuthCodeOrToken.
  6. CloverPaymentSDK exchanges the code for a token, stores the token back into Keychain for the next launch, and then calls your token change callback registered in Step 1. In your callback, call the CloverPaymentSDK.shared.setup to retry initialization this time with a valid token stored.

Full OAuth Flow

Partial OAuth

Partial OAuth is used when you would like to perform the OAuth login flow in your app, but then let the SDK manage refresh tokens.

  • When to Use: Use Partial OAuth to implement the OAuth login flow in your app, but let the SDK manage token refresh moving forward.
    • Pros:
      • The SDK will manage refresh tokens for you, and will ensure you always have a usable token.
      • You can present the Clover login screen directly in your app, using the UI design appropriate for you
      • You can implement the OAuth login flow without exiting the app, should you choose to do that.
    • Cons:
      • You will need to write your own web view implementation to execute the OAuth login flow
      • You will need to monitor and intercept the code response from the OAuth login flow in your app
      • As a result, the implementation in your code will be significantly more complicated than the Full OAuth flow.

Partial OAuth Flow

  1. First Launch
    • In your app, implement the OAuth Login Flow by following the flows defined at https://docs.clover.com/docs/use-oauth.
      • Be sure and use the Low Trust Apps flow defined at https://docs.clover.com/docs/oauth-flow-for-low-trust-apps-pkce. This flow is specifically for mobile apps where the app secret cannot be kept secret due to the nature of distributed app binaries. Note: the CloverPaymentSDK.OAuthCodeChallenge object may be utilized to facilitate the PKCE flow in your application by generating the verifier and challenge objects for use in the flow.
      • You only need to get as far as receiving the Code response before returning and passing that information to the SDK.
    • Initialize the SDK by calling CloverPaymentSDK.shared.setup, passing in your configuration object. In the configuration object, include a CloverPaymentSDK.PartialOAuth object. In the PartialOAuth object, include the Code received from the OAuth Login flow already completed, along with the Challenge information you used with the PKCE flow.
    • CloverPaymentSDK exchanges the code for a token, stores the token in the Keychain for the next launch, and then calls your token change callback registered in Step 1.
  2. Subsequent Launches
    • Initialize the SDK by calling CloverPaymentSDK.shared.setup, passing in your configuration object. In the configuration object, include a CloverPaymentSDK.PartialOAuth object. In the Partial OAuth object, set the code to nil to signal to the SDK that you do not have a new code, and to simply use the previously stored token.

Partial OAuth Flow

No OAuth

No OAuth is a special case where your code will implement and manage the OAuth Flow external to the SDK. You provide a token for the SDK to use, and then provide updates to the token as your refresh them.

  • When to Use: Use No OAuth when you want to manage the full flow in your code.
    • Pros:
      • You can manage the full flow
      • You can use the token in external calls such as to Ecomm endpoints
    • Cons:
      • Significantly increased app complexity
      • Tokens need to be refreshed every 30 minutes, and you will need to provide updated tokens as you refresh them.
      • Every time you provide a refreshed token, the SDK will re-fetch the merchant data, which will increase your network load over the other two options.

Important

Monitor the lifecycle of your token by examining the expiry date provided along with the token. When it nears expiration, it is your app's responsibility to refresh it.

No OAuth Flow

  1. In your app, implement the OAuth Login Flow by following the flows defined at https://docs.clover.com/docs/use-oauth.
    • Be sure and use the Low Trust Apps flow defined at https://docs.clover.com/docs/oauth-flow-for-low-trust-apps-pkce. This flow is specifically for mobile apps where the app secret cannot be kept secret due to the nature of distributed app binaries.
    • You will need to follow through the OAuth Flow through to receiving an auth Token as well as the refresh tokens.
  2. Initialize the SDK by calling CloverPaymentSDK.shared.setup, passing in your configuration object. In the configuration object, include a CloverPaymentSDK.NoOAuth object. In the NoOAuth object, include the token obtained in step 1. You must include the token every time you call setup.
  3. Whenever you need to update the token, pass in the updated token via CloverPaymentSDK.shared.updateToken.

No OAuth Flow

Interconnects

The Clover app ties the merchant to the mobile app, and provides authorization from Clover to operate your app on Clover systems. The Clover app is installed on the merchant. The Clover app's ID and Secret are provided to the mobile app.

The merchant provides authorization to their employee(s), and to the Clover app (and by extension, your Mobile App). Employees are configured on the merchant. The Clover app is installed on the merchant.

The site URL is validated against a redirect URI provided by your mobile app during OAuth. The redirect URI must have the same base as the site URL configured for your Clover app. The site URL is configured on the Clover app. The redirect URI is configured in the mobile app.

Note

If using app site association on iOS, the apple-app-site-association file must also be installed at the base of the same site URL and will be used by iOS and Apple for further validation. The apple-app-site-association validates the redirect URI against the mobile app using the Mobile App's ID and your developer credentials.

Methods

Main SDK Class

public class CloverPaymentSDK {
    /// Initialize the Clover Payment SDK
    /// - Throws: A ``CloverGenericError`` in the event of an issue during setup
    /// - Parameters:
    ///   - configuration: Provide the necessary ``Configuration`` parameters used to communicate with Clover.
    public func setup(configuration: Configuration) async throws

    /// True if we have valid OAuth credentials, signifying the User is logged in
    public var isLoggedIn:Bool

    /// Deletes the OAuth credentials and triggers an onTokenChangeCallback
    public func logout()

    /// The onTokenChangeCallbacks will be executed whenever a token changes (new token, refreshed token, deleted token, invalidated token)
    /// - Parameter callback: The callback to execute when the token changes
    /// - Returns: A unique identifier to be used for removing a callback when no longer needed.
    public func addOnTokenChangeCallback(_ callback:@escaping ()->()) -> String

    /// Removes an onTokenChangeCallback from the call list
    /// - Parameter identifier: The unique identifier returned when adding the callback to the call list
    /// - Returns: True if the passed in identifier was found to be associated with a callback in the call list, and therefore the callback was removed from the call list
    public func removeOnTokenChangeCallback(identifier:String) -> Bool

    /// Updates the token to use when utilizing the NoOAuth flow.  Note, this will trigger a re-download of merchant information, as the token must be verified to belong to the merchant in use prior to being used for payments.
    public func updateToken(_ token: String) async throws
}

Configuration Object

/// Provides configuration parameters to the SDK, specifying how to communicate with Clover's servers
public struct Configuration {

    /// The server environment that we will send all server calls to.
    public let environment: CloverEnvironment.EnvironmentType

    /// App ID registered on your Clover Developer Portal, used by the OAuth Flow to match permissions to your app when your merchant logs in.
    public let appID:String

    /// App Secret obtained from your Clover Developer Portal.  This is the secret associated with your App ID.
    public let appSecret:String

    /// API Key for server access.  Contact your Developer Relations representative for a valid Key and Secret.
    public let apiKey: String

    /// API Secret for server access.  Contact your Developer Relations representative for a valid Key and Secret.
    public let apiSecret: String

    /// Specifier for how the SDK should handle OAuth within your application. 
    /// Provide a FullOAuth object to enable the SDK to provide login capabilities automatically. 
    /// Provide a PartialOAuth object to enable the SDK to only maintain the OAuthToken that you have aquired outside of the SDK.
    public var oauthFlowType : OAuthFlowType
}

OAuth Type Structs

/// Specifies that the SDK should provide full OAuth login capabilities for your application. 
/// If specified, when needed the SDK will kick out to the default browser for user authentication, and return via the redirectURI.
public struct FullOAuth : OAuthFlowType {

    /// The redirectURI to provide to the OAuth server.  This URI will be called containing the code or token after the user logs in.
    /// - Precondition: The redirectURI must be configured in your app using either Associated Domains or Custom URL Scheme.
    /// - Precondition: The redirectURI must be entered into your associated Clover App on Developer Home
    public var redirectURI : String
}

/// Specifies that the SDK should provide partial OAuth login capabilities for your application.
/// If specified, the SDK will not attempt to authenticate the user, and instead expects that the host app will provide the authentication mechanism.  The SDK will provide refresh capabilities.
/// - Remark: `codeResponse` is optional, and should only be provided if you received a new code response.  The eventual token will be stored securely by the SDK between instances.
public struct PartialOAuth : OAuthFlowType {

    /// The response you received from the OAuth flow implemented in your app.
    /// - Remark: This value is optional, and should only be provided if you received a new code response.  The eventual token will be stored securely by the SDK between instances.
    public var codeResponse : OAuthCodeResponse?
}

/// Specifies that the SDK should provide no OAuth login capabilities for your application.
/// If specified, the SDK will rely on the passed in token, and will not attempt any OAuth or token refresh operations.
public struct NoOAuth : OAuthFlowType {

    /// The token used to communicate with Clover servers, obtained via the OAuth flow in your application
    public var token : String
}

Recommended implementation

OAuth implementation is covered fully in the Getting Started Guide. Refer to the section on OAuth for instructions to implement OAuth using the built-in OAuth flow.

When your app launches, any stored tokens are loaded from Keychain. If there is a token, it initializes the SDK. If there is not a token, then it redirects to the default web browser for the user to log in. When authentication succeeds, the app reopens, passing in the code, which we then give to the SDK, which exchanges it for a token, stores it securely in Keychain, and finishes initializing the SDK.

Clone this wiki locally