freshworks

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.

• SSO Overview
• Implement Single Sign-On for Freshworks 
• How is the authentication data securely exchanged between IdP and SP
• Terms and definitions to understand SSO better 
• Agent SSO and Contact SSO for an Organization

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": "[email protected]",
    "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?

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://madmaggie.myfreshworks.com/sp/OIDC/629884134309915544/implicit then the redirect url would be https://madmaggie.myfreshworks.com/sp/OIDC/629884134309915544/implicit?state=hgdg43567&id_token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.TCYt5XsITJX1CxPCT8yAV-TVkIEq_PbChOMqsLfRoPsnsgw5WEuts01mq-pQy7UJiN5mgRxD-WUcX16dUEMGlv50aqzpqh4Qktb3rk-BuQy72IFLOqV0G_zS245-kronKb78cPN25DGlcTwLtjPAYuNzVBAh4vGHSrQyHUdBBPM

5. The user is redirected back to Freshworks with the encoded JWT in a query string. 

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

Note: The new Security UI will be enabled by default on 30 Nov 2020. You can try our new features and redesigned UI in advance by clicking on the link present in the banner at the top of the Security section. 

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

1. Log in using your organization URL. Click on the 'Security' icon in the sidebar. Under Security> Agents & Employees  > Default Login Methods, you can enable SSO to simplify your users' login experience. Choose JWT as your login protocol and the IdP of your choice.

Note: Organization Admins are the only ones who can configure SSO. Default login methods are applicable for all users in the organization, including admins/agents. If you want to create specific policies for a particular account or portal, configure it under Custom Policies. For contacts, configure any security policies under Security > Contacts. 

Note: You can access the Neo Admin Center by opening the Freshworks Switcher and clicking on your organization link.

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

3. Fill in the relevant SSO configuration fields mentioned above

If you need further assistance, please feel free to write to [email protected] with your queries. We're more than happy to help.