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 sample apps for a demonstration of this feature.

Prerequisites

Ensure that you:

  • Have CLI v4.1.0 or higher installed. 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.

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 You can use options 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.
token_type Mandatory Specifies the level of access for the access token. Currently, the only value that we support is account.
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" }
EXPAND ↓
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 Front-end Component of the App

You must use the Request API 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.

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

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

  • Login to your Freshdesk account (if you do not have a Freshdesk account, sign up here).
  • Go to the Ticket Details page or Contact Details page where you enabled your app. In the address bar, append the URL with ?dev=true. For example, the URL should look like this: https://subdomain.freshdesk.com/helpdesk/tickets/1?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. Provide your credentials and the access and refresh tokens will be generated and stored in the .frsh/localstore file. (If you configured the Oauth installation parameters, you be redirected to a page where you can enter them.)

Log in with your Freshdesk account

Enter your helpdesk URL to proceed to login

Proceed

By clicking "Proceed", you agree to our Terms of Use.