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.
Important:- For apps built using platform v3.0,
- We support multi-OAuth configurations. It means, during its lifecycle, an app can access multiple OAuth-secured resources. Currently, this feature lets your app access a maximum of three OAuth-secured resources.
- Out of the three OAuth configurations, only one can be a configuration that facilitates agent installation.
- For apps built using platform v3.1 and later,
- We support multi-OAuth configurations. It means that during its lifecycle an app can access multiple OAuth-secured resources. Currently, this feature lets your app access a maximum of five OAuth-secured resources.
- Currently, only account-level authorization is supported. This means that if your app uses the multi-OAuth configuration, each OAuth configuration facilitates account-level authorization only.
- Along with multi-OAuth configurations, you can configure multiple accounts under a single OAuth-secured resource during app installation. For example, if you have multiple accounts or stores on Shopify, you can choose which specific account or store to use when placing the authorization request.
- To enable your app to place an authorization request for a particular account, use the request method, define the $credentials.oauth method in the server.js file, and see the Test apps that use OAuth section for testing the functionality.
- The multi-account feature allows your app to access up to 20 accounts per OAuth-secured resource.
To do this,
- Ensure that the prerequisites (app registration with the third-party OAuth resource provider) are met.
- Set up the OAuth configuration file.
- Use request method to place the request to OAuth-secured resources.
For a demonstration of this feature, see the OAuth Freshdesk sample app.
Prerequisites
Ensure that you:
- Register your app with the third-party resource provider. After registration, the client_id and client_secret to perform OAuth handshake are provided.
- Specify the following redirect URLs to the third-party provider.
- Testing: http://localhost:10001/auth/callback
- Production: https://oauth.freshdev.io/auth/callback
Set up the OAuth configuration file
- 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).
- 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
- <oauth_configuration_name>objectRequired
Meaningful identifier of the third-party whose OAuth resource the app intends to access. This value is used at run-time to place the request method call.
Notes:- For apps built on platform v3.0, you can configure a maximum of three <oauth_configuration_name> configurations.
- For apps built on platform v3.1 or later, you can configure a maximum of five <oauth_configuration_name> configurations. Currently, only account-level authorization is supported.
Use request method to place OAuth request
- Provide a snapshot of the request to be made to the third-party domain, in config/requests.json.
- Use the access_token variable in <requestTemplateName>.schema.header.Authorization.
- 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" } } }
- Declare the configured template (snapshot) in manifest.json.Sample manifest.json
{ … "requests": { "asanaGetWorkspace": {} } }
- Invoke the template from the app code in either app.js (for front-end app) or server.js (for serverless app).Sample app.jsSample server.js
try { let workspace = await client.request.invokeTemplate( "asanaGetWorkspace", {} ); //handle success } catch (err) { //handle error }
Define the credentials.oauth method in app code
Important:This section applies if you are building apps on platform version 3.1 or later. If you are building apps for platform version 3.0, skip this section and proceed to the Test apps that use OAuth section.
The credentials.oauth method enables you to get the account name passed to the app during app installation. Within this method, define the oauthName key and assign it the name of the OAuth-secured resource as specified in the oauth_configs.json file of your app.
The version key specifies the payload version to be returned by the credentials.oauth method. Currently, the version key accepts v1 as its value.
const credentials = await $credentials.oauth({ version: 'v1' }).get({ oauthName: 'asana' });
Test apps that use OAuth
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.
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.
In the system settings page,
- Select the modules for which you want to test the OAuth app.
- In the corresponding Enter account URL section, enter valid account URL(s) for the product(s) to which the selected modules belong.
- 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.
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.
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.
For front-end apps that do not run in the background,
Log in to the Freshworks product account where you want to test the app deployment.
To the default account URL displayed in the address bar, append ?dev=true.
Example URL: https://subdomain.freshdesk.com/helpdesk/tickets/1?dev=true.
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.
Click Authorize, to enable the app to perform OAuth handshake.
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.