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 the OAuth-secured resources.

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.

Prerequisites

Ensure that you:

  1. Register your app with the third-party resource provider. After registration, a client_id and client_secret to perform OAuth handshake is 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

Set up the OAuth configuration file

Enter appropriate values for the following attributes of the config/oauth_config.json file.

  • client_idstringRequired

    Client ID for your app. The OAuth-secured resource provider gives this information when you register your app with them.

  • client_secretstringRequired

    Client credential for your app. The OAuth-secured resource provider gives this information when you register your app with them.

  • authorize_urlstringRequired

    Authorization URL to which your app must place the request for authorization grant.

  • token_urlstringRequired

    URL to which your app must (use the authorization grant and) place the request for access token.

  • optionsobject

    Additional parameters that the third-party provider might require, specified as key: value pairs. For example, some third-party providers require scope to be defined to control the level of access on the resource. Some third-party providers require custom headers such as follows to be defined.

    "customHeaders": { "Authorization" : "Basic API_KEY" }
  • token_typestringRequired

    Specifies the access permissions on the resources.

    Possible values:

    • agent: Authorization handshake is initiated when an agent installs the app.
    • account: Authorization handshake is initiated only when an admin installs the app.

    Important:token_type cannot be agent for serverless or apps that run in the background.

  • oauth_iparamsobject

    Installation parameters whose values need to be retrieved from the app user during installation, to complete the OAuth handshake.

    Only parameters of type text are supported.

Use request method to place OAuth request

  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.isOAuth as true.
    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": {
      "isOAuth": true
    }
  }
}
  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).
    try {
  let workspace = await client.request.invokeTemplate(
    "asanaGetWorkspace",
    {}
  );
  //handle success
} catch (err) {
  //handle error
}

Test apps that use OAuth

Note:For testing, use the latest version of Chrome browser.

  1. From your terminal, navigate to the app project directory, and execute the following command.

    fdk run

  2. Log in to your product account.

  3. Navigate to the page where your app is deployed. In the address bar, append the URL with ?dev=true.

    Example URL: https://subdomain.Freshworks-product.com/helpdesk/tickets/1?dev=true

  4. The first time you test your app, click Authorize on the app’s front-end, to enable the app to perform OAuth handshake.

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

  • The .fdk/localstore file for token_type as account.
  • The browser's localStorage for token_type as agent.