Strategy One

Configure JWT Authentication on the Library Server

Starting in Strategy One (November 2025), you can create security filters while configuring JWT authentication for your Library server. This addition allows you to define user security filters according to your configured claims.

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. Starting in Strategy One (November 2025), in 5. Security Filter Template, click Add next to a Project.

    1. The Security Filter Template dialog displays.

    2. Click New Qualification.

    3. Find an object in the left pane and click and drag it to Based On or search an object in Based On.

    4. Expand the Qualify On drop-down list and choose a form.

    5. Expand the Operator drop-down list and choose an operator to filter on.

    6. To add a JWT claim, next to Value, click Claim.

      The claim must also exist in the Identity Provider (IDP). If a claim name in a qualification does not exist in the IDP, enable Omit if Unset, as described in step k, for the qualification.

    7. In New Claim, type a Name, Multi Value (if available), and Delimiter (if available).

    8. Click OK.

    9. To add more qualifications, repeat steps b through h.

    10. To set a condition so it applies if the value is not met, click More Options and select the check box next to NOT.

    11. To exclude a condition if it is unset, click More Options and select the check box next to Omit if unset.

      When a qualification has Omit if unset selected, the panel displays it as OPTIONAL, and it will be omitted from the final security filter if the claim value is not set.

    12. To delete a condition, click Delete.

    13. Click Save.

      After completing the JWT authentication, the security filter template is added to each user in the selected project. For more information on viewing the security filters, see Manage Security Filters for a User.

  9. 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 Failure

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.

JWT Security Filter Authentication Failure

JWT authentication might fail due to incorrect security filter configuration or missing information from the JWT payload. If you encounter errors when configuring security filters, use the following checklist to troubleshoot:

  • For each claim used in the security filter template, ensure it is included in the JWT login or the associated filter predicate is set to OPTIONAL.

  • Attribute forms used in the security filter predicate have different data types. When compared with a JWT claim, ensure the claim value matches the attribute form type.

  • Check the Library log for a JWT authentication error.