A JSON Web Token (JWT) is an open standard that defines a compact and self-contained way of transmitting information between two parties as a JSON object.

Using JWT integration with HappyFox, you can build your own login portal or reuse an existing login portal for providing access to HappyFox support center. This way, your contacts do not need separate credentials to view their existing tickets or raise new tickets.

You can find more information about JWT here 🔖.

Applicable Plans: ✖️ Mighty ✔️ Fantastic ✔️ Enterprise ✔️ Enterprise Plus

Installing the JWT App in HappyFox:

• Log in to your HappyFox as an agent.
• Navigate to Apps >> Goodies >> Json Web Token (JWT).
• Click "Install".
• Provide the necessary values for the JWT Setup Fields.
• Click "Save Settings".

Setting up JWT integration in HappyFox

Enter the following details, 

• Remote Login URL:  This is the URL the client will be redirected to, if he/she logs into your HappyFox Support Centre.
• Remote Logout URL: This is the URL the client will be redirected to, once he/she logs out of your HappyFox Support Centre. 
• Key: The Key field will be prepopulated with a 32 character alphanumeric string.
• Whitelisted domains: A security feature where only Domains whitelisted will be able to access HappyFox via JWT. All other domains will be restricted. To enable this feature, turn on the "Allow JWT login only from whitelisted domains" toggle.
• Client Redirect URL: This is the URL to which your authentication system must redirect the client to after login:https://<your_account_name>.happyfox.com/jwt/?token=<token_string>. If custom domain is setup, use the appropriate custom domain url.

Generate the <token_string> using a JSON payload. A sample has been provided as follows:

{
  "name": "John Doe",
  "iat": 1717740457,
  "email" : "john@john.com",
  "jti" : "2c65fe8c-2494-11ef-9bc0-1e00e222b599"
}

The fields iat and jti are required fields

iat - Stands for issued at. This is a JWT standard formatted string that represents the time at which the token was generated. The sample provided above has been generated using int(time.time()) in python.

jti - This is a unique identifier for each request. The value 2c65fe8c-2494-11ef-9bc0-1e00e222b599 in the sample has been generated using str(uuid.uuid1()) in python.

To redirect users to their ticket list, home page and knowledge base use the return_to url parameter.

Home page: https://acme.happyfox.com/jwt/?token={JWT_Token_String}&return_to=/home

Ticket list: https://acme.happyfox.com/jwt/?token={JWT_Token_String}&return_to=/tickets

KB: Ticket list: https://acme.happyfox.com/jwt/?token={JWT_Token_String}&return_to=/kb

Once the feature is enabled, the login link in your Support Centre will redirect the user to the Remote Login URL specified above. Similarly, when the user logs out, they will be redirected to the Remote Logout URL.

Setting up your JWT implementation:

To authenticate a user, you need to send the following values to HappyFox as part of your JWT request. Please learn more about how to make a valid JWT request from jwt.io. 

• iat - Stands for Issued At. This is the time when the token was generated, this is used to help ensure that a given token gets used shortly after it's generated. The value must be the number of seconds since UNIX epoch.
• jti - Stands for JSON Web Token ID. A unique id for the token used to prevent token from being used multiple times (replay attacks).
• name - Name of the user logging in. 
• email - Email address of the user logging in.

These values need to be encoded with the HS256 algorithm with the Secret Key that you get from the JWT integrations page in your HappyFox account as mentioned above. Once the payload is encoded, redirect the user to https://<accountname>.happyfox.com/jwt/?token=<payload>

Once HappyFox validates the payload, it will log the user into the Support Centre with the specified name/email.