ForumKB
Try it Free

How to set up JWT for SSO authentication in Bold BI

This section explains how to perform Single Sign-On (SSO) for users with the Custom JSON Web Token (JWT) in the Bold BI application.

Steps to configure JWT in Bold BI

  1. Login with this URL {Bold BI URL}/ums/administration using the admin credentials.

  2. Click on Authentication and then JWT.

    JWT Configuration

  3. Enable the JWT settings.

  4. Provide the following details in the JWT settings.

    Name It represents the name of the JWT provider to be displayed in the login page.
    Provider Logo It represents the logo of the JWT provider to be displayed in the login page.
    Remote Login URL It is the endpoint of the JWT provider to send the authorization request from Bold BI application.
    Remote Logout URL It is the endpoint of the JWT provider to send the logout request once user logged out in the Bold BI application.

  5. After the values are saved, the application will generate a Signing Key. This signing key must be used for signing JSON Web Tokens from your application.

  6. The Signing Key can be copied, viewed, and reset using the following options:

    Copy

  7. You can enable JWT token encryption by selecting Enable Encryption. Once activated, a public key is generated, which is used to encrypt the JWT token. This enhances security by ensuring that token payloads remain confidential and protected from unauthorized access. By default, encryption remains disabled

    Enable Encryption

  8. The JWT Encryption Key can be copied, viewed, and reset using the following options:

    Copy Encryption Key

How JWT works with Bold BI

  1. Once the JWT settings are configured, go to the Bold BI login page and click on the JWT login option. JWT Login

  2. After that, the application will generate the JSON Web Token for user and it will be submitted via an HTTP Form POST to the Bold BI callback URL https://{Bold BI URL}/sso/jwt/callback. The form POST will include the following parameters:

    • jwt
    • site_identifier
    • redirect_to

  3. The Bold BI application will validate the JWT and deserialize the user information from the token.

  4. Based on the user information, the Bold BI application will check if the user’s email already has access in the Bold BI application. If the user is already registered in Bold BI, they will be authenticated.

  5. If the user is not yet registered in the Bold BI server, they will be added as a user and authenticated to access the Bold BI application

JWT Callback URL

The JWT callback URL will validate the JWT response from the configured application.

After a user successfully logs into your configured application, you can redirect them to the specific URL provided.

{Bold BI URL}/sso/jwt/callback?jwt={token}&site_identifier={site identifier}&redirect_to={redirecturl}

Parameter Required Comments
jwt Yes JSON Web Token will be passed in this parameter. It will contain the JWT Payload
site_identifier No This parameter will be used to grant site access for the JWT user.

If the JWT login accessed from the tenant, Bold BI login URL will redirect to your application with tenant site identifier in URL query string. You can use this identifier in JWT response URL.

Example Url{Remote login URL}?site_identifier={site identifier}

NOTE: Should pass one site identifier. More than one identifier not allowed.
redirect_to No If this parameter is included in the JWT response, then the user will be redirected to that page, after the login process completed.

Enable JWT Callback with HTTP GET (Optional)

Note: Enabling GET requests may increase the risk of token exposure because JWT values can be recorded in browser history, URLs, and various logging mechanisms. It is strongly recommended to use HTTP POST whenever possible and enable GET support only when required for legacy workflow compatibility.

By default, the JWT callback endpoint accepts only HTTP POST requests to enhance security. Using POST helps prevent JWT tokens from being exposed in browser history, web server logs, proxy logs, and URL query parameters.

For backward compatibility, organizations that need to continue using the legacy (old) workflow can enable HTTP GET request support through the application configuration. When this option is enabled, the JWT callback endpoint will accept JWT tokens provided through URL parameters, allowing existing integrations to continue operating without modification.

  1. Go to {domain}/ums/administration
  2. Open Configuration in settings page.
  3. Select the dropdown and open config.json and then locate PreferSecureHttpVerbs.
  4. Set the PreferSecureHttpVerbs node to false. If the PreferSecureHttpVerbs node is not present, create it and configure it as false.

Enable JWT Callback Get

  1. After updating the configuration, save the changes and restart the application to apply the updated settings.

After the application is restarted, the JWT callback endpoint will accept HTTP GET requests for all tenant sites, enabling support for the legacy (old) workflow.

Create JSON Web Token

To create the JWT, use HMAC-SHA256 as the signing algorithm.

What parameters can be passed in the payload of JWT

A JWT should contain the following claims:

Parameter Parameter Name Value Type Required Comments
User Id sub string Yes Unique identifier of the user.
Email email string Yes Email address of the user.
First Name first_name string Yes First name of the user.
Last Name last_name string No Surname of the user.
Phone phone string No Phone number of the user.

JSON Web Token sample

Please refer to the following sample for instructions on how to generate the JWT.

private string GenerateJSONWebToken(UserModel userInfo)    
{    
    var signingKey = "signingkey";// Signing key value will copy from JWT Settings page
    var securityKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(signingKey));
    var credentials = new SigningCredentials(securityKey, SecurityAlgorithms.HmacSha256Signature, SecurityAlgorithms.Sha256Digest);

    var claims = new[] {
        new Claim("sub", "420c5d51-1754-4a9b-b4b5-d5bfebb21b0f")
        new Claim("email", "[email protected]"),
        new Claim("first_name", "Makila"),
        new Claim("last_name", "S"),
        new Claim("phone", "1234567890")
            };

    var token = new JwtSecurityToken(claims: claims,
                expires: DateTime.Now.AddMinutes(120),
                signingCredentials: credentials);

    return new JwtSecurityTokenHandler().WriteToken(token);
}