Overview

AGILITY Multi-Tenancy allows multiple teams to work within a single AGILITY deployment while keeping their data fully isolated. Each tenant acts as a dedicated workspace—typically representing a team, project, or organization—ensuring that users only access the analyses and intent-based evaluations relevant to their current context.

This structure enables secure collaboration across teams without data overlap, while preserving a focused and personalized experience for each user.

Key Benefits

• Team-specific visibility: Each team works within its own workspace, with dashboards and insights tailored to its data and activities.

• Strict data isolation: Analyses, evaluations, and feedback are fully separated between tenants, ensuring no cross-team data exposure.

• Scalable collaboration: Multiple teams can operate independently within the same platform without impacting each other’s workflows.

In this page, you will learn:

• Core concepts of Multi-Tenancy

• Keycloak Setup: Groups & User Assignment

• Enabling Multi-Tenancy in AGILITY

• Tenant management (Admin only)

• Tenant selection & switching (All users)

• Scoped Features

• Operating Modes

• Troubleshooting

Core concepts of Multi-Tenancy

This section introduces the key concepts and terminology used in AGILITY Multi-Tenancy. It provides a glossary of the main terms, along with clear definitions, to help you understand how tenants, users, and data are structured and interact within the platform.

Use this section as a reference to familiarize yourself with the foundational concepts before configuring or using Multi-Tenancy features.

How Tenant Access Works

A user can access a tenant if any of the following conditions are met:

• Keycloak group match
  The user belongs to at least one Keycloak group (as defined by the JWT groups claim) that is mapped to the tenant. This is the primary access mechanism.

• Admin user
  Admin users automatically have access to all tenants.

There is no separate membership management. Access to a tenant is determined entirely by matching the user’s Keycloak groups with the group mappings configured for each tenant.

How Tenant Context Flows Through the System

When Multi-Tenancy is enabled, the following flow applies:

1. User authentication
   The user logs in via Keycloak. The JWT token includes a groups claim (e.g., ["group-a", "agility-admin"]).

2. Group propagation
   AGILITY proxy extracts the group's claim and forwards it to the backend through the X-Groups HTTP header.

3. Tenant selection
   The UI stores the selected tenant ID in a cookie (tenant_id) and in the user’s backend settings.

4. Request handling
   For each API request, the UI sends both X-Tenant-Id (from the cookie) and X-Groups (from the JWT) to the backend.

5. Access validation
   The backend validates whether the user has access to the requested tenant based on their groups.

   1. If access is denied → 403 Forbidden

   2. If X-Tenant-Id is missing → 400 Bad Request

6. Data scoping
   Once validated, the tenant_id is used to filter all data queries. Data from the default tenant (tenant-default) is always included alongside the active tenant’s data.

Keycloak Setup: Groups & User Assignment

Before enabling Multi-Tenancy, ensure the following requirements are met:

• Keycloak configuration: A Keycloak instance is set up with an AGILITY realm already configured.

• Admin access
  You have administrative access to the Keycloak Administration Console.

• Groups claim extraction
  OAuth2-Proxy is configured to extract the groups claim from JWT tokens. This is included by default in standard AGILITY deployments: oauth2_proxy.cfg → oidc_groups_claim = "groups"

• Header forwarding
  The NGINX reverse proxy is configured to forward the X-Groups header to the backend on every authenticated request.

Creating Tenant Groups in Keycloak

For each AGILITY tenant, you must create a corresponding Keycloak group. This group will later be mapped to the tenant in AGILITY (see Section: Create a New Tenant -> Keycloak Groups Mapping).

You can use any naming convention, but a common and recommended pattern is:
tenant-{name} (e.g., tenant-a, tenant-b).

Steps

1. Log in to the Keycloak Administration Console.

2. Select the AGILITY realm from the top-left dropdown.

3. Navigate to Manage → Groups.

4. Click Create group.

5. Enter the group name (e.g., tenant-a) and click Create.

6. Repeat these steps for each tenant you plan to create in AGILITY.

Admin Access

If certain users need both admin privileges and tenant access:

• Assign them to the agility-admin group

• And to the relevant tenant-* group(s)

Admin users automatically have access to all tenants. However, the agility-admin group is still required to grant administrative permissions (e.g., managing settings and configurations).

Assigning Users to Tenant Groups

Once the groups are created, you can assign users to the appropriate tenant groups:

Steps

1. In the Keycloak Administration Console, navigate to Manage → Users.

2. Search for and select the user you want to assign.

3. Open the Groups tab.

4. Click Join Group.

5. Select the desired tenant group (e.g., tenant-a) and click Join.

The user is now a member of that group. On their next login, their JWT token will include the assigned group(s) in the groups claim.

Repeat these steps for all users and tenant groups as needed.

Multi-Tenant Access

A user can belong to multiple tenant groups (e.g., tenant-b and tenant-c). When logging in to AGILITY, they will be prompted to select which tenant they want to work in.

Verifying the Group's Claim in the JWT

After assigning users to groups, verify that the JWT token includes the groups claim:

Steps

1. Log in to AGILITY as the user.

