Cover art attribution for OAuth logo (Chris Messina)

OAuth: Above & Beyond

The OAuth feature available on the Freshworks Developer Platform helps integrate an app with third-party services through a simple configuration and without the overhead of maintaining an OAuth client service to handle redirects. In this post, we’ll discuss new functionalities and how we can leverage them in different use cases.

What is OAuth2?

OAuth2 is an open standard that allows users to authorize an app to access user information from third-party services without sharing credentials.

Figure 1: The OAuth handshake (source — https://tools.ietf.org/html/rfc6749).

The Freshworks Developer Platform acts as the client which takes care of the handshake on behalf of the app as depicted in Figure 1. The obtained token is managed by the Platform and the app can use the token as part of the Request API.

OAuth Configuration

Here is a sample OAuth configuration, sections of which are explained across the blog.

oauth_config.json

{
    "client_id"    : "xxxxx-xxxx-xxxxx-xx",
    "client_secret": "yyyyy-yyyy-yyyyy-yy",
    "authorize_url": "https://login.acme.com/authorize",
    "token_url"    : "https://login.acme.com/token",
    "options": {
        "scope": "read"
    },
    "token_type": "account"
}

OAuth Installation Parameters

Like installation parameters, OAuth installation parameters are used when installing an app, including OAuth handshake and as part of Request API.

Figure 2: The OAuth handshake w.r.t OAuth installation parameters.

Sample Snippet (oauth_config.json)

"oauth_iparams": {
    "sub_domain": {
        "display_name": "Domain",
        "description" : "Please enter your domain",
        "type"        : "text",
        "required"   : true
     }
}

Usage (oauth_config.json)

"token_url": "https://<%= sub_domain.domain%>.acme.com/token"

Use Cases

The following interesting use cases can be solved by extending OAuth with other functionalities.

Dynamic subdomain

Some third-party services provide token and authorize URLs that are specific to an account subdomain.

https://myaccount.acme.com/token

Here, a static OAuth configuration does not hold good for dynamic fields. In this case, OAuth installation parameters can be configured to dynamically interpolate the subdomain obtained from users at the time of handshake.

"token_url": "https://<%= oauth_iparams.sub_domain%>.acme.com/token"

Dynamic client_id and client_secret

A typical product can have cloud (hosted by the vendor) and on-premise (hosted by the user) software, such as Jira and Confluence, and the OAuth configuration would be specific to the hosted system. This means a cloud OAuth configuration cannot be used with an on-premise system and vice versa.

Instead of developing two different apps for on-premise and cloud, an optional OAuth installation parameter can be configured to obtain the end-user value (client_id or client_secret) or the default value is used.

"client_id": "<%= oauth_iparams.client_id || 'xxxxxxxxx' %>"

Region-specific configuration

For third-party services that span multiple data centers, app users would need to choose region-specific OAuth configurations.

An optional OAuth installation parameter can be configured to obtain the end-user value (region) based on which a condition is evaluated.

"client_id": "<%= oauth_iparams.region == 'US' ? 'xxxxx': oauth_iparams.region == 'EU' ? 'yyyyy' : 'zzzzz' %>"

The above expression evaluates client_id to “xxxx” if the provided value for region is “US”, and to “yyyy” if it is “EU”, and defaults to “zzzz” otherwise.

Re-using OAuth parameters

In addition to the above functionalities, OAuth installation parameters can be re-used across the app.

For example, if the subdomains of OAuth URLs are account specific, the API endpoints for the same will also be account-specific. So, you can re-use the OAuth installation parameters as part of whitelisted-domains and Request API.

Whitelisted Domains (manifest.json)

"whitelisted-domains": [ 
    "https://<%= oauth_iparams.sub_domain %>.acme.com"
]

Request (app.js)

client.request
.post("https://<%= oauth_iparams.sub_domain %>.acme.com/api", {
    headers: {
        Authorization: "Basic <%= access_token %>"
    },
   json: { user: "acme_user"}   
});

From this post, you have an idea of how OAuth handshake can be customized to support various use cases, specifically how interpolating OAuth installation parameters into the configuration can be an effective and powerful tool.

If you have any questions you can reach us at marketplace@freshworks.com. Follow us on @FWMarketplace.