Authorization with OAuth 2.0

We have seen what is OAuth and how Freshworks apps use it. Let's look at how it actually works by using it in our app.

To create OAuth credentials for Asana:

1. Go to the Asana Developer Console at Asana Developer Console.
2. Log in with your Asana account.
3. Click on "Create new app" card.
4. Fill in the app details such as "App Name" and "purpose".
5. Click "Create App" to generate your OAuth credentials.
6. Note down the "Client ID" and "Client Secret" provided by Asana securely. These will be used in your app’s OAuth configuration.

To create OAuth credentials for GitHub:

1. Go to GitHub and log in to your account.
2. Navigate to GitHub Developer Settings.
3. Under "OAuth Apps", click "New OAuth App".
4. Fill out the form with your app’s details:
   1. "Application Name": Your app's name.
   2. "Homepage URL": The URL of your app.
   3. "Authorization callback URL": The URL where users will be sent after authorization. Find the redirect URL for Freshworks apps in the documentation.
5. Click "Register Application" to generate your OAuth credentials.
6. You will receive a "Client ID" and "Client Secret". These credentials are required for your app’s OAuth configuration.

Using the credentials involves configuring the OAuth settings in your app:

1. Let’s include the OAuth configuration file in your app by creating a JSON file under the “/config” folder with the name "oauth_config.json".
2. Add the following content to the file.

1{
2  "integrations": {
3    "asana": {
4      "display_name": "Asana",
5      "client_id": "YOUR_CLIENT_ID",
6      "client_secret": "YOUR_CLIENT_SECRET",
7      "authorize_url": "https://app.asana.com/-/oauth_authorize",
8      "token_url": "https://app.asana.com/-/oauth_token",
9      "options": {
10          "scope": "default"
11      },
12      "token_type": "account"
13    },
14    "github": {
15      "display_name": "GitHub",
16      "client_id": "YOUR_CLIENT_ID",
17      "client_secret": "YOUR_CLIENT_SECRET",
18      "authorize_url": "https://github.com/login/oauth/authorize",
19      "token_url": "https://github.com/login/oauth/access_token",
20      "options": {
21        "scope": "repo"
22      },
23      "token_type": "account"
24    }
25  }
26}

Replace YOUR_ASANA_CLIENT_ID, YOUR_ASANA_CLIENT_SECRET, YOUR_GITHUB_CLIENT_ID, and YOUR_GITHUB_CLIENT_SECRET with the actual credentials you obtained from Asana and GitHub.

Testing the OAuth handshake ensures that your app can securely obtain access tokens:

1. Run the app with fdk run command again.
2. Install the app from the Custom App section in the Marketplace and it will process the authorisation.
3. The app will request for the installation parameters, then OAuth iparams, and then it will execute the OAuth handshake and user will be requested to authorise in the Asana and GitHub's authorisation page with the relevant scope and OAuth credential name defined.
4. After you authorise as a user, the app will proceed to install and complete the installation.
5. If any of the OAuth handshake fails, it will be returned to the Freshworks Marketplace page with proper error message if any of the inputs in the OAuth credentials or configurations are wrong. Correct them and install the app again to retest until the app installation completes successfully.

We have added the OAuth configuration to the app. Now, let’s use it in the APIs made to Asana and GitHub.