OAuth

You can use the OAuth 2 protocol to authorize an app to access resources from third-party applications. This is done by using the access token which is obtained from the third-party when the app is installed.

Take a look at the OneDrive sample app and the Asana sample app for a demonstration of this feature.

Prerequisites

Please ensure that:

  • You have CLI v4.1.0 or higher installed. You can find instructions on how to get the latest version here.
  • You have registered 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.
  • You have provided the redirect URI for your app in the Third-Party developer portal:
    • Local Testing: "http://localhost:10001/auth/callback"
    • Production: "https://oauth.freshdev.io/auth/callback"
Configure

In the config/oauth_config.json file, update the following fields:

FIELD DESCRIPTION
client_id Mandatory Once you register your app in the Third-Party developer portal, you will be issued a unique 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 authorization URLs that are unique for every account. 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 the authorize_url and the token_url are based on the installer's Shopify domain. Hence it is retrieved from the installer during installation and substituted in the authorize and token URL.

Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{ "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 } } }
EXPAND ↓
Usage

First, include the Third-Party domain in the whitelisted-domains section of the manifest file as shown below:

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. To make requests using OAuth, you should include the isOAuth parameter in the options. The access token will be accessible using the access_token variable.

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. You must include the isOAuth parameter in the options. The access token will be accessible using the access_token variable.

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 ↓
Local Testing

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

  • Log into your Freshdesk account (if you do not have a Freshdesk account, sign up here).
  • Go to ticket details page or contact details 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://subdomain.freshdesk.com/helpdesk/tickets/1?dev=true.

    The first time you perform local testing, you will need to authorize the app to access information from the third-party. You will see an Authorize button within the app as shown below: Clicking this button will redirect you to the third-party (If you have configured Oauth installation parameters, you will first be redirected to a page where you can enter them). After you authorize by providing the credentials, the access token and refresh token will be generated and stored in the .frsh/localstore file.

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.