You can use Single sign-on (SSO) to log into your Freshworks account via existing SAML-enabled ID providers, such as Active Directory, OneLogin, Okta, etc.
To learn more about SSO, refer to these articles below.
- SSO Overview
- Implement Single Sign-On for Freshworks
- How is the authentication data securely exchanged between IdP and SP
- Terms and definitions to understand SSO better
- Agent SSO and Contact SSO for an Organization
How SAML works?
SAML is a commonly used XML-based authentication and authorization framework to securely exchange information between a Service Provider (example - Freshworks) and an Identity Provider (example - ADFS). As part of the configuration, Service Provider trusts Identity Provider to verify the user's authentication, and the Identity Provider exchanges this user's identity via a digitally signed authentication assertion with the Service Provider to enable seamless authentication of a user.
In other words, it is a standard protocol that gives identity providers (IdP) a secure way to let a service provider (SP) like Freshworks know whether you are you. When Freshworks sends requests to an IdP to authenticate a user, the browser is redirected to Freshworks with a SAML assertion. After verifying the SAML assertion, users are granted access to the application.
Here is an overview of some of the components you’ll encounter:
- Service Provider (SP): This is the entity providing the service or a web application. In our context, it would be Freshworks.
- Identity Provider (IdP): This is the entity providing the user's context and also the one that is capable of authenticating a user.
- Assertions: SAML allows for one party to assert security information in the form of statements about a subject. For instance, a SAML assertion could state that the subject is named “John Doe”, has an email address of john.doe@example.com
- SAML Request: Also known as the authentication request. SP is responsible for generating this request to the IdP.
- SAML Response: IdP is responsible for generating the SAML response in XML format which contains the details of the user whose authentication is validated by the IdP. SAML Response is constructed by the IdP based on the mutually pre-configured information for that SP. Once an SP receives the SAML response, it is the SP's responsibility to validate that the response is generated by the appropriate IdP and then parse the user's identity information embedded in the SAML response.
- Certificate: As mentioned above, SPs need to validate the SAML response generated by the IdP, and to be able to validate this, SP needs the public portion of the certificate that is used to sign the SAML response.
- ACS URL: This is the public endpoint from the SP side that IdP will post the SAML Response to.
- SAML SSO URL or Login URL: This is the public endpoint from the IdP side that the SP will send the SAML Request to.
SAML - Freshworks Configuration
Now that you are aware of some of the key components that are part of the SAML standard, let us explain how you can configure SAML settings for your organization.
Step-by-step configuration on how to configure SSO with SAML
- Log in using your organization URL. Click on the ‘Security’ icon in the sidebar.
- Under Security > Agents & Employees > Default Login Methods, you can enable SSO to simplify your users’ login experience.
- Choose SAML as your login protocol and the IdP of your choice. For some of the popular identity providers like Okta, ADFS, Azure AD, and OneLogin, we have guides within the UI, helping you map relevant information in the IdP and from the IdP. For more details, you can always refer to the support articles listed below.
Note: Organization Admins are the only ones who can configure SSO. 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 custom policies under Security > Contacts.
Note: You can access the Admin Center by opening the Freshworks Switcher and clicking on your organization domain link.
Verify SAML Configuration
On the login page, you will notice a new option to login called "Sign in with SSO"
Click this button to verify whether the SAML configuration is successful or not. If you are able to successfully complete the authentication and log into Freshworks - your configuration is successfully complete.
If you are not able to log in, please make sure you configured the SAML fields correctly
We expect the SAML claims (information of a user at the time of SAML assertion) to be in the following format to update the profile:
| Profile Attribute | Expected SAML Claim format |
|---|---|
| First Name | "givenname", "GivenName', "FirstName", "User.FirstName", "username","http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname" |
| Last Name | "surname", "Surname""LastName", "User.LastName","http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname" |
| Work Number | phone |
| Mobile Number | mobile |
| Company Name | "company", "organization" |
| Job title | "title", "job_title" |
| Language/Locale | "preferredLanguage", "user.preferredLanguage", "User.preferredLanguage" |
| Timezone | "timezone", "user.timezone", "User.timezone" |
Click any of the relevant links to read more about the topic:
- Configure SAML 2.0 for Freshworks using Okta
- Configure SAML 2.0 for Freshworks using Azure AD
- Configure SAML 2.0 for Freshworks using ADFS
- Configure SAML 2.0 for Freshworks using OneLogin
If you need further assistance, please feel free to write to support@freshworks.com with your queries. We're more than happy to help.