Using Bearer Authentication with Seeq

Introduction

Bearer token authentication using JWT (JSON Web Tokens) is a secure method for accessing resources in Seeq. It is configured as part of the OAuth 2.0 connector setup (see OpenID Connect). This article outlines the steps for setting up and using JWT tokens to authenticate with Seeq, covering the required configurations and key restrictions.

Key Restrictions

JWT Tokens Only: Seeq supports only JWT tokens, not opaque tokens.
OAuth Connection: An OAuth connection to Azure must be created in Seeq and indexed for bearer authentication to work. The audience claim (aud) in the JWT token must match the ExpectedAudience configured in the OAuth connector in Seeq.
JWT Claims, user: The JWT token must include the following claims:
- email claim
- aud claim
- iss claim
JWT Claims, application: The JWT must include the following claims:
- aud claim
- iss claim
- <client ID claim>: the name of this claim depends on the IdP and version. Must be specified as the OidcApplicationUsernameClaim for the OAuth 2.0 connection specified for the Application
  - Entra ID v1.0 token: appid (ref: https://learn.microsoft.com/en-us/entra/identity-platform/access-token-claims-reference )
  - Entra ID v2.0 token: azp (ref: https://learn.microsoft.com/en-us/entra/identity-platform/access-token-claims-reference )
  - Okta token: cid (ref: https://developer.okta.com/docs/api/openapi/okta-oauth/guides/overview )
  - Google OpenID Connect: azp (ref: https://developers.google.com/identity/openid-connect/reference#id_token_claims )
Key ID: The JWT token's header must contain a Key ID (kid).
User Creation: The user must log in to Seeq at least once for their account to be created.
User Status: The user in Seeq must be enabled.

Configuring OAuth 2.0 connector for Bearer Authentication

Steps:

Locate Your OIDC Connection:
- In the OAuth connection configuration, locate the ExpectedAudience field.
Set the ExpectedAudience:
- This should be set to the audience claim that your OIDC application will issue in the JWT token. For an Entra ID application, it will typically be in the format: api://<your-application-id>.
Wait for an Index on Your OIDC Datasource: this should happen automatically for an OAuth 2.0 connection after the configuration is changed

Ensure the ExpectedAudience matches the aud claim in the JWT, as Seeq uses this to validate that the token is intended for its API.

Testing the configuration

You can use Postman to verify your bearer authentication setup by generating a JWT token from Azure AD and using it to call a Seeq API endpoint, such as:

http://<your-seeq-server>/api/users/me

This particular endpoint returns information about the authenticated user and is a good way to test that the token is accepted and correctly linked to a Seeq user.

Step 1: Get a JWT Token using Postman

Open Postman.
Click Authorization tab.
Set Type to OAuth 2.0.
Fill in the details:

Field	Value
Token Name	Seeq Test Token
Grant Type	Client Credentials
Access Token URL	`https://login.microsoftonline.com/<your-tenant-id>/oauth2/token`
Client ID	Your Azure AD app's client ID
Client Secret	Your Azure AD app's client secret
Scope	`openid profile email`

Click Get New Access Token.
Once retrieved, click Use Token.

Step 2: Call the Seeq API with the Token

Set the HTTP method to GET.
Set the URL to:

http://<your-seeq-server>/api/users/me
In the Headers tab, create a Accept header with value application/vnd.seeq.v1+jsonapplication/vnd.seeq.v1+json
In the Authorization tab, make sure the token you retrieved is still selected.
Click Send.

Expected Result

200 OK: The token is valid, and the user exists and is enabled in Seeq. The response will include user details (username, first name, last name, email, etc.).
401 Unauthorized: Indicates token issues (missing/invalid claims) or that the user is not found or is disabled.

Troubleshooting

If you encounter issues, refer to the following common errors in appserver.log and their solutions:

Missing Email Claim or Oidc Application Username Claim:

java.lang.IllegalArgumentException: JWT token does not contain an email claim or the datasource's Oidc Application Username Claim

Solution: Ensure the token contains an email claim, if authenticating a user, or the claim specified by the OidcApplicationUsernameClaim configuration parameter of the OAuth 2.0 connection for the Identity Provider, if authenticating an Application
Missing Audience Claim:

java.lang.IllegalArgumentException: JWT token does not contain an audience claim

Solution: Ensure the token contains an aud claim.
Missing Issuer Claim:

java.lang.IllegalArgumentException: JWT token does not contain an issuer claim

Solution: Ensure the token contains an iss claim.
Audience Claim Mismatch:

JWT token audience claim '******' does not match expected value

Solution: Ensure the value printed in the log matches the ExpectedAudience configured in the OAuth connector in Seeq.
Token Validation Error:

Error validating JWT token

Solution: Ensure the token is valid and not expired.
Disabled User:

User '****' was ignored because it is disabled

Solution: Ensure the user is enabled in Seeq.

To troubleshoot, you may consider parsing your access tokens in an online JWT debugger like jwt.io. A JWT debugger can decode an access token so you can review the header and claims.