This article describes the process to set up JWT SSO in Freshservice for authentication using the Active Directory. A script will need to be hosted in the IIS server and will have access to the Active Directory to authenticate your users in Freshservice.


Note: This option is currently available only if you've signed up with the Freshworks Suite of Products from February 2020. We'll be incrementally rolling this option out for customers who signed up before that.


Step 1: To install Internet Information Services (IIS)

Internet Information Services (IIS Manager) should be configured on Windows Server to host the Classic ASP script file which will access user information from the Active directory. You can follow the steps given in this article to install IIS 8 on Windows Server 2012. Please choose the following options while installing the IIS role on the Server.

  • Web Server (IIS)

    • Security

      • Windows Authentication

    • Application Development

      • ASP

  • Management Tools

    • IIS Management Console

 

You need ASP to host the Classic ASP script and Windows Authentication to authenticate users in the Active Directory for Freshservice. So if you’ve already installed IIS, make sure that these features are installed.


Step 2: To edit the Classic ASP script file

 

  1. Download the ADScriptJWT.asp, Constants.asp, and jwt.all.asp files attached below.

  2. Open the Constants.asp file and assign the following values to the variables.

    • sLdapReaderUsername = "domain\username" (Username of the AD account which has Read-Only privilege to all the users in the AD)

    • sLdapReaderPassword = "password" (Password of that user account)

    • sRSAPrivateKey
      To create the signature part you have to take the encoded header, the encoded payload, RSA private key, and sign that. You can generate the RSA Key using the following script:

      #generate RSA key
      ssh-keygen -t rsa -b 1024 -m PEM -f jwtRS256.key
      # use empty passphrase 
      openssl rsa -in jwtRS256.key -pubout -outform PEM -out jwtRS256.key.pub

      Or use the online generators       Link1, Link2 

    • sReturnURL: The Freshservice Redirect URL where the user will be redirected once the authentication is successful < https://domain.freshworks.com/sp/OIDC/13415184120 >

  3. Save the Constants.asp file.


For Example:

 

sLdapReaderUsername = "FRESHSERVICE\admin"

sLdapReaderPassword = "xxxxxxxxx"

sRSAPrivateKey = "-----BEGIN RSA PRIVATE KEY-----<RSA Private Key as single line string>----END RSA PRIVATE KEY-----"

sReturnURL = "https://domain.freshworks.com/sp/OIDC/134151841209466902/implicit"


Note: When you run commands on Linux/Mac, two files will be generated which contains the RSA public and private keys jwtRS256.key and jwtRS256.key.pub
Make sure you copy the multiline content from the .key files, change to a single line within double quotes before pasting along with the sRSAPrivateKey in the Constants.asp file.



Step 3: To configure the ASP script in the IIS

 

  1. Create a new website in IIS, go through the Create a new Web site section in this article (you can create a new site or use the existing site available in IIS).

  2. Click on the site and double click ASP on the right pane. 

  3. Set Enable Parent Paths to true.

  4. Click on the site again and double click Authentication. 

  5. Right-click Windows Authentication and select Enable. 
    Note: Disable all the other authentication types. IIS will use the integrated Windows authentication. To make it possible, IIS Server should be installed on the Active Directory Domain which contains the users.

  6. Right-click on the site, select Explore. 

  7. Paste the 3 files - ADScriptJWT.asp, Constants.asp, and jwt.all.asp  which are configured already.

  8. Navigate to the ADScriptJWT.asp path. 

  9. You will be authenticated and logged into Freshservice.


Prerequisites/ Points to Remember: 

  • The Classic ASP script uses your mail attribute as an email holder. It will fetch the email address from your mail attribute. So it is mandatory to have the mail attribute populated in User Attributes to successfully log into Freshservice. So if you get the error “Couldn't log in to Freshservice. Please contact your administrator”, check whether the email address is configured for you in the Active directory.

  • By default, the runat="server" option for Javascript tags will be enabled when you’re creating a site in IIS. 

  • Try to access the Script from http://dc-svr01/test.asp and see if the script is executed or not. Ensure that the IIS calls this script with Integrated Authentication and NOT via Anonymous Authentication. 

  • Change the authentication to only use NTLM and not negotiate with Kerberos.


 

Step 4: To set up SSO for Freshservice

  1. Sign in to your Freshservice account. 

  2. Click on the Admin Settings icon. 

  3. Click Service Desk Security under Account Settings. If your account has more than one workspace, navigate to Admin > Global Settings > Account Settings > Service Desk Security.

  4. Click on the link - Manage Service Desk Security from Freshworks 360 Security. This opens the Org Security page in a new tab. 

  5. Navigate to the Single sign-on card under Login Methods. 

  6. Toggle the switch. By default SAML SSO will be selected. 

  7. Click the dropdown and select JWT SSO. A Redirect URL will be automatically generated in the Redirect URL field box.
    Note: Copy the Redirect URL generated and paste it along with the     sReturnURL while assigning values in the Constants.asp file. 


  8. Copy the contents of jwtRS256.key and paste it in the RSA Public key field box. 
    Note: Make sure you omit the header and footer contents of the jwtRS256.key before pasting it in the field.

  9. Enter the Authorization URL 

    URL Format:

    https://<AD Server Domain or IP>:<port>/ADScriptJWT.asp
     

  10. (Optional) You can also enter the Logout URL to which the users will be sent when they log out. 

  11. Click Save to finalize your changes.

JWT-SSO-ADScript-v2 (1).zip JWT-SSO-ADScript-v2 (1).zip

(30.8 KB)