The Single Sign-On capability in Freshservice lets the users arriving at your support portal login with their Twitter/Facebook/Google credentials. This saves them the time and effort involved in creating a separate account for your support portal. You can also set up an SSO mechanism to validate users trying to log into your portal for Freshservice using a 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 log into 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 hash on his login details (name, secret key, email and time stamp in that order) using the secret key Freshservice shares with you and generate a hash.
- You send Freshservice the encrypted value and the user’s login details this way:
['freshservice_domain_name']+"login/sso?name= "+current_user.username+ "&email="+current_user.email+ "×tamp="+utctime+ "&phone="+phone+ "&hash="+gen_hash_from_params_hash(utctime)
- Freshservice performs the same HMAC-MD5 hash on his login details using the secret key and checks if the resulting hash matches the hash you sent.
- If they match, Freshservice knows that the user has been validated by you already and grants access to your portal.
A quick guide on enabling remote authentication in your Freshservice portal:
Please note that you will need developer assistance to set up SSO.
- Log into your support portal as an 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 Freshservice. This key should be kept confidential as anyone getting hold of this key can use it to access your support portal.
- Set up your Remote login and Remote Logout pages and provide those URLs here.
- Remote Login URL: This is the URL of the page to which Freshservice will redirect the users requesting remote Login to your support portal. Here is how you can set it up using Ruby.
- Remote Logout URL: Freshservice redirects the users who log out from your support portal to this page.
Note: If you're using a Freshworks Organization account to access Freshservice, you can configure SSO from the Org Security Page.
Parameters in the Redirect URL
The redirect URL which you send Freshservice after user validation should consist of the following parameters with their corresponding properties.
The name of the user logging in, whether new or old, will be set to the user with the corresponding email address sent.
A valid email address needs to be passed. If no user exists with this email in Freshservice, an account is created for him on the go.
The UTC timestamp of when the user attempts to log in remotely in seconds since epoch. This value has to be within the past 5 minutes. Else the hash is rejected and the user is denied login.
A phone number can be passed as an optional parameter. This is however not used to generate the hash value.
HMAC-MD5 encryption of Name, Secret key, Email and Timestamp are done using the shared secret key.
Usually, once a user logs into 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 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 ticket view.
This can be done by appending &redirect_to=”the URL to user needs to access” to the authentication string you send back to Freshservice that contains the hash and login values.
The next step is to set up a remote login page that will perform authentication with Freshservice using the Shared Secret Key. This is done by passing an HMAC-MD5 hash back to Freshservice which contains the necessary Name, Secret key, Email Address, and Timestamp together. You can get the sample code for the login page using the following links:
Locked out of Freshservice?
In case you set up remote authentication and are locked out of Freshservice for some reason, you can use the following link to use a normal login:
If you're in the Estate plan, you can configure SSO with any other app like LinkedIn using the portal customization feature.
You can configure Freshservice to provide SAML Single Sign-On for your users. Here's how.