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
    }

OAuth request with domain whitelisting

Important:This mode of placing an OAuth request is supported only for building apps with platform version 2.2 and FDK versions prior to 9.0.0. Support for building apps on platform version 2.2 is scheduled for deprecation on Decemebr, 2023. Ensure to migrate to the latest platform and FDK versions. If you are on the latest FDK version (platform 2.3), to build apps that use the OAuth requests, see Use request method to place OAuth request.

  1. Include the third-party domain in the whitelisted-domains section of the manifest file as shown in the following code sample.
    manifest.json
    "whitelisted-domains": [
        "https://<sample>.com"
    ]
  2. To make requests from the front-end or serverless app component to the third-party domain, in either app.js (for front-end app) or server.js (for serverless app)
    1. Use the access_token variable to access the token.
    2. Include the isOAuth parameter in the options.
    var getFiles = function() {
    var self = this,
    path = "/",
    headers = { Authorization: "bearer <%= access_token %>"},
    reqData = { headers: headers, isOAuth: true },
    url = "https://api.onedrive.com/v1.0/drive/root:" + path +
                      ":/children";
    client.request.get(url, reqData).then(
        function(data) {
            console.log(data);
            // var response = JSON.parse(data.response)["value"];
            // handleSuccess(response);
        },
        function(error) {
            console.log(error)
            //handleError(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.