Setup OAuth

OAuth is a protocol that allows secure authorisation in a simple and standard method from web, mobile, and desktop applications. It enables third-party services to access a user's data without exposing their credentials.

Freshworks Developer Platform allows using OAuth to authenticate and authorise to third-party applications from the app ensuring secure access without exposing the credentials anywhere in the app.

Freshservice supports accessing it’s resources via API with OAuth mechanism for authentication and authorisation.

To create OAuth credentials for Freshservice from the Freshworks developer platform:

1. Create the OAuth app in the Freshworks Devleper Platform following the steps form the documentation (https://developers.freshworks.com/docs/app-sdk/v3.0/service_ticket/advanced-interfaces/request-method/oauth-access-freshworks-resources/).
2. Find the required scopes for your app's functionality, ensuring it has access to the necessary resources on Freshservice. For this app, we only need “Freshservice.Tickets.Create” scope under “Tickets” section.
3. Keep the client ID and client secret securely and it is required to configure in the app.

Using the credentials involves configuring the OAuth settings in your app:

1. Let’s include the OAuth configuration file in your app by creating a JSON file under “/config” folder with the name "oauth_config.json".
2. Add the following content to the file.

{
  "integrations": {
    "freshservice": {
      "display_name": "Freshservice",
      "client_id": "YOUR_CLIENT_ID",
      "client_secret": "YOUR_CLIENT_SECRET",
      "authorize_url": "https://<%= oauth_iparams.freshworks_org_domain %>/org/oauth/v2/authorize",
      "token_url": "https://<%= oauth_iparams.freshworks_org_domain %>/org/oauth/v2/token",
      "options": {
        "scope": "freshservice.tickets.create",
        "customHeaders": {
          "Authorization": "Basic BASE64_ENCODED_VALUE_OF_YOUR_CLIENT_ID:YOUR_CLIENT_SECRET"
        }
      },
      "token_type": "account",
      "oauth_iparams": {
        "freshworks_org_domain": {
          "display_name": "Your Freshworks organisation domain",
          "description": "Enter your Freshworks organisation domain. For example, samplecompany.myfreshworks.com",
          "type": "text",
          "required": true
        }
      }
    }
  }
}

1. In the file content, add your actual Client ID and Client Secret in the place of their values and add the Base64 encoded value of your client id and secret in the place of Authorization header value.
2. In the file, we have also added the scope, URLs to authorise and get token.
3. The authorisation and token URL requires the Freshworks Organisation’s domain in them. So, we request the same dynamically from the OAuth iparams in the same OAuth config. This will be requested from the user additionally when installing the app before the OAuth handshake will happen.

Testing the OAuth handshake ensures that your app can securely obtain access tokens:

1. Run the app with “fdk run” command again.
2. Install the app from the Custom App section in the Marketplace and it will process the authorisation.
3. The app will request for the installation parameters, then OAuth iparams, and then it will execute the OAuth handshake and user will be requested to authorise in the Freshworks organisation’s authorisation page with the relevant scope and OAuth credential name defined.
4. After you authorise as a user, the app will proceed to install and complete the installation.
5. This OAuth handshake will fail with proper error message if any of the inputs in the OAuth credentials or configurations are wrong. Correct them and install the app again to retest until the app installation completes successfully.

We have added the OAuth configuration to the app. Now, let’s use it in the API to create a ticket.