Authentication with JWT

Introduction

This page explains how to configure QueryDeck to use JWT mode for authenticating incoming requests.

In this setup, your authentication service issues a JWT to the client, which is then included in the request to QueryDeck in the format: Authorization: Bearer <JWT>.

QueryDeck verifies and decodes the JWT to extract the session variable. The session variable is required, along with the user ID and any other information you need to define access to your data.

QueryDeck JWT

Example Encoded JWT

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODlhMCIsIm5hbWUiOiJKb2huIERvZSIsImFkbWluIjp0cnVlLCJpYXQiOjE1MTYyMzkwMjJ9.1i3oPBiRHkw_XKXhd7y6T-DcQV7A_yK8WzFlV35esAU

Example Decoded JWT

{
  "sub": "123456789a0",
  "name": "John Doe",
  "admin": true,
  "iat": 1516239022
}

---

In this example:

• Decoded Payload includes:

  • "sub": Subject ID, uniquely identifying the user.

  • "name": The name of the user, "John Doe".

  • "admin": Boolean value indicating if the user has admin rights (true in this case).

  • "iat": Issued At, a timestamp indicating when the token was created (in Unix time format).

This JWT can be included in the HTTP request header as Authorization: Bearer <JWT>. QueryDeck will verify this token, and based on the payload, determine the user’s role and access level.

JWT.io is a useful tool for decoding, verifying, and debugging JWTs. You can paste a JWT to view its payload and signature, ensuring it includes the necessary claims for authentication. It also allows you to generate test tokens, making it ideal for troubleshooting JWT-based access control setups.

QueryDeck Authentication Config

Head to Security > Authentication to Setup Authentication

This setup screen is for configuring JWT-based authentication in QueryDeck. Here’s a breakdown of each field:

1. Algorithm: This specifies the algorithm used to verify the JWT signature. In this case, it’s set to HS256, which is HMAC-SHA256, a common choice for signing tokens securely.

2. JWT Public Key: The public key used to verify the JWT signature. This key is essential because it allows QueryDeck to authenticate the token provided in the request header, ensuring it was issued by a trusted source.

3. User Session Key: Here, you would enter the key name (usually a session variable like user-id) that represents the user ID or unique identifier in the JWT. This key is used to extract the user's identity from the token.

4. Add Column (Select Table and Select Column): This section allows you to select specific tables and columns to which you can apply additional session-based permissions. This enables more granular access control at the data level, depending on user roles or other session variables.

5. Role Session Key: Enter the session key (e.g., x-querydeck-role) that represents the user's role in the JWT. This role determines the permissions for the user and can be used to apply role-based access control (RBAC) rules in QueryDeck.

6. Authorization Header Token Name (Optional): This is the name of the HTTP header that will carry the JWT in requests. By default, it’s set to authorization, meaning the JWT should be sent in an Authorization: Bearer <JWT> header. You can change it if your setup requires a different header name.

How It Works?

• After a user is authenticated through an external authentication service, a JWT is issued to them.

• This JWT, containing session variables like user ID and role, is passed to QueryDeck in the specified header (usually Authorization).

• QueryDeck verifies the JWT using the provided public key and extracts session variables based on the specified keys (User Session Key and Role Session Key).

• These variables are then used to enforce permissions based on the user’s role and specific data access rules defined at the table and column level.

This setup allows QueryDeck to securely authenticate users and control their access to data based on JWT claims, ensuring a robust, flexible authentication and authorization model.