Use request method to access OAuth-secured resources

Some resource providers allow access to secure resources only after a successful OAuth handshake. Through the developer platform’s request method interface, you can enable your app to successfully place a request to access multiple OAuth-secured resources.

Note:Either an agent (individual product user) who uses the Freshworks product or an admin can install apps. Admins can install apps at an account level. After installation, an app that uses OAuth to access third-party resources, requires authorization before app users start to use the app. In account-level installations, the server-side places the authorization call to the secure resource and to provide client context, the server-side passes a client ID and client secret (think of it as a password) to the resource. In agent installations, all details are loaded onto the client (agent browser) along with the app and the client places the authorization call to the resource. So, client ID and client secret are not required during the call to the authorization server.

To do this,

1. Ensure that the prerequisites (app registration with the third-party OAuth resource provider) are met.
2. Set up the OAuth configuration file.
3. Use request method to place the request to OAuth-secured resources.

For a demonstration of this feature, see the OAuth Freshdesk sample app.

Ensure that you:

1. Register your app with the third-party resource provider. After registration, the client_id and client_secret to perform OAuth handshake are provided.
2. Specify the following redirect URLs to the third-party provider.

• Testing: http://localhost:10001/auth/callback
• Production: https://oauth.freshdev.io/auth/callback

1. From the app’s root directory, navigate to the config folder and create an oauth_config.json file (if oauth_config.json does not exist).
2. In the oauth_config.json file, use the syntax on the right-pane to configure all OAuth configurations that the app is expected to use, as JSON objects.

Attributes of the OAUTH_CONFIG.JSON.integrations object

1. Provide a snapshot of the request to be made to the third-party domain, in config/requests.json.
   1. Use the access_token variable in <requestTemplateName>.schema.header.Authorization.
   2. Set <requestTemplateName>.options.oauth to the <oauth_configuration_name> value defined in oauth_configs.json.
   Sample config/requests.json

   {
     "asanaGetWorkspace": {
       "schema": {
         "method": "GET",
         "host": "app.asana.com",
         "path": "/api/1.0/workspaces",
         "headers": {
           "Authorization": "bearer <%= access_token %>",
           "Content-Type": "application/json"
         }
       },
       "options": {
         "oauth": "asana"
       }
     }
   }
   

2. Declare the configured template (snapshot) in manifest.json.
   Sample manifest.json

   {
     …
     "requests": {
       "asanaGetWorkspace": {}
     }
   }

3. Invoke the template from the app code in either app.js (for front-end app) or server.js (for serverless app).
   Sample app.js

   Sample server.js

   try {
     let workspace = await client.request.invokeTemplate(
       "asanaGetWorkspace",
       {}
     );
     //handle success
   } catch (err) {
     //handle error
   }

1. From the command line, navigate to the directory that contains the app related files and run the fdk run command. The FDK starts the local test server.

2. To enter the OAuth configurations, navigate to http://localhost:10001/custom_configs. As a first step, the system settings page is displayed. All modules configured in the App manifest are listed.

3. In the system settings page,

   1. Select the modules for which you want to test the OAuth app.
   2. In the corresponding Enter account URL section, enter valid account URL(s) for the product(s) to which the selected modules belong.
   3. Click Save & Continue.

   The OAuth configurations page is displayed prompting for client ID and client Secret. Enter appropriate values and click Submit.

   Notes:

   • For agent-level installations (oauth_config.json.intergrations.oauth_configuration_name.token_type is agent) the OAuth configurations page is not displayed.

   • If there are multiple OAuth configurations, the configuration page for each OAuth is displayed based on the order in which the configurations are defined in oauth_config.json.

4. If you have configured OAuth iparams, the configuration settings page is displayed. Enter appropriate values and click Save & Continue.

   Note: If there are multiple OAuth configurations and if the configurations contain OAuth iparams, the configuration settings page for each OAuth is displayed based on the order in which the configurations are defined in oauth_config.json.

5. If you have configured installation parameters for the app, the App Settings page is displayed at http://localhost:10001/custom_configs. Enter appropriate values for the installation parameters and click Install.

6. For front-end apps that do not run in the background,

   1. Log in to the Freshworks product account where you want to test the app deployment.

   2. To the default account URL displayed in the address bar, append ?dev=true.

      Example URL: https://subdomain.freshdesk.com/helpdesk/tickets/1?dev=true.

   3. Navigate to the appropriate location where the app is intended to be deployed, verify that the app is rendered. On the app’s front-end an Authorize button is displayed.

   4. Click Authorize, to enable the app to perform OAuth handshake.

7. For serverless apps and apps that run in the background, you can publish the app as a Custom app, navigate to the App Management Portal and Configure or Authorize your app.

After a successful handshake, the generated token is stored in:

• The .fdk/localstore file when token_type is account.
• The browser's localStorage when token_type is agent.