How to add OAuth in a Freshworks app

Freshworks Developer Platform supports OAuth to authenticate third-party applications that provide authorization in the Freshworks Marketplace apps. The OAuth 2.0 framework compliance is required for the third parties to integrate from the platform’s offering.

Do a few steps to complete a Freshworks app with OAuth configuration.

  1. Get credentials: To create OAuth app in the third-party authorization provider to get a Client ID and Client Secret
  2. Add configurations to the app: Create an oauth_config.json file to add configurations
  3. Use the OAuth access token: Use access token in the HTTP requests made from the app

Get Credentials

Every third-party authorization provider has its steps to create an OAuth application on its platform. For example, find the steps for GitHub, Shopify, and OneDrive. Unique credentials are generated for these OAuth applications, and we can fetch the credentials from the third-party platform. These credentials are then used as a Client ID and Client Secret in the Freshworks app. We now have the credentials to fetch the OAuth access token dynamically.
Let’s see how we can configure it in the Freshworks app.

Add Configuration to the app

In the Freshworks app, all the configurations required for OAuth handshake go in one file. That is oauth_config.json under /config/ directory in the app root directory.

Refer to the following sample OAuth configuration file

{ 
  "client_id": "********************",
  "client_secret": "********************",
  "authorize_url": "<https://example.com/oauth/authorize>",
  "token_url": "<https://example.com/oauth/access_token>",
  "options": {
    "scope": "read", "write"
  },
  "token_type": "account"
}

In this OAuth configuration,

  • The Client ID and Client Secrets are added in the respective properties of the JSON. These are mandatory attributes for the app with OAuth configuration.
  • The third-party authorization providers provide the authorization URL and token URL.
  • We can add any other required parameters for the third-party platform to this configuration file’s options attribute in this configuration file. For example, one of the popular parameters, scope, goes in the options object.

We have now configured the required details for the OAuth handshake. Let’s see how the access token fetched from a successful OAuth handshake can be utilized in the app.

Use the OAuth access token

OAuth access token and refresh token is stored by the Freshworks platform after a successful OAuth handshake. So, the request method platform feature has to be used to make HTTP requests with this access token.

Two steps are required to use this OAuth access token.

  1. Add <%= access_token %> template in place of the access token on the HTTP request header. The platform will replace this template with the actual access token stored by the Freshworks platform while initiating the request.
  2. Add the isOauth boolean with true as value in the request method option. The Freshworks platform requires this to identify this request and use the OAuth access token.

Now, the app will make the HTTP request with the actual OAuth access token fetched from a successful OAuth handshake between the Freshworks platform and the third-party authorization provider.
Refer to a sample request method that uses an OAuth access token.

Here are the next steps on learning OAuth and utilizing it to the fullest.

  1. Find the difference between agent and account-based OAuth authorization for token_type in the Freshworks Platform to choose a method according to your business need.
  2. Find the steps to test an app with OAuth. Check out the end-to-end testing to test how the OAuth will work in the actual product.
  3. Learn OAuth iparams (oauth_iparams) to get the dynamic parts in the OAuth configurations that the user can provide during the app installation time.
1 Like