OAuth

The OAuth 2 protocol enables authorizing an app to access resources from third-party applications. This is done by using an access token obtained from the third-party when the app is installed.

To see a demonstration of this feature, see the OneDrive and Asana Freshdesk sample apps.

Prerequisites

Ensure that you:

  • Register your app in the third-party developer portal. Once registered, you will be issued a client_id and client_secret to perform OAuth handshake with the provider.
  • Provide the redirect URL for your app in the third-party developer portal.
    • Testing: http://localhost:10001/auth/callback
    • Production: https://oauth.freshdev.io/auth/callback

Set up OAuth configuration file

Update the following fields in the config/oauth_config.json file.

FieldDescription
client_id Mandatory Once you register your app in the third-party developer portal, you will be issued a client ID for your app.
client_secret Mandatory Once you register your app in the third-party developer portal, you will be issued a client secret for your app.
authorize_url Mandatory Third-party authorization request URL.
token_url Mandatory Request URL for the access token.
optionsThe options field can be used to send:
  • Additional parameters to the resource owner while fetching the access token. For example, some third-party owners accept an option called scope to control the level of access on the resource.
  • Custom headers as part of the token phase as required by certain third-party services. For this, custom headers can be included in the options field as an object.
    "customHeaders": { "Authorization" : "Basic API_KEY" }
token_type Mandatory Specifies the level of access for the access token. We support the following values:
  • account - Authorization happens when the app is installed by the admin.
  • agent - Authorization happens when the app is accessed by an agent. Note:Note: Agent-level OAuth does not support apps in background locations and serverless apps.

oauth_iparams

Certain OAuth providers, such as Shopify, have unique authorization URLs for every account. The oauth_iparams enable you to retrieve these values from the installer before the OAuth handshake occurs. These parameters are configured in the same manner as the installation parameters.

Only parameters of type text are supported.

Define OAuth request

  1. Provide a snapshot of the request to be made to the third-party domain, in config/requests.json.
    1. Use the access_token variable in <requestTemplateName>.schema.header.Authorization.
    2. Set <requestTemplateName>.options.isOAuth as true.
    Sample config/requests.json
    {
  "asanaGetWorkspace": {
    "schema": {
      "method": "GET",
      "host": "app.asana.com",
      "path": "/api/1.0/workspaces",
      "headers": {
        "Authorization": "bearer <%= access_token %>",
        "Content-Type": "application/json"
      }
    },
    "options": {
      "isOAuth": true
    }
  }
}
  2. Declare the configured template (snapshot) in manifest.json.
    Sample manifest.json
    {
  …
  "requests": {
    "asanaGetWorkspace": {}
  }
}
  3. Invoke the template from the app code in either app.js (for front-end app) or server.js (for serverless app).
    try {
  let workspace = await client.request.invokeTemplate(
    "asanaGetWorkspace",
    {}
  );
  //handle success
} catch (err) {
  //handle error
}

Test apps that use OAuth

Note:For testing, use the latest version of Chrome browser.

  1. Open your console, navigate to your project directory, and execute the following command.

    fdk run

  2. Log in to your Freshsales Suite account.

  3. Go to the page where you have enabled your app. In the address bar, append the URL with ?dev=true. For example, the URL should look like this: https://domain.myfreshworks.com/crm/sales?dev=true

  4. The first time you test your app, you need to authorize the app to access information from the third-party. In the app, click the Authorize button to redirect to the third-party domain.

    The generated token is stored in:

    • The .fdk/localstore file for account level.
    • The browser's localStorage for agent level.