OAuth

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 Freshteam.

Prerequisites

Ensure that you:

  • 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.

FIELD DESCRIPTION
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.
options The 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. 
    1
    		"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: 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.

Sample Configuration
Copied Copy 
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.

Copied Copy 
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
       }
     }
   }
EXPAND ↓
Usage

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

Copied Copy 
1
2
3
"whitelisted-domains": [
      "https://api.onedrive.com"
    ]
Sample OAuth Request from the Serverless Component of the App

You must use $request to make OAuth requests from the serverless component of the app to the third-party domain by including the isOAuth parameter in the options. Use the access_token variable to access the token.

Copied Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
function oauthCallback() {
      var headers = {
          "Authorization": "bearer <%= access_token %>"
      };
      var reqData = {
          headers: headers,
          isOAuth: true
      };

      $request.get("https://api.onedrive.com/v1.0/drive/root:/:/children", reqData)
          .then(function(data) {
              // success
              console.log("oauth " + _.keys(data) + " " + data.status + " " + _.keys(JSON.parse(data.response)));
          }, function(err) {
              // failure
              console.log(err);
        });
  }
EXPAND ↓
Testing

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

  • From the command prompt, navigate to the project folder, and run the following command. $ fdk run
  • Log in to your Freshteam account.
  • To the Freshteam account URL append ?dev=true. Example URL: https://domain.freshteam.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.