You can use the OAuth 2 protocol to authorize 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.

Take a look at OneDrive and Asana Freshdesk sample apps for a demonstration of this feature. The same functionality is available in Freshcaller.

Prerequisites

Ensure that you:

• Have CLI v4.5.0 installed for agent-level OAuth. For more information on how to get the latest version, click here.
• Register your app in the third-party developer portal. Once registered, you will be issued with 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

Configure

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

Sample Configuration

1
2
3
4
5
6
7
8
9
10
{
      "client_id": "5eXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXc8d1",
      "client_secret": "q8NbXXXXXXXXXXXXXXXX1p1",
      "authorize_url": "https://login.domain.com/authorize.srf",
      "token_url": "https://login.domain.com/token.srf",
      "options": {
        "scope": "read"
      },
      "token_type": "account"
    }

Sample Configuration with OAuth Installation Parameters

In this example, both authorize_url and token_url are retrieved from the installer during installation.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
     "client_id": "5eXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXc8d1",
     "client_secret": "q8NbXXXXXXXXXXXXXXXX1p1",
     "authorize_url": "https://<%= oauth_iparams.domain %>/authorize.srf",
     "token_url": "https://<%= oauth_iparams.domain %>/token.srf",
     "options": {
       "scope": "read"
     },
     "token_type": "account",
     "oauth_iparams": {
       "domain": {
         "display_name": "Shopify domain",
         "description": "Please enter your Shopify domain",
         "type": "text",
         "required": true
       },
       "client_id": {
         "display_name": "Shopify Client ID",
         "description": "Please enter your Shopify client ID",
         "type": "text",
         "required": true
       },
       "client_secret": {
         "display_name": "Shopify Client Secret",
         "description": "Please enter your Shopify client secret",
         "type": "text",
         "required": true
       }
     }
   }

Usage

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

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   {
     "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
           }
         }
       }

   EXPAND ↓
2. Declare the configured template (snapshot) in manifest.json.

   Sample manifest.json

   1
   2
   3
   4
   5
   6
   {
           …
           "requests": {
               "asanaGetWorkspace": {}
           }
       }

3. For front-end apps, invoke the template from the app code in app.js.

   Sample app.js

   1
   2
   3
   4
   5
   6
   7
   …	
       try {
           let workspace = await client.request.invokeTemplate("asanaGetWorkspace",{});
               //handle success
           } catch (err) {
               //handle error
       }

4. For serverless apps, invoke the template from the app code in server.js.

   Sample server.js

   1
   2
   3
   4
   5
   6
   7
   …
     try {
         await $request.invokeTemplate("asanaGetWorkspace",{});
             //handle success
         } catch (error) {
             //handle error
     }

OAuth request with domain whitelisting

First, include the third-party domain in the whitelisted-domains section of the manifest file as shown in the following code sample.

1
2
3
"whitelisted-domains": [
  "https://api.onedrive.com"
]

Sample OAuth Request from the Front-end Component of the App

You must use the Request method to make requests from the front-end to the third-party domain by including the isOAuth parameter in the options. Use the access_token variable to access the token.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
var getFiles = function() {
  var self = this,
  path = "/",
  headers = { Authorization: "bearer <%= access_token %>"},
  reqData = { headers: headers, isOAuth: true },
  url = "https://api.onedrive.com/v1.0/drive/root:" + path +
    ":/children";
  client.request.get(url, reqData).then(
    function(data) {
      console.log(data);
        // var response = JSON.parse(data.response)["value"];
        // handleSuccess(response);
    },
    function(error) {
      console.log(error)
      //handleError(error);
    }
  );
}

Test apps that use OAuth

Note: For testing, we recommend that you use the latest version of Chrome browser.

Open your console, navigate to your project directory, and execute the following command. $ fdk run

• Log in to your Freshcaller account.
• To the Freshcaller account URL append ?dev=true. Example URL: https://domain.freshcaller.com/dashboard?dev=true..

  The first time you test your app, you need to authorize the app to access information from the third-party.

  1. In the app, click the Authorize button to redirect to the third-party domain.
  2. The generated token is stored in:
     1. The .fdk/localstore file for account level.
     2. The browser's localStorage for agent level.