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 for 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.|
|SAML certificate|| 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
Here is how you can configure SAML SSO 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 the in these text boxes.
- Click Save to start using SAML SSO right away.
User Attributes recognized by Freshservice
Freshservice recognizes the following attributes from the Identity Provider
|Email Address||NameID||Yes||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||firstName||No||First name of the user.|
|Last Name||lastName||No||Last Name of the user.|
|Job Title||jobTitle||No||Job Title of the user.|
|Phone||phone||No||Phone number of the user.|
|Mobile||mobile||No||Mobile number of the user.|
|Department||department||No||Department of the user. If the department does not exist in Freshservice, a new department is created. New department values are always overwritten.|
|Reporting Manager||reportingManager||No||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||address||No||Address of the user.|
|Time Zone||timeZone||No||Time zone of the user. The value should follow the format specified in this article.|
|Language||language||No||Language of the user. The value should follow the format specified in this article.|
|Location||location||No||The location of the user. The location value should exist in Freshservice.|
|Custom Fields||custom_field_<field_name>||No||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.|
|Blank response ||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.