Unlocking Secure Authentication: Implementing OAuth 2.0 Authorization in Your Freshworks Applications

Recently, APIs have become the core of any business. Developers are building apps and implementing multiple automations that allow an app to interact with several apps through APIs. Hence, it has become crucial to secure data and control the data access the apps hold.

When considering ways of securing APIs, the popular and secure way is using the OAuth 2.0 protocol. OAuth stands for Open Authorization. It is often mistaken for authentication but OAuth is an authorization protocol.

Freshworks always considers the security-first approach when it comes to data, and thus has introduced the functionality of securing APIs using OAuth 2.0.

This blog discusses the following:

• Entities involved in OAuth 2.0
• How OAuth 2.0 works
• Types of tokens in OAuth 2.0
• Types of Grant in OAuth 2.0

Entities involved in OAuth 2.0

Resource owner (Customer): Usually a user/customer who owns the resource and who can grant access to the application

Client (marketplace app): Application that requests/requires access to secured resources. OAuth defines two types of clients:

• Confidential client: Apps that use registered client credentials and are able to securely authenticate with the Freshworks Authentication server. It is usually an app submitted or published on the Freshworks marketplace.
• Public client: Apps that do not use registered client credentials. For example, an app running in browsers or on mobile devices.

Authorization Server (Freshworks Authentication service): The server that provides tokens to the authenticated client upon successful verification and consent from the resource owner. Usually, the Authorization server handles the following two endpoints:

• Authorization endpoint: Responsible for handling the authentication and consent from the resource owner
• Token Endpoint: Responsible for providing a token, which is used by the client to access the resource

Resource Server (Freshservice): The server that holds the protected resource and returns the appropriate resource by validating the access token from the client.

How OAuth 2.0 works

1. The client has to get registered using the Marketplace Developer portal with the following details:

• Scopes: List of resources that are to be accessed by the client. For example,. freshservice.ticket.manage
• Callback URL: The URL to which the Authorization Server will redirect during the OAuth handshake step. For a marketplace app, the following URLs can usually be mentioned:
  http://localhost:10001/auth/callback
  https://oauth.freshdev.io/auth/callback

2. Upon registering, the developer receives the client ID and client secret based on which the client will be authenticated during the OAuth handshake.

3. The developer then adds the OAuth credentials in the oauth_config.json(Link) file and publishes the app through the Marketplace Developer portal.

4. When the app is installed, the Marketplace identifies the app as an OAuth app and initiates the handshake requiring authorization to the Freshworks Authentication server by providing the client ID and client secret. It also provides the scopes and redirects the URI to which the authorization code will be passed.

5. The Freshworks Authentication server authenticates the clients, checking and validating the requested scopes, and the redirect URI matches the ones used during registration.

6. The customer/user of the Marketplace app provides their consent by interacting with the Freshworks Authorization server to provide grant

7. The Freshworks Authorization server redirects to redirect uri with the authorization code

8. The Marketplace platform, which hosts the app, uses the authorization code to exchange for access tokens and refresh tokens and to handle the complete token lifecycle.

9. With the access token used in the request template as mentioned in the OAuth to access the Freshworks resources document, the Marketplace app accesses APIs hosted by Freshservice

Types of tokens in OAuth 2.0

Access token: This token is validated by the resource server and is used to access resources. This is a short-lived token and there isn’t any standard format defined for it as per the OAuth standard. Most commonly, people use JSON Web Token (JWT) which includes data inside. This token is used within the Marketplace request templates

Refresh token: This token is used to obtain a new access token when an older token expires. It is a long-lived token with an expiry period not as short as that of an access token. Marketplace handles the regeneration of expired access tokens using the refresh token and then automatically places them in the request. App users will have to reauthorize the app when the refresh token expires.

Types of Grant in OAuth 2.0

The grant refers to the flow used by the client to get a token during the OAuth handshake.

Authorization code: The authorization server returns the authorization code (single-use) during the OAuth handshake, which is used to get access tokens. This type is usually handled by backend servers to securely manage client secrets.

PKCE (Proof Key for Code Exchange): An extension to the authorization code grant, designed to protect the authorization code injection making it useful for every type of client.

Client credentials: Typically used to access resources held by the client itself, rather than by the user.

Device authorization: Used by input-constrained devices like Smart TV, which exchanges the device code for the access token.

Refresh token: Used by clients to exchange a refresh token for an access token when the access token has expired.

Summary

OAuth 2.0 is a secure way of restricting access to APIs. With the entities and tokens involved during the OAuth handshake, OAuth 2.0 revolutionized how apps and services authenticate and authorize users.

Freshworks considers a security-first approach when it comes to data access and hence provides app developers the functionality to let their users securely access the data. To learn how app developers can implement OAuth 2.0 in their apps, check out the documentation.

Useful Resources:

• Developer Community Announcement: Click here
• Developer documentation: Click here
• Sample App: Freshservice OAuth for API