You can configure Freshservice to provide SAML Single Sign-On for your users. This way, they do not have to provide separate login credentials for Freshservice. The authentication of the user is done by any SAML provider you configure on your side and the user attributes like Email address are sent back to Freshservice.
An overview of SAML
Security Assertion Markup Language (SAML) is a mechanism used for communicating identities between two web applications. It enables web-based Single-Sign-On and hence eliminates the need for maintaining various credentials for various applications and reduces identity theft.
SAML usually involves three things:
The person requesting the service.
A service provider
The application providing the service or protecting the resource.
An identity provider
The service/repository that manages the user information.
A user requests a SAML SSO to access a resource that is protected by a service provider. The service provider requests the identity provider to authenticate the user. The identity provider checks the existence of the user and sends back an assertion to the service provider that may or may not include the user information. The communication between the identity and service providers happens in the SAML data format.
You can configure Freshservice to act as a service provider in this mechanism. You can use your own SAML server to act as an Identity provider or you could use some third party applications like OneLogin, Okta etc.
Fields required by Freshservice for SAML integration
You can use third party services like OneLogin, Okta or any identity provider to verify your users' identity. You need to get the following information from your identity provider in order to configure SAML SSO in Freshservice:
SAML Login URL
The user gets redirected to this URL when he requests SAML SSO in Freshservice.
SAML Logout URL
The user gets redirected to this URL when he logs out. This is optional. If this information is not provided by the Identity provider, the user gets redirected to the portal.
SHA256 certificate provided by the Identity provider that Freshservice uses to validate the authenticity of the Identity provider.
Fields required by your identity provider
The identity provider requires a Consumer Assertion URL to which it redirects the user after the authentication.
You need to provide the URL in this format: https://<yourdomain>.freshservice.com/login/saml
When the user requests for SAML SSO by arriving at the Freshservice Portal, the encrypted XML Assertion will be sent to this URL.
If you add freshservice as an app in your Identity provider, the user gets redirected to this URL when he clicks on Freshservice button.
How does SAML SSO in Freshservice work?
- User wants to login to Freshservice using SAML SSO.
- Freshservice redirects user to the login URL of the Identity Provider, for example, OneLogin.
- User enters their credentials and the identity provider validates the user.
- Identity Provider redirects the user to Freshservice’s Consumer Assertion URL and passes an encrypted SAML Assertion telling Freshservice that the user is valid.
- User Attributes such as Email address, First name and Last name of the user will be sent along with the Assertion by identity provider to Freshservice.
- Freshservice verifies the identity provider's SHA256 certificate and grants the user access.
Enabling SAML Single Sign-On in Freshservice
- Log into your Freshservice as an administrator.
- Go to Admin > Helpdesk Security.
- Click on the SSO toggle to enable it.
- Click the SAML SSO radio button. You will have to copy the Login URL, Logout URL (optional) and the SHA256 certificate from the Identity Provider and paste them in these text boxes.
- Click Save to start using SAML SSO right away.
Note: If you're using a Freshworks Organization account to access Freshservice, you can configure SAML 2.0 SSO from the Org Security Page.
To access Org security settings:
Sign in to your Freshservice account.
Click on the Admin Settings icon.
Click Helpdesk Security under General Settings.
Click on the link - Manage Helpdesk Security from Freshworks 360 Security. This opens the Org Security page in a new tab.
User Attributes recognized by Freshservice
Freshservice recognizes the following attributes from the Identity Provider
Email address of the user will act as the user name in Freshservice. When a new user logs in, Freshservice will create an account using this Email address automatically.
First name of the user.
Last Name of the user.
Job Title of the user.
Phone number of the user.
Mobile number of the user.
Department of the user. If the department does not exist in Freshservice, a new department is created. New department values are always overwritten.
The Email address of the manager to whom the user reports to. If the email of the reporting manager does not exist in Freshservice, a new requestor will be created.
Address of the user.
Time zone of the user. The value should follow the format specified in this article.
Language of the user. The value should follow the format specified in this article.
The location of the user. The location value should exist in Freshservice.
Custom fields defined for users. The <field_name> placeholder refers to the name attribute that is returned by the List All Requester Fields API operation (for all the fields in which default = false.
The address of the user is the only required field that freshservice needs. Here is an sample code of how the email address is passed:
If this code is sent by the identity provider, a user with the user name as "example" is created in Freshservice.
A user will be denied from logging into Freshservice due to the following reasons:
No fingerprint or certificate on settings
SSO has been disabled or the certificate fingerprint is not configured in Freshservice.
Invalid / Empty SAML response received
Current time is earlier than response / Current time is much later than response
There is a time difference between the request and validation response to Freshservice. Time on the SAML provider needs to be checked for difference in clock.
Login was unsuccessful
You are not authorized to access the application. Or the App is not assigned to you by the identity provider
During these cases, the user will get redirected to http://yourcompany.freshservice.com/login/normal with the error message displayed. From there, the user can login normally.