How to add OAuth in a Freshworks app

Wiki How To's
,
1

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.

The Freshworks developer platform takes care of making the OAuth handshake with the third-party authentication provider and get the required Access token and Refresh token, refresh the Access token automatically when it expires using the Refresh token. From the app developer, create the OAuth app on the third-party authentication provider side and fill in the OAuth configurations on your Freshworks app to do the OAuth handshake and get the resource for you.

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. Freshworks Developer Platform only uses Authorisation code grant type to fetch the tokens. 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.

Troubleshooting

Where does the access token and refresh token stored when testing in the local environment?

After successful authorization, the access token and refresh token are stored in the .fdk/localstore file in the app directory. If the refresh token is not stored, it was not received from the resource owner.

How to test the negative use case for an unauthorized access token in the local environment?

When testing in the local environment, the access token is stored in the .fdk/localstore file in the app directory. It can be modified to make the token incorrect and expect the resource owner to return an unauthorized access token error. This behavior is not certified by the platform, so it may or may not work depending on the platform’s and third-party resource owner’s behavior in the future.

How to verify the OAuth configuration changes in the custom app or Freshworks app?

The OAuth configuration changes will only take effect after the successful reauthorization when updating the app. It would be better to test the changed behavior of the modified OAuth configuration in the app by reauthorizing the app again after updating the app.

How to ensure the right configurations are used in the app for the desired authorization behavior?

The third-party resource owners provide various options for different behaviors that can be used for the desired action by the app. The additional parameters are passed in the options property of the OAuth configuration JSON (config/oauth_config.json) file in the app.

The examples are,

  1. The scope parameter is defined in most OAuth authorization with resource owners. Only the requested scopes will be allowed to do actions with the provided credentials, and the app cannot do actions beyond the requested scope access. Choosing the right scope to get access to the resources will avoid confusion.
  2. Some resource owners will provide an optional parameter to skip receiving the refresh token. If used that parameter, the refresh token will not be sent to the app, and only the access token will be received after the successful OAuth handshake.
  3. Some resource owners will provide an optional parameter to skip reauthorization every time after the access token expiry. Unless using this parameter, the authorization has to happen again to refresh the access token. This behavior can also be vice versa, on which behavior is considered by default by the resource owner. Most likely, you would not want to give the user an additional burden to reauthorize again after the access token is expired and would want to skip reauthorization by using the appropriate parameter.

Resources:

  1. A simplified reference for OAuth 2.0
  2. A simplified explainer article for OAuth 2.0
3 Likes