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 Optimizely Data Platform (ODP) 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:

1. OAuth initiated from the ODP App Directory (from your app settings form)
2. OAuth initiated from a third-party service

Which method you choose depends on the third-party service you are integrating with.

OAuth initiated from the ODP App Directory

1. The OAuth flow initiates when a user clicks an OAuth button in your app settings form in the ODP App Directory.
2. The ODP 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 Node SDK's functions.getAuthorizationGrantUrl method.
3. The app user authenticates and authorizes your app in the third-party service.
4. The app user is redirected back to the ODP App Directory, which displays the authorization page and lets the user choose which account to install the app in. ODP defaults to the account that initiated the OAuth flow).
5. The ODP 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:
   • 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.
6. The user is redirected to the app settings form where they started.

OAuth initiated from a third-party service

Some OAuth providers do not allow initiating the OAuth flow from the ODP 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 ODP 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 ODP App Directory to pick the ODP account where they want to install the app and authorize the app installation. The URL to redirect to is returned by the Node SDK's functions.getAuthorizationGrantUrl method. When the user is redirected to this URL, steps 4 to 6 from the OAuth initiated from the ODP App Directory section take place.

If the third-party service requires more redirects, you can use a global function to implement them.