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:

A user

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?

  1. User wants to login to Freshservice using SAML SSO.
  2. Freshservice redirects user to the login URL of the Identity Provider, for example, OneLogin. 
  3. User enters their credentials and the identity provider validates the user. 
  4. Identity Provider redirects the user to Freshservice’s Consumer Assertion URL and passes an encrypted SAML Assertion telling Freshservice that the user is valid.
  5. 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. 
  6. 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.


  1. Log into your Freshservice as an administrator.
  2. Go to Admin > Helpdesk Security. 
  3. Click on the SSO toggle to enable it.
  4. 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. 
  5. Click Save to start using SAML SSO right away. 

 


User Attributes recognized by Freshservice

Freshservice recognizes the following attributes from the Identity Provider

 

Attribute
Attribute Name
Required?
Description
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.


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:

  <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">example@test.freshservice.com</saml:NameID>

If this code is sent by the identity provider, a user with the user name as "example" is created in Freshservice.


Login Errors

A user will be denied from logging into Freshservice due to the following reasons:

 

Error Message
Description
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.