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: The JWT token must include the following claims:

  • email claim

  • aud claim

  • iss claim

• 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 Azure Connection:

  • In the OAuth connector configuration, identify your Azure connection and locate the ExpectedAudience field.

• Set the ExpectedAudience:

  • This should be set to the audience claim that your Azure AD application will issue in the JWT token. It will typically be in the format: api://<your-application-id>.

• Request an Index on Your Azure Data Source:

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

1. Open Postman.

2. Click Authorization tab.

3. Set Type to OAuth 2.0.

4. Fill in the details:

5. Click Get New Access Token.

6. Once retrieved, click Use Token.

Step 2: Call the Seeq API with the Token

1. Set the HTTP method to GET.

2. Set the URL to:

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

3. In the Headers tab, create a Accept header with value application/vnd.seeq.v1+jsonapplication/vnd.seeq.v1+json

4. In the Authorization tab, make sure the token you retrieved is still selected.

5. 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:

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

  Solution: Ensure the token contains an email claim.

• 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.