JWT Authentication with Mindbreeze
Configuration

JWT Introduction

JSON Web Tokens (JWTs) can be used to provide secure authentication and authorization for web applications and services. When a user logs in to an application, they are issued a JWT, which contains information about their identity and permissions. This token can be sent to the client service via an Authorization: Bearer header. The client service uses a JSON Web Key (JWK) to verify the JWT and extract the identity. By integrating Mindbreeze InSpire with JWT authentication, users can securely access content and services within the platform.

Preparation

For the configuration of JWT in Mindbreeze InSpire the following data is necessary:

• The JWKS JSON which contains the public keys of the user pool.
• Examples:
  • At Cognito this can be downloaded with a URL in the following form:
    Concrete Example: https://cognito-idp.eu-central-1.amazonaws.com/eu-central-1_AbCdEf/.well-known/jwks.json
  • For Microsoft Entra ID Applications the JWKS URL is https://login.microsoftonline.com/{{tenant_id}}/discovery/v2.0/keys, where {{tenant_id}} is the Directory (tenant) ID of the Microsoft Entra ID Application.
• Hint: The JSON contains one or more RSA public keys that can be used to verify the signature of the JWT.

• The issuer (iss) claim.
• Examples:
• For Cognito, this is a URL in the following form: https://cognito-idp.{{region}}.amazonaws.com/{userPoolId}}. The placeholder {{region}} corresponds to the AWS region where the user pool sits and the placeholder {{userPoolId}} corresponds to the ID of the user pool.
  Concrete Example: https://cognito-idp.eu-central-1.amazonaws.com/eu-central-1_AbCdEf

Microsoft Entra ID Application: the iss claim value is https://sts.windows.net/{{tenant_id}}/.

• The Audience (aud) Claim.

Examples:

• In Cognito, this corresponds to the client_id of the client used to log onto the user pool, e.g. 1a2b3c4d5e6f7g8h9i1a2b3c4d
• In Microsoft Entra ID this is in the form of api://{{client_id}}, {{client_id}} being the Application (client) ID of the Microsoft Entra ID application.

Configuration

You find the configuration of JWT in the MMC Configuration in the tab “Client Service” in section

„JWT Authentication Settings“:

Activate "Enable JWT Authentication".

In the text field "JWKS JSON" insert the content of the JSON downloaded in the “Preparation” section.

As an alternative to the "JWKS JSON" option, you can use the "JWKS URI" option to specify a file URI pointing to a JWKS file in the file system of the appliance, e.g. file:///data/jwks-cognito.json or /data/jwks-cognito.json. To do this, create the JSON file (e.g. /data/jwks-cognito.json) in the Management Center (MMC) in "File Manager", "Local Filesystem" and paste the contents of the JSON downloaded in section "Preparation".

Additionally, JWKS endpoints URLs are also supported. For example:

• https://cognito-idp.eu-central-1.amazonaws.com/eu-central-1_YLjIaJICL/.well-known/jwks.json
• https://login.microsoftonline.com/{{tenant_id}}/discovery/v2.0/keys
• https://www.googleapis.com/oauth2/v3/certs

Note: Changes in the configured "JWKS JSON" file are effective immediately; thus, a restart of the client service is not necessary.

Then add the following "Required Claims Patterns“:

