OAuth authentication
Optimizely Connect Platform (OCP) provides building blocks to help you implement OAuth authentication for your app. OAuth lets your app call third-party APIs on behalf of the owner of the OCP account where your app is installed. For example, you can use OAuth to call the Shopify API to retrieve data from a Shopify store.
There are two ways to implement OAuth authentication in your app.
- Initiate OAuth from the OCP App Directory (from your app settings form).
Which method you choose depends on the third-party service you are integrating with.
Initiate OAuth from the OCP App Directory
- The OAuth flow initiates when a user clicks an OAuth button in your app settings form in the OCP App Directory.
- The OCP App Directory redirects the user to the third-party service to authenticate and authorize your app. The URL to redirect to is defined by the `onAuthorizationRequest lifecycle method`. Implement this method by returning an App.LifecycleSettingsResult object with the redirect property set to the URL of the third-party service. The exact URL depends on the third-party service you are integrating with. For the returning URL of the OAuth flow, you use the value returned by the OCP App SDK's functions.getAuthorizationGrantUrl method.
- The app user authenticates and authorizes your app in the third-party service.
- The app user is redirected back to the OCP App Directory, which displays the authorization page and lets the user choose which account to install the app in. OCP defaults to the account that initiated the OAuth flow.
- The OCP App Directory calls the `onAuthorizationGrant lifecycle method` to validate the response and retrieve the OAuth token from the third-party service. The exact implementation of this method depends on the third-party service you are integrating with. The method should do the following:
- Validate the response from the third-party service.
- Retrieve the OAuth token from the third-party service. The exact way to retrieve the OAuth token depends on the third-party service you are integrating with.
- Store the token in the secret store for later use.
- Return an App.AuthorizationGrantResult object. It is good practice to add a toast message to the object to notify the user about the authorization result.
- The user is redirected to the app settings form where they started.
Initiate OAuth from a third-party service
Some OAuth providers do not let you initiate the OAuth flow from the OCP App Directory, but rather they require the app user to initiate the OAuth flow from their service. One example is Shopify, where the flow starts from a merchant requesting app installation in the Shopify admin portal.
The flow starts from a third-party service, where the app user authenticates and authorizes your app. This means there is no OAuth button in the app settings form of your app in the OCP App Directory, and you do not need to implement the onAuthorizationRequest lifecycle method.
The exact implementation depends on the third-party service you are integrating with, but at some point in the process, you must redirect the user to the OCP App Directory to pick the OCP account where they want to install the app and authorize the app installation. The URL to redirect to is returned by the App SDK's functions.getAuthorizationGrantUrl method. When the user is redirected to this URL, steps 4 to 6 from the Initiate OAuth from the OCP App Directory section take place.
If the third-party service requires more redirects, you can use a global function to implement them.