You can use Single sign-on (SSO) to log into your Freshworks account via JWT.


To learn more about SSO, refer to these articles below.


What is JSON Web Token (JWT)


A JSON object that is defined in RFC 7519 as a safe way to represent a set of information between two parties. The token is composed of a header, a payload, and a signature. It represents your users' credentials wrapped in a single query string.


Note: 

The JWT SSO implementation is done strictly in compliance to Implicit OAuth flow as described in the RFC6749 here.

JWT - Overview

In its compact form, JSON Web Tokens consist of three parts separated by dots (.), which are:

  • Header
  • Payload
  • Signature

Therefore, a JWT typically looks like xxxxx.yyyyy.zzzzz. Let's break down the different parts of the token in detail.


Header

The header typically consists of two parts: the type of the token, which is JWT, and the signing algorithm being used, in case of Freshworks, it is RS256. 

{ "alg": "RS256", "typ": "JWT"}

Then, this JSON is Base64Url encoded to form the first part of the JWT.


Payload

The payload contains the data related to the identity along with secure parameters exchanged in JSON format. For example,

{
    "sub": "1234567890",
    "email": "messi@awesomecompany.com",
    "nonce": "123422"
}

The payload is then Base64Url encoded to form the second part of the JSON Web Token.

Please note that this information, though protected against tampering, is readable by anyone. Do not put secret information in the payload or header elements of a JWT unless it is encrypted.


Signature

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

Do not, under any circumstances, share the private key with anyone else outside of your organization and keep it as secure as possible. You will use the private key only to sign the JWT and keeping it secure guarantees that no one other than you (not even Freshworks) can sign the JWT token.

The signature is used to ensure that the message wasn't changed along the way, and, in the case of tokens signed with a private key, it can also verify that the sender of the JWT is who it says it is.

Putting it all together, a sample JWT token looks like this

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.TCYt5XsITJX1CxPCT8yAV-TVkIEq_PbChOMqsLfRoPsnsgw5WEuts01mq-pQy7UJiN5mgRxD-WUcX16dUEMGlv50aqzpqh4Qktb3rk-BuQy72IFLOqV0G_zS245-kronKb78cPN25DGlcTwLtjPAYuNzVBAh4vGHSrQyHUdBBPM

The public key portion of the RSA Key has to be configured in the Freshworks Security UI so that Freshworks can use that to verify the JWT token.
We support only RS256 as the signing algorithm as it is more secure.

What params can be passed in the payload of JWT Token?


Param NameValue Type & ExampleRequired / OptionalDescription
subString "Messi10"RequiredThe ID of the agent in the external system
emailString "messi@awesomecompany.com"RequiredThe email address of the user who is to be logged in
iatNumber 1545894207RequiredThe value must be the number of seconds since the UNIX epoch. A maximum clock drift of 300 seconds is permitted.
nonceString "23456781234"Requirednonce passed by Freshworks as part of the login request to mitigate the replay attacks. It will be a random alpha-numeric string. The nonce is valid only for 10 mins from the time it is issued by FreshID.
given_nameString "Leo"RequiredFirst name or given name of the user
family_nameString "Messi"RequiredLast name or Family name of the user
phone_numberString "1010101010"OptionalPhone number of the user
pictureString "https://bit.ly/Lionel_Messi.jpg"OptionalProfile picture URL of the user.


How JWT SSO works 

  1. A user tries to log in to Freshworks' account. 

  2. Freshworks recognizes the user is not authenticated and is configured with JWT SSO. The user is redirected to the login URL configured in the account along with client_id, state, and nonce request params. Based on the client_id, you can redirect the user to an appropriate redirect URL as provided by Freshworks at the time of SSO configuration.

    If the login URL that is configured in Security settings is https://awesomecompany.com/sso/jwt/login, then the redirect URL would be https://awesomecompany.com/sso/jwt/login?client_id=a13v13&state=hgdg43567&nonce=1545894408&grant_type=implicit&scope=profile openid email
  3. The user is asked to authenticate his/her account.

  4. The identity provider authenticates the user and generates a JWT (JSON Web Token).

If Freshworks JWT SSO URL for this account is https://awesomecompany.freshworks.com/auth/12344/jwt, then the redirect url would be https://awesomecompany.freshworks.com/auth/12344/jwt?state=hgdg43567&id_token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.TCYt5XsITJX1CxPCT8yAV-TVkIEq_PbChOMqsLfRoPsnsgw5WEuts01mq-pQy7UJiN5mgRxD-WUcX16dUEMGlv50aqzpqh4Qktb3rk-BuQy72IFLOqV0G_zS245-kronKb78cPN25DGlcTwLtjPAYuNzVBAh4vGHSrQyHUdBBPM
  1. The user is redirected back to Freshworks with the encoded JWT in a query string. 

  2. Freshworks will validate the JWT token (using the public key/shared secret) and extract the user identity from the token. If the token is valid, creates the session for that user and logs the user into the portal.


Step-by-step process on how to configure SSO with JWT

  1.  Log in using your Org URL and navigate to the Org Dashboard. Click on the security settings in the sidebar. You can define a default security policy that will be applicable for all users in the organization including admins/agents. You can scroll down to turn on the Single Sign-On option and choose OAuth as the login method.

Note: Org Admins are the only ones who can configure SSO. 
Note: You can access the Organization Dashboard by opening the Freshworks Switcher and clicking on your organization link.
  1. You will be presented with the following fields:
  • Redirect URL - This is the URL where the user will be redirected once the authentication is successful. Make a note of this. 

  • Authorization URL: This is the URL you need to configure to instruct Freshworks to redirect the user to complete the authentication flow at your end. In that endpoint, the user authentication script is triggered and the JWT payload is generated. Example login URL could be https://awesomecompany.com/sso/jwt/login

  • RSA Public Key: Public Portion of RS256 Key that is generated by you. As instructed above, you need to generate an RS256 key where the private key portion is stored with you securely while the public portion of the key is configured here so that we can validate the JWT token that is generated by you. 

  • Logout URL - Optional logout URL to which the users will be sent when they logout.

  1. Fill in the relevant SSO configuration fields mentioned above. 

  2. Click on the Save button.


If you need further assistance, please feel free to write to support@freshworks.com with your queries. We're more than happy to help.