Last updated: 2023-10-03

Source: https://support.freshservice.com/support/solutions/articles/50000001173-configure-active-directory-sso-with-json-web-token

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

    01. Sign in to your Freshservice account.

    02. Click on the Admin Settings icon.

    03. 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.

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

    05. Navigate to the _Single sign-on_ card under _Login Methods_.

    06. Toggle the switch. By default _SAML SSO_ will be selected.

    07. 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.

    08. 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 thejwtRS256.key before pasting it in the field.

    09. Enter the _Authorization UR_ L

    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.