OAuth

You can use the OAuth 2 protocol to authorize the 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 simple oauth app for a demonstration of this feature.

Prerequisites

Please ensure that:

  1. You have SDK v2.2.1 or higher installed. You can find instructions on how to get the latest version here.
  2. 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.
  3. 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"
Create

If you want to create a new app with OAuth, run the following command:

$ frsh init [project directory name] -f oauth

Or, if you want to include the OAuth feature in your existing app, in your project directory, run the following command:

$ frsh update -a oauth

In the manifest.yml file, you will notice the following feature addition:

Copied Copy
1
2
features: - oauth
Configure

In the config/oauth_config.yml file, update the following fields listed in the table below:

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

Sample Configuration

oauth_config.yml

Copied Copy
1
2
3
4
5
6
7
client_id: "5eXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXc8d1" client_secret: "q8NbXXXXXXXXXXXXXXXX1p1" Authorize_url: "https://login.domain.com/authorize" token_url: "https://login.domain.com/token" options: scope: "read" token_type: "account"
Usage

You must use the request API to make requests to the third party domain. To do this, in the manifest file, include the Third-Party domain in the whitelisted-domains section. For more information, please refer to the Request API section.

Sample OAuth request

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
var headers = {"Authorization": "Bearer <%= access_token %>"}; var options = { headers: headers, isOAuth: true }; this.$request.get(url, options) .done(function(data) { }) .fail(function(err) { console.log(err); });
EXPAND ↓
Local Testing

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

The first time you perform local testing, you will need to authorize the app to access the third party resources. You will see an “Authorize” button within the app. Clicking this button will redirect you to the third party. After you authorize by providing the user 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.