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.
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
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:
|
||
token_type Mandatory | Specifies the level of access for the access token. We support the following values:
|
||
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 Copy1 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 Copy1 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 } } } |
Usage
First, include the third-party domain in the whitelisted-domains section of the manifest file as shown in the following code sample.
Copied Copy1 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.
Copied Copy1 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); } ); } |
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 Copy1 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); }); } |
Testing
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 Freshsales account.
- To the Freshsales account URL, append ?dev=true.
Example URL: https://domain.myfreshworks.com/crm/sales?dev=trueThe first time you test your app, you need to authorize the app to access information from the third-party.
- In the app, cick 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.