Strategy One

Configure JWT Authentication on the Library Server

Strategy One (September 2025) adds support for JSON Web Token (JWT) authentication to the Library server. You can send a Library login API with a signed JWT. The Library server then uses this information to create a valid user session.

Prerequisites

  • Integrate Library JWT authentication into a custom login workflow. The workflow should generate signed JWTs with user information and send Library login API requests.

  • Your administrator account must have the following Server - Intelligence privileges:

    • Configure server basic

    • Configure security settings

    • Configure governing

    • Administer environment

    • Use Workstation

Configure JWT Authentication

  1. Open the Workstation window and connect to your environment.

  2. Right-click your environment and choose Configure Enterprise Security and Configure JWT.

  3. In 1. General Settings, type the JWT's Issuer and Audience.

    The values must exactly match the iss and aud properties of the incoming JWT. Strategy only supports verifying one iss / aud pair.

  4. 2. Key Configuration specifies the keys used to verify incoming JWTs. Strategy supports three key sources:

    • Issuer: This option uses the OpenID Provider Issuer Discovery process to determine the jwksUri. Strategy then fetches the public keys remotely from the OpenID provider metadata. This option requires issuer support, often from OpenID providers, and the iss must match the issuer's base URL.

    • JWKS URI: This option requires the admin to provide the jwksUri to fetch JWKs for JWT verification.

    • Static Key: Administrators provide the keys and algorithm for JWT authentication.

      • Signature Algorithm: The alg in the JWT header. Key value formats vary based on the selected algorithm.

      • Symmetric keys (HS256 / HS384 / HS512): The Shared Secret must be a UTF-8 string. Length requirements vary by algorithm:

        • HS256: 32 bytes or more

        • HS384: 48 bytes or more

        • HS512: 64 bytes or more

      • Asymmetric keys (algorithms beginning with RS, PS, and ES) only accept Public Key in base64-encoded PEM format. This includes the generic PEM header/footer (-----BEGIN PUBLIC KEY-----\n ,,, \n-----END PUBLIC KEY-----). The public key must match the specified algorithm and meet security requirements. You can use your own public key or generate a pubic/private key pair and use the private key for JWT generation.

      Strategy only supports PEM files in SPKI format. Convert other formats to SPKI PEM before entering them in Public Key (PEM). The following formats require conversion:

      • PEM files in PKCS format (often begin with -----BEGIN RSA PUBLIC KEY-----)

      • EC-specific format (begin with -----BEGIN EC PUBLIC KEY-----)

      • Non-PEM formats like JKS

  5. In 3. User Claim Mapping, configure JWT claims as Intelligence server user attributes.

    User ID mapping is required. It maps the given claim to a trusted authentication ID. Nested claim mapping is not supported.

  6. In 4. System Prompt, configure mapping rules between user system prompts and JWT claims.

    Available SSO system prompts include 15 text, 15 numeric, and 10 date prompts. Nested claim mapping is not supported.

  7. Click Save.

    Workstation may prompt you to restart the Library server to apply the JWT configuration for the first time.

Perform JWT Login

Your login workflow must generate a signed JSON Web Token that Workstation can validate with a public key or shared secret. The JWT must meet the requirements:

  • The exp claim must be present. Strategy does not support JWTs without an expiration time.

  • The JWT must contain a claim mapped to the User ID.

Use the Library authentication API for JWT login.

Copy 
POST /api/auth/login

{
  "loginMode": 67108864,
  "password": "<jwt string>",
  "maxSearch": 3,
  "workingSet": 10,
  "metadataLocale": "en_us",
  "warehouseDataLocale": "en_us",
  "displayLocale": "en_us",
  "messagesLocale": "en_us",
  "numberLocale": "en_us",
  "timeZone": "UTC",
  "applicationType": 35
}

Most properties in the request JSON payload are the same as other login modes, besides the following:

  • loginMode: Set to 67108864

  • username: Not required. Leave this property not defined.

  • password: Assign the JWT string to this field.

If you provide the correct JWT, login succeeds with a web session and X-MSTR-AuthToken in the response header.

Troubleshooting

JWT authentication may fail due to misconfiguration or mismatch with the generated JWT. Use the following checklist to troubleshoot:

  • Verify JWT authentication mode is enabled or the trust relationship is set up. To resolve, open the JWT config dialog, save it again, and restart the Library server, if prompted.

  • Examine the generated JWT using JWT tools to ensure it is correct. Check the following:

    • The JWT signature and alg must match the Workstation configuration.

    • The iss and aud values must match the Workstation configuration.

    • The exp must be a future time. Ensure the Library server machine time is correct or synced with the API client's time, as the Library server evaluates this value.

    • Confirm the mapped claim for User ID exists. Verify that claims for other attributes and system prompts are present.

  • Check Library logs for server-side errors.