• Issuer Claim
  • „Claim Name“: iss
  • „Claim Pattern“: the issuer claim determined in the “Preparation” section, or a regular expression that matches valid issuer claims. (for example: https://cognito-idp.eu-central-1.amazonaws.com/eu-central-1_AbCdEf)
• Audience Claim
  • „Claim Name“: aud
  • „Claim Pattern“: the audience claim identified in the “Preparation” section, or a regular expression that matches valid audience claims (for example: 1a2b3c4d5e6f7g8h9i1a2b3c4d)
• Token Use Claim:
  • „Claim Name“: token_use
  • „Claim Pattern“: id (This always has the same value "id" in Cognito)

Then configure the setting "JWT Identity Claim Names". This determines which claim is used for the identity in the Mindbreeze InSpire search (e.g: cognito:username ).

If the Client Service should be able to handle tokens from different OAuth clients with different claims, multiple Identity Claim Names can be configured. This is needed if you have different tokens where, for example, some of them specify the "email" claim that should be taken as the identity and some tokens specify the "upn" claim. The claims are then checked in order of specification. According to the example, this would mean that the token for the "email" claim is checked first and if it is not present, the token for the "upn" claim will be checked next.

This should be done with extreme caution to avoid misassignment of the identity.

If there are additional claims that should be used as principals in the Mindbreeze search, configure them in "JWT Principal Claim Names". The principal claims can be single values or an array of values.

Protected Resource Metadata (RFC 9728)

The Mindbreeze InSpire Client Service also functions as an MCP server gateway, providing OAuth authentication support for MCP clients. When an MCP client tries to connect for the first time, the server responds with the status code 401 (= unauthorized) and tells the client, where to find authorization information, which is saved in a Protected Resource Metadata (PRM) document.

The document is hosted by the MCP server (client service), follows a predictable path pattern, and is provided to the client in the resource_metadata parameter within the WWW-Authenticate header.

The URL path for the PRM document is in the case of the Mindbreeze InSpire Client: /api/modelcontextprotocol.2025-11-25/.well-known/oauth-protected-resource.

To provide a PRM document for MCP clients, the following parameters are required to be set in the Client Service Configuration:

• Authorization Server URL: URL of the OAuth Authorisation Server.
  • Example: A Microsoft Entra ID OAuth Authorization Server: https://login.microsoftonline.com/{{tenant_id}}/v2.0
• Authorization Server Allowed Scopes: A list of OAuth scopes.
  • Depending on the configured authorization server, this might be needed for the MCP clients to request an authorization token.
• Authorization Server Resource: MCP Server URL, the resource for which the OAuth token will be requested.
  • Example:

Appendix

Setting up a Microsoft Entra ID Application as OAuth Authorization Server

In this section, an example is provided of how to set up a basic OAuth Authorization Server using a Microsoft Entra ID application. This application can be used in the JWT authentication setup described in the previous sections. The configured application is also ready to be used for authentication from MCP clients such as ChatGPT.

Log in to the Microsoft Entra ID administration portal (https://portal.azure.com/) with a credential that is permitted to create application registrations and perform the following steps:

1. Register a Microsoft Entry ID application by navigating to “App Registrations” on the administration portal and click on “New registration”:

1. Set the application name and click on “Register” to register the new application.

1. For supporting requesting user access token with OAuth Authorization Code Flow, please configure a client secret on the “Certificates and Secrets” panel of the newly created application:

1. After creating the client secret make sure you are copying the value so that you can use it later. Copying the value of a secret is only available on creation in Microsoft Entra ID.

1. OAuth login use cases often require that the application defines one or more custom scopes. This can be set up in Microsoft Entra ID on the “Expose an API” section of the application configuration. After setting the application URI, please set up the new scope:

If the Microsoft Entra ID application is created, the “JWT authentication settings” in the Mindbreeze InSpire Client Service can be set as follows:

For enabling MCP clients to log in using protected resource metadata, the following settings are needed:

Fallback to other Authentication Methods

If the header "Authorization: Bearer {{token}}" is not included in the request, an attempt will be made to log the user on with a different authentication method, if any is configured. For example, SAML can be configured to be the fallback authentication method.

To disable this behavior, the option "Optional JWT Authentication" can be disabled. If the request does not contain a JWT, requests are answered strictly with HTTP status code 403.

Troubleshooting

Every access to an authenticated resource (e.g. https://mysearch.com/api/v2/search) must contain a valid JWT token. Otherwise, the error code HTTP 403 is returned. The following criteria must be met:

• The HTTP request must contain an Authorization: Bearer {{token}} have headers
• The {{token}} must be a JWT token string in valid format
• The token must have a valid signature that can be verified with a public key in JWK JSON
• The token must not have expired
• The token must contain all configured "Required Claims Patterns".
• The token must contain the "JWT Identity Claim Name".

If one of these criteria is not met, there is no message in the log with default settings.

Enable “Full Logging" (optionally only on the log region com.mindbreeze.enterprisesearch.webapp.jwt). This logs detailed messages about why the JWT token is not valid.

Hint: (online) tools such as https://jwt.io/ are suitable for the analysis of JWT tokens (Mind data protection).