OAuth 2.0 is an authorization framework for third-party applications. On behalf of a resource owner, third-party applications like Freshworks use OAuth 2.0 to get limited access to an HTTP service. The framework also enables an approval interaction of the resource owner with the HTTP service. In addition, OAuth 2.0 supports direct access to the HTTP services by the third-party application.


To learn more about SSO, refer to these articles below.

How OAuth 2.0 works

  1. If you, the user, haven't already signed in, you will be redirected from the application to your authorization URL, requesting an authorization code. 

  2. Freshworks receives the requested authorization code from the authorization server.

  3. Freshworks makes a request to your access token URL, exchanging the code obtained for an access token.

  4. Your authorization server will return an access token to Freshworks.

  5.  Freshworks then makes a request to your UserInfo URL with the access token obtained.

  6. Your server will then return the user’s information in JSON format


Step-by-step process on how to configure SSO with OAuth 2.0

  1. Log in using your organization URL. Click on the 'Security' icon in the sidebar. 
  2. Under Security> Agents & Employees > Default Login Methods, you can enable SSO to simplify your users' login experience. Default login methods are applicable for all users in the organization, including admins/agents. If you want to create specific policies for a particular account or portal, configure it under Custom Policies. For contacts, configure any security policies under Security > Contacts. 
  3. Choose OAuth 2.0 as your login protocol and the IdP of your choice.
    Note: Organization Admins are the only ones who can configure SSO.
    Note: You can access the Neo Admin Center by opening the Freshworks Switcher and clicking on your organization domain link.
  4. Use the Redirect URL provided by Freshworks in your Identity provider configuration.
  5. You will be presented with the following fields that you need to fill with the information you get from the IdP side:

    • Client Id

    • Client secret

    • Authorization URL (to redirect to the login page of IdP, if not already logged in)

    • Access token URL (to get the user access token)

    • Logout URL (optional - user will be redirected to this page on logout)

    • User info URL (to get the user information based on the access token obtained by invoking the access token URL)



Params to be shared

Name

Description

Sample Value

Minimum requirement

Client Id

Client Id as generated by IdP

xxxx

Required

Client Secret

Client secret as generated by IdP

xxxx

Required

Logout Redirect URL

URL where the user should be redirected post logout

https://www.freshworks.com

Optional

Login display title

Text that will be displayed on the login button

Login with Awesome Company

Required

Logo URL

Logo to be displayed on the login page. Size should be 36x36 px. Only PNG & SVG is accepted


Optional

Authentication Method

Authentication method to be used while making a call to the token endpoint

POST | BASIC 

Required

Default: BASIC

Authorization Endpoint

URI where the user should be sent to for authorization


Required

Token Endpoint

Endpoint URI that is used to exchange token


Required

User Info Endpoint

Endpoint URI that will be used to fetch user info


Required

Scopes

Scopes that should be used during authorization call


email 

Required

Id Path

Path to Json that holds Id of the user

.id

Required

Email Path

Path to Json that holds the email address of the user

.email

Required

First Name Path

Path to Json holds the first name of the user

.first_name

Optional

Middle Name Path

Path to JSON holds the middle name of the user

.middle_name

Optional

Last Name Path

Path to JSON that holds the last name of the user

.last_name

Optional

Phone Path

Path to JSON that holds the phone number of the user

.phone_number

Optional

Mobile Path

Path to JSON that holds the mobile number of the user

.mobile

Optional

Locale Path

Path to JSON that holds the Locale of the user

.locale

Optional

Job Title Path

Path to JSON that holds the job title of the user

.job_title

Optional

Company Path

Path to JSON that holds the company name of the user

.company

Optional


Note: 
1. Once all the configurations are correct on both the sides, the user info endpoint URL should mandatorily return sub and email claims. Without these claims, it is not possible for to authenticate the user.
2. Call from Freshworks to the token endpoint has a timeout of 10 seconds.


If you need further assistance, please feel free to write to [email protected] with your queries. We're more than happy to help.