How to Configure JWT Base Single Sign-On (SSO) in BoldDesk

This guide outlines the steps to configure JWT (JSON Web Token) based Single Sign-On (SSO), enabling seamless, secure, and token-based authentication between your identity provider and BoldDesk platform.

What is a JSON Web Token (JWT)?

A JSON Web Token (JWT) is a compact, URL-safe token format defined by RFC 7519. It is used to securely transmit information between parties as a JSON object.

Key features of JWT

• Digitally signed for integrity and authenticity.
• Compact and easy to include in URLs and headers.
• Carries all necessary user data (Self-contained).

What is JWT SSO?

JWT-based Single Sign-On (SSO) allows users to authenticate once through your organization’s identity provider and gain seamless access to the BoldDesk portal without re-entering credentials.

After successful authentication, the system issues a digitally signed JSON Web Token (JWT).

This acts as a secure, self-contained credential, like a digital passport, that carries verified user identity information.

By using JWT SSO, organizations ensure a smooth and secure login experience while maintaining trust and control over user access.

JWT structure

A JWT consists of three Base64Url-encoded components, separated by periods (.). Each part plays a distinct role in ensuring secure and verifiable data exchange.

Token structure overview

Header.Payload.Signature

1. Header

   Generally, the header as the first part of the JWT, contains two fields:

   • The “alg” value indicates the encryption algorithm (for BoldDesk, this is RS256).
   • The “typ” value specifies the token type (in this case, JWT).

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

   Note: This section is Base64Url encoded.

2. Payload (Claims)

   The payload is the second part of the JWT. It consists of the user’s identity information or other details (also in JSON format). In other words, this is where you put the actual user data or metadata exchanged securely.

   {
     "name": "John",
     "email": "john@company.com",
     "iat": 1545894207,
     "returnUrl": "/agent"
   }
   

   Note: This sections is encoded in Base64Url and is readable by anyone. Do not include sensitive information.

3. Signature

   Signature is the third part of the JWT that ensures the token’s integrity and authenticity.

   To generate the signature, concatenate (combine) the Base64Url-encoded Header and Payload using a period (.) as a separator, then sign the result using your RSA private key.

   RS256(
     privateKey,
     SHA256(base64UrlEncode(header) + "." + base64UrlEncode(payload))
   )
   

   Note: Result is Base64Url-encoded.
   
   

Generating RSA keys (For RS256)

To use RS256 for signing JWTs, you’ll need a matching RSA key pair. That is:

• Private key: Used to sign the token.
• Public key: Used to verify the token’s signature.
  
  

Option 1: Use online tools

You can generate RSA keys using these tools:

• https://www.csfieldguide.org.nz/en/interactives/rsa-key-generator/
• https://travistidwell.com/jsencrypt/demo/

Option 2: Command line

Create RSA keys locally using ssh-keygen as follows:

# Generate the Private Key
ssh-keygen -t rsa -b 2048 -m PEM -f jwtRS256.key
# Use empty passphrase 
ssh-keygen -f jwtRS256.key.pub -e -m pem > jwtRS256_public.pem

Note

To ensure secure JWT authentication, follow these key handling guidelines:

1. Private key:

• Use your RSA private key exclusively to sign JWTs.
• This key is strictly for internal use within your organization.
• Never share the private key outside your team.
• Maintain tight control and secure storage to prevent unauthorized access.

2. Public key: Share your RSA public key with the BoldDesk portal to enable JWT signature verification during login.

Example of a complete JWT

When combined, the full JWT (JSON Web Token) looks like this:

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

Note: RS256 is the exclusive signing algorithm supported by BoldDesk, as it offers greater security.

Required claims for JWT payload

Optional claims for JWT payload

How JWT-based single sign-on (SSO) works

JWT SSO setup in BoldDesk portal

To enable JWT SSO in the BoldDesk system, follow the steps below:

1. Log onto the administrator section of your BoldDesk portal.

2. Go to Admin Settings > Customer Portal Settings.

3. Switch to the Login configuration tab to manage authentication settings. You will be presented with the following fields:

   Field	Description
   Authorization URL	The endpoint where users are directed to authenticate via your identity provider.
   Redirect URL	The BoldDesk URL that receives the JWT after authentication for session initiation.
   RSA Public Key	The public key used by BoldDesk to validate the JWT signature for secure login.
   Logout URL	(Optional) Destination URL for users after logging out from BoldDesk.

Authentication flow using JWT

1. User requests access

When a user attempts to sign in to our BoldDesk portal, the system first checks if the user is authenticated. If not, and if JWT-based SSO is enabled, they are automatically redirected to your organization’s authentication page via specified authorization URL.

Sample Authorization URL: https://xyzcompany.com/login/jwt/authenticate

2. User login & token creation

Once the user successfully logs in via your Identity Provider, your system creates a JSON Web Token (JWT) containing user-specific claims like email, name, iat and optionally return URL, signs it with your RS256 private key, and prepares to return it.

3. Redirection to callback URL with JWT

The user is then sent back to BoldDesk, specifically to the configured callback address, with the freshly generated JWT included as a parameter.

Sample Redirect URL: https://YourBrandDomain.com/id/20250423143117/JWT/callback

The JWT is sent in the query string, typically as

https://YourBrandDomain.com/id/20250423143117/JWT/callback?token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.TCYt5XsITJX1CxPCT8yAV-TVkIEq_PbChOMqsLfRoPsnsgw5WEuts01mq-pQy7UJiN5mgRxD-WUcX16dUEMGlv50aqzpqh4Qktb3rk-BuQy72IFLOqV0G_zS245-kronKb78cPN25DGlcTwLtjPAYuNzVBAh4vGHSrQyHUdBBPM

4. Token validation & user login

Upon receiving the JWT, BoldDesk uses the public key that you previously uploaded to check the authenticity of the token.

If the token is valid:
* The claims are extracted.
* A new session is created. The user is logged in automatically.

If validation fails (e.g., invalid signature, expired token, or missing claims), access is denied.

5. Logout flow (optional)

You can optionally configure a Logout URL so that users are redirected to your system after they log out from our platform.