search string side menu

Update keys for JWT tokens

In BRIX, JWT tokens (JSON Web Tokens) are applied for user authentication. They are automatically issued to employees after the users successfully enter their login and password. These tokens are required to authorize users when they access the system.

 

A TLS certificate and a key are used to verify the validity of issued tokens. They are generated automatically during system installation. For increased security, it is recommended to update these keys regularly — at least once a year.

 

To minimize the impact of this process on user experience, you can configure seamless transition to updated keys. To do this:

  1. Create a new TLS certificate and a key to verify the user's JWT token and save them in the vahter service secrets.
  2. Set a deletion date for the old TLS certificate and key for the JWT token.
  3. While the old TLS certificate and key remain active, the JWT tokens verified by them will be updated automatically when the user performs any action in the system.
  4. If the user is not logged in during the key rotation, they will need to re-enter their username and password the next time they log in to receive a JWT token verified by the new key.

Configuring update of the TLS certificate and key for JWT tokens varies depending on the installation method:

 

Update JWT token keys for BRIX in Kubernetes

For the BRIX On‑Premises Standard Kubernetes and BRIX On‑Premises Enterprise editions, follow these steps:

 

  1. Obtain a TLS certificate and a key in one of the following ways:
  1. Use a ready-made TLS certificate and key.
  2. Generate them using the following commands:
  • TLS certificate:

openssl req -newkey rsa:4096 -nodes -keyout cryptedjwtTls.key -x509 -sha256 -days 365 -subj "/C=RU/O=ELMA365/CN=MYDOMAIN.COM" -addext "subjectAltName = DNS:MYDOMAIN.COM" -out jwtTls.crt

  • Key:

openssl rsa -in cryptedjwtTls.key -traditional -out jwtTls.key

 

Where:

  • -days 365 is the TLS certificate validity period in days.
  • MYDOMAIN.COM is the company domain.
  • jwtTls.crt is the name of the TLS certificate file.
  • jwtTls.key is the name of the key file.
  1. Open the values‑elma365.yaml file and in the vahter microservice configuration block, enable the renewToken parameter by setting it to true:

vahter:
  secrets:
    renewToken:
      enabled: true

  1. Configure the update settings of the TLS certificate and key for JWT tokens:

vahter:
 secrets:
   renewToken:
     enabled: true
     schedule: "0 * * * *"
     oldTokenExpiry: "2025-05-14"
     certNew: |
       -----BEGIN CERTIFICATE-----
       ...
       -----END CERTIFICATE-----
     keyNew: |
       -----BEGIN RSA PRIVATE KEY-----
       ...
       -----END RSA PRIVATE KEY-----

Where:

  • schedule. Set the schedule for automatically running the cronjob and replacing old keys. For example, we've set it to run every hour, every day.
     
    cronjob is a Kubernetes tool that allows you to schedule a recurring operation. For more information about cronjob configuration rules, see the official Kubernetes website.
  • oldTokenExpiry. The date when users with old JWT tokens will no longer be able to log in. For example, we've set it to: 2025-05-14.
  • certNew. Specify the TLS certificate by copying the contents of the jwtTls.crt file you obtained in step one.
  • keyNew. Specify the key by copying the contents of the jwtTls.key file you obtained in step one.
  1. Update the system services using the command:

helm upgrade elma365 elma365/elma365 values-elma365.yaml

 

After the update, the new TLS certificate and key will be written to the vahter service secrets. When the date specified in the oldTokenExpiry parameter occurs, the old TLS certificate and key for JWT tokens will be deleted.

 

  1. For increased security, remove the TLS certificate and key entered in step three from the values-elma365.yaml configuration file, or restrict access to this file.

 

Update JWT token keys for BRIX in KinD

For the BRIX On‑Premises Standard installation in KinD, follow these steps:

  1. To configure JWT token key renewal, navigate to the BRIX application docker container using the command:

docker exec -it elma365 /bin/bash

 

Where elma365 is the name of the docker container.

  1. Obtain a TLS certificate and key in one of the following ways:
  1. Use a ready-made TLS certificate and key.
  2. Generate a TLS certificate and key in the docker container using the command:

openssl genrsa -out jwtTls.key 4096 && openssl req -new -key jwtTls.key -nodes -x509 -sha256 -days 365 -subj "/C=RU/O=ELMA365/CN=MYDOMAIN.COM" -addext "subjectAltName = DNS:MYDOMAIN.COM" -out jwtTls.crt

Where:

  • -days 365 is the TLS certificate's validity period in days.
  • MYDOMAIN.COM is the company domain.
  • jwtTls.crt is the name of the TLS certificate file.
  • jwtTls.key is the name of the key file.

 

  1. To replace JWT tokens without requiring users to re‑enter their login and password, add the new TLS certificate and key to the vahter service secrets using the following commands:

 

BASE64_KEY=$(cat jwtTls.key | base64 -w 0) && kubectl patch secret vahter-jwt -n <namespace> --type='json' -p="[{\"op\": \"add\", \"path\": \"/data/tls_new.key\", \"value\": \"$BASE64_KEY\"}]"

 

BASE64_CERT=$(cat jwtTls.crt | base64 -w 0) && kubectl patch secret vahter-jwt -n <namespace> --type='json' -p="[{\"op\": \"add\", \"path\": \"/data/tls_new.crt\", \"value\": \"$BASE64_CERT\"}]"

Where:

  • namespace is the namespace in which the BRIX application is installed.
  • jwtTls.crt is the name of the TLS certificate file.
  • jwtTls.key is the name of the key file.
  1. To update the key data, restart the vahter pod using the command:

 

kubectl rollout restart deployment vahter -n <namespace>

Where namespace is the namespace in which the BRIX application is installed.

 

  1. On the scheduled end date of the JWT update, ensure that the TLS certificate and key generated in second step are in the docker container and replace the old TLS certificate and key with the new ones using the following commands:

 

BASE64_KEY=$(cat jwtTls.key | base64 -w 0) && kubectl patch secret vahter-jwt -n <namespace> --type='json' -p="[{\"op\": \"add\", \"path\": \"/data/tls.key\", \"value\": \"$BASE64_KEY\"}]"

BASE64_CERT=$(cat jwtTls.crt | base64 -w 0) && kubectl patch secret vahter-jwt -n <namespace> --type='json' -p="[{\"op\": \"add\", \"path\": \"/data/tls.crt\", \"value\": \"$BASE64_CERT\"}]"

 

Where:

 

  • namespace is the namespace in which the BRIX application is installed.
  • jwtTls.crt is the name of the TLS certificate file.
  • jwtTls.key is the name of the key file.

 

  1. Remove the previous secrets using the following commands:

 

kubectl patch secret vahter-jwt -n <namespace> --type='json' -p='[{"op": "remove", "path": "/data/tls_new.crt"}]'

kubectl patch secret vahter-jwt -n <namespace> --type='json' -p='[{"op": "remove", "path": "/data/tls_new.key"}]'

 

Where namespace is the namespace in which the BRIX application is installed.

 

configmap.html postgresql-performance-diagnostics.html