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.
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 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 email@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.
Before you configure, make note of some of the requirements/features that Freshworks SAML implementation supports.
- We require the SAML Options to be as SAML Responses to be signed and SAML Assertions to be unsigned. We will use the x.509 certificate to validate the signed payload. If you require the SAML Assertions to also be signed, please reach out to us via email and we can enable that option for you.
- We currently support SP initiated SAML SSO only.
- We currently support HTTP Post binding only.
- We require the Name Provider Format to be "Unspecified" with email as the value.
- We currently do NOT support Encrypted SAML Assertions.
Step-by-step configuration on how to configure SSO with SAML (Old UI)
Note: The new Security UI will be enabled by default on 30 Nov 2020. You can try our new features and redesigned UI in advance by clicking on the link present in the banner at the top of the Security section.
Log in using your Organization URL. Click on the ‘Security’ icon in the sidebar.
You can define a default security policy that will be applicable for all users in the organization including admins/agents. You can also create custom policies to configure SSO for contacts or to cater to agents in a specific portal.
Scroll down and toggle the Single Sign-On option. Choose SAML SSO as the login method.
Note: Org Admins are the only ones who can configure SSO.
Note: You can access the Organization Dashboard by opening the Freshworks Switcher and clicking on your organization link.
You will be presented with the ACS URL and Entity ID from our (Freshworks) side that you need to configure in the IdP. Please make a note of the same and use them to configure SAML in your IdP.
On the IdP side, once you configure Freshworks as an SP, you will be given values for the following entries that you need to configure in the Freshworks UI.
Entity ID (or Metadata ID)
SAML SSO URL (or Login URL)
Security Certificate (or x.509 certificate)
Copy the values into relevant fields and click on save to complete your SAML configuration.
After the SAML configuration details are successfully saved, click logout to verify the SAML configuration
Step-by-step configuration on how to configure SSO with SAML (New UI)
- Log in using your organization URL. Click on the ‘Security’ icon in the sidebar.
- Under Security > Agents/Admins > 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
In 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|
"givenname", "GivenName', "FirstName", "User.FirstName", "username","http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"
"surname", "Surname""LastName", "User.LastName","http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"
Click any of the relevant links to read more about the topic:
If you need further assistance, please feel free to write to firstname.lastname@example.org with your queries. We're more than happy to help.