2. Inspect the JWT access token (e.g., using browser developer tools → Application → Cookies, or via a tool like http://jwt.io ).

3. Check that the token payload includes the expected groups, for example:

If the group's claim is missing

• Ensure the user is correctly assigned to the required Keycloak groups

• Verify that the client scope includes a group's claim mapper

Enabling Multi-Tenancy in AGILITY

Multi-Tenancy is controlled by a feature flag (MULTI_TENANCY_ENABLED). It must be enabled before any tenant-related features become available.

Steps

1. Navigate to Settings → Application page.

   Open

   

2. Click on the Edit button to open the Feature Enablement section.

   Open

   

3. Locate Multi-Tenancy Feature Enabled (MULTI_TENANCY_ENABLED).

4. Click the Edit (pencil) icon to unlock the field.

   Open

   

5. Set the value to True.

   Open

   

6. Click Save to apply or click Cancel to discard the changes.

   Open

   

Once enabled, Multi-Tenancy features will become available across the platform.

What Happens After Enabling Multi-Tenancy

Once Multi-Tenancy is enabled:

• Tenant context is required
  The backend requires the X-Tenant-Id header on all tenant-scoped API requests.

  • If missing → 400 Bad Request

• Tenant access is resolved per user
  The /v1/tenants/available endpoint returns the list of tenants the user can access, based on their Keycloak groups.

• Admin management becomes available
  A Tenant Management card is added to the Application Settings page (visible to admin users only).

• UI updates reflect tenant context

  • A tenant badge appears in the header bar

  • A tenant selector dropdown is available in Webhook and Autoloader pipeline creation forms

• Tenant selection on login
  Users without an active tenant are redirected to a tenant selection page after logging in.

When Multi-Tenancy is Disabled

• The backend defaults to a single tenant (tenant-default) for all requests

• No tenant-related UI elements are displayed

Tenant Management (Admin)

Accessing Tenant Management

1. Navigate to Settings → Application.

   Open

   

2. Click the "Tenant Management" card (only visible when multi-tenancy is enabled).

   Open

   

3. You will see a table listing all existing tenants with columns: ID, Name, Description, and Keycloak Groups.

   Open

   

Creating a New Tenant

1. On the Tenant Management page, click the + New Tenant button.

   Open

   

2. Fill in the form:

3. Click "Save & Close” to create a tenant; the list will be automatically updated.

   Open

   

Editing a Tenant

1. On the Tenant Management page, click the Edit button next to the tenant.

   Open

   

2. Update the Tenant Name, Description, or Keycloak Groups Mapping as needed.

   Open

   

3. Click Save & Close to apply the changes.

   Open

   

Deleting a Tenant

1. On the Tenant Management page, click the Delete button next to the tenant.

   Open

   

2. A confirmation message will appear:
   “Tenant will be deleted, but internal data will remain in the system.”

3. Click Delete to confirm, or Cancel to abort.

4. The tenant list will be updated accordingly.

Tenant Selection & Switching (All Users)

Tenant Selection on Login

When Multi-Tenancy is enabled, and a user does not have an active tenant selected (no tenant_id cookie or default_tenant in settings), they are automatically redirected to the tenant selection page.

What you see

Open

• A modal that allows you to select a tenant based on your available group access

• A dropdown displaying all tenants you have access to (based on your Keycloak groups), including each tenant’s name and, when available, a short description

What to do

Open

• Select a tenant from the dropdown

• You will be automatically redirected to the AGILITY home page with the selected tenant active

Special cases

• Single-tenant users
  If you have access to only one tenant, it is automatically selected—no selection page is shown.

• Users with no tenant access
  If your Keycloak groups do not match any tenant mapping:

  • Admins see a message with a link to the Settings page to configure tenants

  • Non-admin users see: “Please contact your administrator to request access.”

• Admin users
  Admins bypass group checks and can access the Settings page even without a selected tenant, allowing them to create and configure tenants.

Switching Your Active Tenant

Steps

1. Click your profile icon (top-right corner of the header).

   Open

   

2. In the dropdown menu, click Tenancy option.

   Open

   

3. A list of your available tenants will be displayed:

   Open

   

   • Your current tenant is marked with a green checkmark

   • Each tenant shows its name and, if available, a description

4. Click on a different tenant to switch.

What happens next

• The page reloads with the newly selected tenant context

• A “Switching Tenant…” indicator appears briefly during the transition

• The selected tenant is saved to your user settings, and a tenant_id cookie is updated

Tenant Badge in the Header

When multi-tenancy is active, and you have a selected tenant:

• A tenant badge (pill-shaped label) appears in the top navigation bar, showing the current tenant name.

  Open

  

• Hovering over it shows a tooltip with the Tenant ID.
  
  

  Open

  

• The badge is visible only when two or more tenants are available to you.

Tenant-Scoped Features

Once a tenant is selected, all tenant-aware features automatically filter data based on the active tenant. Data from the default tenant (tenant-default) is always included alongside the active tenant’s data.

Analyses

• Creating an analysis (file upload)
  The analysis is automatically assigned to your active tenant.

• Listing analyses
  You will see analyses for your active tenant, along with those from the default tenant.

• Analysis details and summaries
  All views are scoped to the active tenant, including CubeJS-powered analytics data.

IBD Evaluations

• Creating an evaluation
  The evaluation and its underlying analysis are assigned to your active tenant.

• Listing evaluations
  The active tenant filters include default tenant data.

Webhooks

When creating or editing a webhook subscription, admins can assign it to a tenant:

1. Navigate to Settings → Application → Webhook Configuration
   
   

   Open

   

2. Click the + New Endpoint button at the top-right.

   Open

   

3. If Multi-Tenancy is enabled, a Tenant dropdown will appear

   Open

   

4. Select a tenant, and the created webhook will only receive events from this tenant

   Open

   

5. Complete the remaining fields (URL, events, notification type, etc.) and click on Cancel to discard changes, Save & New keeps your updates on the current page and opens a form to create another item, and Save & Close saves your changes and returns to the previous view.

   Open

   

Autoloader Pipelines

When creating or editing an autoloader pipeline, admins can assign it to a tenant:

1. Navigate to Settings → Application → Autoloader Configuration

   Open

   

2. Click the + New Pipeline button or edit an existing one