The Single Sign On (SSO) allows you to let users sign into your support portal using either their Gmail, Facebook or Twitter credentials, instead of manually requiring them to sign up for an account. You can also set up an SSO mechanism to validate users trying to log into your portal for Freshdesk using locally hosted script. These could be the users who already have an account in your web application or whose information you have stored in your internal application like ActiveDirectory.


Here is how SSO/ Remote Authentication works:

  • A user (agent/customer) wants to remotely login to your support portal.
  • You redirect the user to a remote login page you set up.
  • The user enters his login credentials and you validate him. 
  • You perform an HMAC-MD5 encryption on his login details (name, email and time stamp) using the secret key Freshdesk shares with you and generate a hash.
  • You send Freshdesk the encrypted value and the user’s login details this way:


['freshdesk_domain_name']+"login/sso?name=

"+current_user.username+"&email="+current_user.email+

"×tamp="+utctime+

"&phone="+phone+

"&company="+company+

“&hash="+gen_hash_from_params_hash(utctime)


  •  Freshdesk performs the same HMAC-MD5 encryption on his login details using the secret key and checks if the resulting hash matches the hash you sent.
  • If they match, Freshdesk knows that the user has been validated by you already and grants access to your portal.




Quick guide on enabling remote authentication in your Freshdesk portal:

Please note that you will need developer assistance to set up SSO.

  • Login to you support portal as administrator. Make sure that you are a full time agent in your helpdesk.
  • Go to the Admin tab and click on the Security icon.
  • Enable Single Sign On by clicking on the toggle.
  • You will be given a Secret key that you will share with Freshdesk. This key should be kept confidential as anyone getting hold on this key can use it to access your support portal.
  • Set up your Remote login and Remote Log out pages and provide those URLs here.
  • Remote Login URL: This is the URL of the page to which Freshdesk will redirect the users requesting remote Login to your support portal. Here is how you can set it up using Ruby.
  • Remote Logout URL: Freshdesk redirects the users who log out from your support portal to this page.


The redirect URL which you send Freshdesk after user validation should consist of the following parameters with their corresponding properties.


Parameters

Properties

name

The name of the user logging in, whether new or old, will be set to the user with the corresponding email address sent.

email

A valid email address needs to be passed. If no user exists with this email in Freshdesk, an account is created for him on the go.

timestamp

The UTC timestamp of when the user attempts to log in remotely in seconds since epoch. This value has to be within the past 30 minutes. Else the hash is rejected and the user is denied login.

phone

A phone number can be passed as an optional parameter. This is however not used to generate the hash value.

company

The name of the company can be passed as an optional parameter. This however is not used to generate the hash value.

hash value

An HMAC-MD5 encryption of Name, Email and Timestamp done using the shared secret key.

redirect_to (optional)

Usually, once a user logs in to your support portal, he is taken to the home page. You can customize this according to the roles of your users. For example, once you verify the user and find out the he is an Admin, he could be redirected to support.yourcompany.com/Admin/home. If he is your customer, he could be taken to his recent tickets view.
This can be done by appending &redirect_to=”the URL to user needs to access” to the authentication string you send back to Freshdesk that contains the hash and login values.


Creating the Remote Login Page


The next step is to setup a remote login page that will perform authentication with Freshdesk using the Shared Secret Key. This is done by passing an HMAC-MD5 hash back to Freshdesk which contains the necessary Email Address, Name and Time stamp together.

You can find sample codes at the following links:

Ruby - https://github.com/kirandarisi/freshdesk_sso

Java - https://github.com/kirandarisi/freshdesk_sso_java/blob/master/FDHmac.java

ASP.NET C# - https://gist.github.com/barryokane/2718191

ASP.NET MVC - https://gist.github.com/kellyelton/8776309


Locked out of Freshdesk?

In case you setup remote authentication and are locked out of Freshdesk for some reason, you can use the following link to use a normal login:

http://yourcompany.freshdesk.com/login/normal


If you're in the Estate plan, you can configure SSO with any other app like LinkedIn using the portal customization feature. If you have already implemented SSO in Freshdesk before December 2, 2013, please go through the following and make the necessary changes.

  • User information must now be encrypted using HMAC-MD5. This improvement over the MD-5 encryption used before reduces security vulnerability of the hashed credentials.
  • The time stamp of when the user logs in must be included in the encrypted data. So an HMAC-MD5 hash of Name + Email + Time Stamp created using Secret key is sent for validation. This hash will be valid for 30 minutes. This prevents malicious attempts to reuse your existing hash to login to your account.


Single Sign On using SAML

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 he requests SAML SSO in Freshdesk.

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 - SHA-1 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 encrypted XML Assertion will be sent to this URL.

If you add Freshdesk as an app in your Identity provider, the user gets redirected to this URL when he clicks on Freshdesk button.


How does SAML SSO in Freshdesk work?

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



Quick guide to enabling SAML Single Sign on in Freshdesk

  • Log into your Freshdesk as an administrator.
  • Under Admin tab, go to 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 SHA-1 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 Freshdesk

Freshdesk requires (and accepts only) the following attributes from the Identity Provider to allow the user to login using SAML SSO.


Attribute

Format

Necessity

Description

First Name

givenname

Optional

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

Last Name

surname

Optional

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

Phone

phone

Optional

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

Company

company

Optional

Name of the Company of the user will be assigned to the corresponding email address.


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:

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.