Cognito 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 JWK JSON which contains the public keys of the user pool.
• For example 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
• Note: the JSON contains one or more RSA public keys that can be used to verify the signature of the JWT.
• The issuer (iss) claim.
• For example, 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
• The Audience (aud) Claim.
• In Cognito, this corresponds to the client_id of the client used to log onto the user pool, e.g. 1a2b3c4d5e6f7g8h9i1a2b3c4d

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 "JWK JSON" insert the content of the JSON downloaded in the “Preparation” section.

As an alternative to the "JWK JSON" option, you can use the "JWK URI" option to specify a file URI pointing to a JWK 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".
Note: Changes in the configured "JWK 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.

Appendix

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.

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