Freshworks Introduces Multi-OAuth Functionality for App Developers!
Previously, Freshworks developers creating apps with OAuth capability faced a limitation where they could configure only a single integration within the app. This constraint led developers to create multiple individual OAuth applications to address a use case, which was a lot of work.
Freshworks recently introduced a new capability called Multi-OAuth for developers. This big change means developers have the capability to build a single app that facilitates the OAuth configuration of multiple integrations. This enables the admin/agents to initiate multi-oauth handshakes seamlessly for all integrations through a single app installation.
UPDATE: Freshservice APIs now support Oauth authentication. The OAuth capability not only empowers customers to seamlessly and securely install apps directly from the Marketplace but also ensures a trusted integration experience.
Freshworks OAuth - What’s New!
The OAuth support offered by the Freshservice product streamlines the integration experience for both, developers and end-users. Developers can now register their apps with the Freshworks Identity platform (FreshID) and customers can authorize access to these apps without sharing sensitive information (such as the API key when authorizing the apps).
This new capability offered by Freshworks enables app developers to generate OAuth credentials for an app. The app can use the credentials to request an authorization code, use the authorization code to request an access token, and use the access token to access the REST APIs. When OAuth is configured at an account level, the account admin needs to navigate to the Marketplace and authorize the permissions during app installation. After successful authorization, the app is installed in the account. When OAuth is configured at agent level, the agents need to authorize the front-end app before using it in the account. After successful authorization, the agent can use the front-end app.
For app developers, the Freshworks APIs are accessible through the OAuth framework. During the app creation, the app developer when creating Oauth credentials specifies the scopes based on the permissions needed by the app. The users of the app (admin and agent) are shown a consent screen requesting their consent for the app to gain these permissions, when the app is being installed or used for the first time. The Freshworks OAuth feature not only enhances security but gives developers and account admins more control over app permissions and access.
Note: Currently Freshworks OAuth feature is available only for Freshservice APIs.
Visit this link https://api.freshservice.com/ to know the OAuth scopes required for the Freshservice APIs.
Here’s a high-level overview of the OAuth flow in your Freshworks app that accesses Freshservice resources:
- App developers can create the OAuth credentials and register their app with the Freshworks App Management portal.
- On app installation, it allows the admin to grant authorization for the app to operate on their behalf and access data
- The app orchestrates a flow with the Freshworks authorization server to request and obtain the access token
- Once the access token is retrieved, the app is allowed to make API calls to Freshservice with this access token.
Developer Journey
Here’s how you can create the OAuth credentials for your OAuth app:
- Log into your developer account and go to your profile and under settings click on the button “Create OAuth Credentials”.
- On the Create New OAuth credentials page, provide the necessary information such as app name, description, redirect URLs, and scopes. Click the “Create Credentials” button. The client ID and client secret are generated for the app.
Important note:
- Once credentials are generated they cannot be deleted.
- Scopes cannot be removed from credentials, only new scopes can be added which causes a consent check for the additional scopes when the admin installs the newer version of the app which uses credentials containing the updated scopes.
- View your existing Oauth credentials under your profile. You can click “View” to edit the redirect URLs and scopes.
As a developer, you can now build an app using the existing/new OAuth credentials. Freshworks App Management Portal allows developers to use one Freshworks OAuth credential per app. A developer can configure the OAuth credentials from multiple vendors in the same app.
Note: 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, and the other two need to be an account-level OAuth.
The OAuth feature in your app can be implemented under three different scenarios:
- When Freshworks app intends to access Freshworks resources
- When the Freshworks app intends to access external resources
- When an external app intends to access Freshworks resources
For more detailed information, visit the resources section shared below.
With this feature release, Freshworks apps built using FDK 9.1.0 and external apps built using third-party SDKs can access Freshworks APIs through OAuth. After FreshID generates the OAuth credentials for your app, a developer can modify the Redirect URLs and App Scopes if needed.
For detailed information on the OAuth framework, visit the link - What’s New
App User’s Journey
An admin who uses Freshservice can install the OAuth app available on the Marketplace.
Agent installation:
If OAuth is configured on an agent level, after installing the OAuth app, users are prompted to authorize it before they can begin utilizing the app. Once the agent using the app hits the authorize button, the permission required by the app (based on the scopes declared when generating Oauth credentials) are displayed on the consent window and upon hitting ‘Agree’, the app can call Freshservice APIs to get the required data. In case of hitting ‘Cancel’, The app remains unauthorized.
Admin installation:
If OAuth is configured on an account level, when the account admin installs the app, the associated accounts are displayed and prompt the admin to select the account where they want to install the app. The admin also goes through the consent flow to authorize the app, post which the app can call the Freshservice APIs to perform the required operations. Once the authorization is given, the app logic places the request to access resources.
The app that uses the OAuth credentials requests for the authorization code, and uses the authorization code to request an access token. The access token is then used to access the resources. The access token has a lifetime of 30 minutes whereas the refresh token has a validity of 365 days. When a refresh token expires the app developer will have to show appropriate UI to allow reauthorization for the agent. For admin, the app reauthorization can be performed from the app settings.
In case you have questions, you can go to Topics tagged oauth and create a new topic with the ‘oauth’ tag for us to be able to answer your OAuth queries.
As Freshworks continues to innovate, we look forward to seeing the diverse and secure applications our developer community will create using the enhanced authentication capabilities. Stay tuned for more updates.
Dev resources
Developer documentation - What’s New
Sample App - Freshservice OAuth for API
Tech blog - Unlocking Secure Authentication
Community Hours - Tech Talk on 16th May 2024
Developer FAQs
What is Multi-Oauth, and why is it important for the developers on the Freshworks developer platform?
We support Multi-OAuth configurations. It means, a single app can access multiple OAuth-secured resources. A developer can configure the OAuth credentials from multiple vendors in the same app. 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, and the other two need to be an account-level OAuth.
OAuth (Open Authorization) is a secure authorization framework that allows marketplace applications to access customer data via an auth mechanism with the right level of scoping. By adopting OAuth in their applications, developers can significantly enhance the security of user data. OAuth allows the applications to access specific resources or perform certain actions on behalf of users, all while keeping user credentials confidential.
How does the OAuth process work on the Freshworks developer platform?
Apps register with FreshID (Freshworks Identity Platform) by specifying the name, description and scopes they need based on the APIs the app needs to interact with. App developer uses these credentials to develop the app. Once the app is published in the marketplace, the admin can install it. During app installation, the app redirects to an authorization URL constructed by the app. Auth server (FreshID) takes over, presenting users with app details and permissions. Users can decide to authorize or deny the access request. If approved, users are redirected to the app’s URL with access and refresh tokens. The access token can be used for performing operations using APIs.
At what point should a developer opt to create an OAuth app instead of a non-OAuth app?
Developers should consider creating an OAuth app when they need to identify the app user who wants to access data. Authentication ensures that only authorized users have access to the data. Through OAuth authorization, the apps access the resources securely, without collecting or exposing sensitive credentials from the app user. Freshworks enables you to implement OAuth authorization flows in Freshworks apps and External apps. OAuth authentication is more secure than API key-based authentication and hence we recommend using OAuth.
How do I get started with building the Freshworks Oauth app on the Freshworks development platform?
You need to log in to your Freshworks developer account and go to your profile on the App Management Portal. Under your profile settings, you will see an option to create OAuth credentials. You can also view and edit the scopes of your existing Oauth credentials by visiting your profile settings, under the Oauth credentials section.
How to build a Freshworks app that uses OAuth to access Freshworks resources?
You need to log in to your developer account and go to your profile under settings. Click on the ‘Create OAuth Credentials’ button listed under the OAuth section. Setup the OAuth configuration file, test the flow and move your app to production. For the detailed step-by-step guide, refer to the link documentation.
How to build a Freshworks app that uses OAuth to access third-party resources?
Resource providers allow access to secure resources only after a successful OAuth handshake. Through the Freshworks developer platform’s request method interface, you can enable your app to place a request to access multiple OAuth-secured resources successfully. Find more info here.
How to build an external app that uses OAuth to access Freshworks resources?
You need to log in to your developer account and go to your profile under settings. Click on the ‘Create OAuth Credentials’ button listed under the OAuth section. Create the OAuth credentials for your app and test the flow from your third-party app. Move your app to production and publish it to the third-party Marketplace. The app developer has to call the FreshID authorization and token URL to get the required tokens to call the APIs. For the detailed step-by-step guide, refer to the link: documentation.
How to install and use an external OAuth app?
The external apps that are built using third-party SDKs and deployed in the third-party Marketplace, redirect the user to the Freshworks authorization server (FreshID) upon installation. The server then displays the scopes for the user to review. After the user hits ‘Agree’, the app can access the Freshservice data.
How to install and use an OAuth app from the Freshservice apps gallery?
Admins can install apps at an account level and enable your app to be available to all agents on the account. After installation, an OAuth app requires authorization before app users can start to use the app. For the step-by-step installation guide, refer to the documentation.
How to register your external app with Freshworks and generate OAuth credentials?
To implement OAuth flow in your external app, you need to create OAuth credentials for your app and include the requisite code in your app logic. You can test the OAuth flow in your third-party app and publish the app to the third-party Marketplace. For detailed steps, refer to this link.
As a developer, will I have the ability to change the authorization from API key to Oauth?
Yes, you change the authorization from API key to Oauth. Developers will have to make changes in the oauth_config.json file and publish the new version. Also, OAuth apps will require user consent to work when the OAuth version of the app is published.
What is the process that developers should follow for submitting Freshworks OAuth-enabled apps?
Any app created by a developer using Freshworks OAuth capability must be registered with FreshID to ensure its overall functioning. FreshID acts as the custodian of the scopes, providing this information to end-users during app installation and authorization. When Freshservice or other products publish or update API scopes these are also updated in FreshID and the same are shown when app developer edits an existing Oauth credential or when creating new Freshworks Oauth credentials.
Also, refer to FAQ #4 (How do I get started with building the Freshworks Oauth app on the Freshworks development platform?) and #5 (How to build a Freshworks app that uses OAuth to access Freshworks resources?) above for additional information.
Will the Marketplace validate that the app is registering with the right level for scopes?
Yes, during the app review process for public apps, the team at Freshworks will validate and review the checks manually. However, this process is not followed for custom apps.
What role does Freshworks play in ensuring that applications do not attempt to access resources beyond the scopes/privileges authorized during the authorization workflow?
The token provided by FreshID is restricted to the scopes declared for the credentials used in the app. If an API requiring a different scope is accessed by the app, then a 401 Unauthorized error is returned.
What happens when an app is uninstalled/reinstalled by a customer?
When you uninstall the app, both the consent and refresh tokens are revoked.
If the app is reinstalled, app users will have to navigate to the App Management Portal (AMP) to reauthorize the app. The reauthorization will place a request to the auth server and generate refresh tokens for data access.
- If your app has a front-end component and is installed at a single-user level, the app will display a Reauthorize button on receiving the 401 error. On-click the app should trigger the authorization code request and regenerate the access and refresh tokens.
- If the app is installed at an account level, the admin should navigate to the Freshworks developer portal and reauthorize the app from the settings page.
What happens to app authorization when new scopes are added, and is reauthorization required?
When new scopes are added, and the newer version of the app is installed, then the admin/agent is shown a consent screen with the additional scopes which are added to the credentials so that the admin/agent can provide the required consent for the app to work as expected. In case the admin/agent does not provide this consent then the app will fail to work as expected as it does not have the full permissions (scopes) to access all the required APIs (resources).
Are app developers encouraged to follow specific guidelines for promptly refreshing tokens and reauthorizing users?
The access token has a lifetime of 30 minutes. At a regular interval, your app should send a refresh-access-token call to the authorization server and regenerate the access token. When placing a refresh-access-token call, the app should pass the refresh token as a mandatory parameter. The refresh token has a lifetime of 365 days. After the refresh token expires, the access token will not be updated and all REST API calls will fail with a 401 - The access token has expired error.
In order to manage this, ensure to include the reauthorization logic in your app code and easy navigation guide to help users understand the error handling. More details here.
Can I create Oauth-enabled apps for Marketplace for all the Freshworks products?
Currently, OAuth authorization and authentication are available only fox`r Freshservice APIs. Visit this link https://api.freshservice.com/ to view the OAuth scope of the Freshservice APIs.
As an admin, I have installed an app that supports multi-oauth configurations. Does this setup allow the agents to access multiple resources?
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 three OAuth-secured resources. Either an agent or an account admin can install OAuth apps. If your app uses the multi-OAuth configuration, out of the three OAuth configurations, only one can be a configuration that facilitates agent installation.
What enablement resources are available for a developer to get started with building OAuth apps?
Link to developer documentation
Link to the sample app
Link to the tech blog
Link to the Tech Talk - 16th May 2024
Get Support!
In case you have questions, you can go to Topics tagged oauth and create a new topic with the ‘oauth’ tag for us to be able to answer your OAuth queries.