You can configure Freshdesk to provide SAML Single Sign On for your users. This way, they do not have to provide separate login credentials for Freshdesk. 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 Freshdesk.


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 Freshdesk 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 Freshdesk 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 Freshdesk:


SAML Login URL


The user gets redirected to this URL when they request SAML SSO in Freshdesk.
SAML Logout URL


The user gets redirected to this URL when they log out. This is optional. If this information is not provided by the Identity provider, the user gets redirected to the portal.
SAML certificate


SHA-256 certificate provided by the Identity provider that Freshdesk 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>.freshdesk.com/login/saml

When the user requests for SAML SSO by arriving at the Freshdesk Portal, the XML Assertion will be sent to this URL.

If you add Freshdesk as an app in your Identity provider, the user will get redirected to this URL when they click on the Freshdesk button.


How does SAML SSO in Freshdesk work?

  1. User wants to login to Freshdesk using SAML SSO.
  2. Freshdesk redirects the user to the login URL the Identity Provider, for example, OneLogin, provides. 
  3. User enters their credentials and OneLogin validates the user. 
  4. OneLogin redirects the user to Freshdesk’s Consumer Assertion URL and passes an SAML Assertion telling Freshdesk that the user is valid.
  5. User Attributes like Email address, First name and Last name of the user will be sent along with the Assertion by OneLogin to Freshdesk. 
  6. Freshdesk verifies OneLogin’s SHA-256 certificate and grants the user access. 





Enabling SAML Single Sign on in Freshdesk


Here is how you can configure SAML SSO in Freshdesk:

  1. Log into your Freshdesk as an administrator.
  2. Under Admin tab, go to 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 SHA-256 fingerprint of the SAML certificate from the Identity Provider and paste them in these text boxes.
  5. Click Save to start using SAML SSO right away.



User Attributes recognized by Freshdesk


Freshdesk requires the following attributes from the Identity Provider to allow the user to login using SAML SSO.


AttributeFormatNecessityDescription
First Name
givennameOptionalThe first name of the user will be assigned to the corresponding email address.
Last NamesurnameOptional

The last name of the user will be assigned to the corresponding email address.

PhonephoneOptional

Phone number of the user will be assigned to the corresponding email address.

CompanycompanyOptional Name of the Company of the user will be assigned to the corresponding email address.
Custom fieldcustom_field_<field_name>OptionalIf there is a custom user field (contact field) configured as 'Office Location', then the SAML assertion needs to be sent the attribute as 'custom_field_office_location' to update the user information.


The address of the user is the only required field that Freshdesk needs. Here is a sample code of how the email address is passed:

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

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


Login Errors


A user could be denied access into Freshdesk due to the following reasons:


Error MessageDescription
No fingerprint or certificate on settings


SSO has been disabled or the certificate fingerprint is not configured in Freshdesk.

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 Freshdesk. 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.freshdesk.com/login/normal with the error message displayed. From there, the user can login normally.


You can also set up an SSO mechanism to validate users trying to log into your portal for Freshdesk using locally hosted script. Find out how.


Note: Freshdesk SAML SSO now supports SHA256 and all support for SHA1 certificates will be stopped by June 1. Customers using SHA1 can transition to SHA256 by following the procedure here.


You can configure Freshdesk to provide SAML Single Sign On for your users. This way, they do not have to provide separate login credentials for Freshdesk. 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 Freshdesk.


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 Freshdesk 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 Freshdesk 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 Freshdesk:


SAML Login URL


The user gets redirected to this URL when they request SAML SSO in Freshdesk.
SAML Logout URL


The user gets redirected to this URL when they log out. This is optional. If this information is not provided by the Identity provider, the user gets redirected to the portal.
SAML certificate


SHA-256 certificate provided by the Identity provider that Freshdesk 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>.freshdesk.com/login/saml

When the user requests for SAML SSO by arriving at the Freshdesk Portal, the XML Assertion will be sent to this URL.

If you add Freshdesk as an app in your Identity provider, the user will get redirected to this URL when they click on the Freshdesk button.


How does SAML SSO in Freshdesk work?

  1. User wants to login to Freshdesk using SAML SSO.
  2. Freshdesk redirects the user to the login URL the Identity Provider, for example, OneLogin, provides. 
  3. User enters their credentials and OneLogin validates the user. 
  4. OneLogin redirects the user to Freshdesk’s Consumer Assertion URL and passes an SAML Assertion telling Freshdesk that the user is valid.
  5. User Attributes like Email address, First name and Last name of the user will be sent along with the Assertion by OneLogin to Freshdesk. 
  6. Freshdesk verifies OneLogin’s SHA-256 certificate and grants the user access. 




Enabling SAML Single Sign on in Freshdesk


Here is how you can configure SAML SSO in Freshdesk.


  1. Log into your Freshdesk as an administrator.
  2. Under Admin tab, go to 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 SHA-256 fingerprint of the SAML certificate from the Identity Provider and paste them in these text boxes.
  5. Click Save to start using SAML SSO right away.



User Attributes recognized by Freshdesk


Freshdesk requires the following attributes from the Identity Provider to allow the user to login using SAML SSO.


AttributeFormatNecessityDescription
First Name
givennameOptionalThe first name of the user will be assigned to the corresponding email address.
Last NamesurnameOptional

The last name of the user will be assigned to the corresponding email address.

PhonephoneOptional

Phone number of the user will be assigned to the corresponding email address.

CompanycompanyOptional Name of the Company of the user will be assigned to the corresponding email address.
Custom fieldcustom_field_<field_name>OptionalIf there is a custom user field (contact field) configured as 'Office Location', then the SAML assertion needs to be sent the attribute as 'custom_field_office_location' to update the user information.


The address of the user is the only required field that Freshdesk needs. Here is a sample code of how the email address is passed:

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

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


Login Errors


A user could be denied access into Freshdesk due to the following reasons:


Error MessageDescription
No fingerprint or certificate on settings 


SSO has been disabled or the certificate fingerprint is not configured in Freshdesk.

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 Freshdesk. 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.freshdesk.com/login/normal with the error message displayed. From there, the user can login normally.


You can also set up an SSO mechanism to validate users trying to log into your portal for Freshdesk using locally hosted script. Find out how.


Note: Freshdesk SAML SSO now supports SHA256 and all support for SHA1 certificates will be stopped by June 1, 2017. Customers using SHA1 can transition to SHA256 by following the procedure here.