Single Sign On is the mechanism using which your agents can access Freshworks portals using the same credentials they are using to login to your internal systems. In this mechanism, the users credentials are verified in your systems and the user’s identity information is securely communicated via SAML XML Response with Freshworks. Freshworks then verifies the XML response and lets the user view the portals that he has access to without additional password checks.
To learn more about SSO and SSO for freshworks, refer to these articles below.
SAML - Overview
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.
Before we explain how SAML works and how it can be configured in your organization security panel, let us first describe some of the components involved.
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 firstname.lastname@example.org
SAML Request: Also known as the authentication request, Service Provider is responsible for generating this request to the Identity Provider.
SAML Response: Identity Provider is responsible for generating the SAML response in XML format which contains the details of the user whose authentication is validated by the Identity Provider. SAML Response is constructed by the Identity Provider based on the mutually pre-configured information for that Service Provider. Once Service Provider receives the SAML response, it is the Service Provider's responsibility to validate that the response is generated by the appropriate Identity Provider and then parse the user's identity information embedded in the SAML response.
Certificate: As mentioned above, Service Providers 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 Service Provider 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 Service Provider 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 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.
Steps to configure SAML
- Navigate to your Organization Dashboard and click on the Security section in the side bar.
Please note that this option is only available to the Org Admins
Note: You can access the Organization Dashboard by opening the Freshworks Switcher and clicking on your organization link.
- In the available choices, turn on Single Sign-On option and choose SAML as the login method.
- You will be presented with ACS URL and Entity ID from SP 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
- In 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)
- Click Save to complete your SAML configuration.
- After the SAML configuration details are successfully saved, click logout to verify the 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 logged into Freshworks - your configuration is successfully complete.
- If you are not able to login, please make sure you configured the SAML fields correctly
- Please do make sure that you followed the requirements section of the SAML configuration above.
- We expect the SAML claims to be in the following format to update the profile information of a user at the time of SAML assertion
Profile Attribute Expected SAML Claim format First Name
"givenname", "FirstName", "User.FirstName", "username","http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"
"surname", "LastName", "User.LastName","http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"