Overview

Single Sign On is the mechanism using which your agents can access Freshworks portals using the same credentials they are using to login to your internal systems. In this mechanism, the users credentials are verified in your systems and the user’s identity information is securely communicated via JSON Web Tokens with Freshworks. Freshworks then verifies the token and lets the user view the portals that he has access to without additional password checks.

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

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

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 using 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"RequiredID of the agent in external system
emailString "messi@awesomecompany.com"RequiredEmail address of the user who is to be logged in
iatNumber 1545894207RequiredThe value must be the number of seconds since UNIX epoch. 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. 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.

Steps to configure JWT SSO

  • Navigate to your Organization Dashboard and click on the Security section in the side bar.

    Please note that this option is only available to the Org Admins

    Note: You can access the Organization Dashboard by opening the Freshworks Switcher and clicking on your organization link.
  • In the available choices, turn on Single Sign-On option and choose JWT SSO.
  • You will be prompted with the JWT SSO URL. Make a note of this as this would be the endpoint you are supposed to redirect the user with JWT token post successful login at your end.
    • Login URL: This is the URL you need to configure to instruct Freshworks to redirect the user to complete the authentication flow at your end. Example login URL could be https://awesomecompany.com/sso/jwt/login
    • Verification 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.

How does JWT SSO work once it is successfully configured?

[Agent] Tries to access freshworks account by navigating to the freshworks account URL - for example, https://awesomecompany.freshworks.com


[Freshworks] Freshworks detects that this account is configured with JWT SSO and redirects the user to the login URL configured in the account along with module_id, state and nonce request params. Based on the module ID, you can redirect the user to 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?**module_id**=a13v13&**state**=hgdg43567&**nonce**=1545894408&grant_type=implicit&**scope**=profile openid email

[Identity Provider Server] Present the login page and verify the credentials. Once the credentials are verified, redirect the user to Freshworks SSO URL that is present in the account UI along with the constructed JWT token and state parameter. Read below to know more about how to construct the JWT token and sign it.

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

[Freshworks] 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 him into the portal.