Skip to content

Latest commit

 

History

History
98 lines (71 loc) · 4.53 KB

tenants.md

File metadata and controls

98 lines (71 loc) · 4.53 KB
title Tenant Isolation Reference
description Claims, org map, what is filtered vs forwarded, and zelkor token mint fields.
type reference
sidebar_group Reference
sidebar_order 60
audience human
edition all

Tenant Isolation Reference

This page documents how tenant identity is configured, mapped, and enforced across Zelkor.

JWT Configuration

Identity comes from a verified JWT. The platform validates the token and maps it to a tenant ID. There is no default tenant — if the claim is missing or validation fails, the request is rejected immediately.

Configuration in values.yaml:

platform:
  tenants:
    jwt:
      issuer: "https://your-idp.example.com"
      audiences:
        - "zelkor-platform"
      remoteJwksUri: "https://your-idp.example.com/.well-known/jwks.json"
      jwksEgressCIDRs:
        - "203.0.113.0/24"
      tenantClaims:
        - "tenant_id"
        - "org_id"
        - "sub"

    # Optional mapping from IDP org names to internal tenant IDs
    orgMappings:
      "idp-org-uuid-1": "tenant-a"
      "idp-org-uuid-2": "tenant-b"

issuer must equal the JWT iss claim. remoteJwksUri must be the HTTPS JWKS URL the IdP publishes. When NetworkPolicies are on, set jwksEgressCIDRs to the IdP CIDRs (TCP 443). Do not set issuer or remoteJwksUri to an in-cluster Service URL that only answers with a public Host header. For those IdPs, put the keys in a ConfigMap (--jwks-file / jwksConfigMap). See JWT rejected (401).

IDM Integration Options

Zelkor uses standard JWKS (JSON Web Key Set) validation. It integrates with any Identity Management (IDM) system that issues signed JWTs:

  • Okta / Auth0: Set issuer and remoteJwksUri to your authorization server's endpoints (e.g. .well-known/jwks.json). Use a custom claim (e.g., org_id) in tenantClaims.
  • Microsoft Entra ID (Azure AD): Use the v2.0 endpoint for issuer and remoteJwksUri. The tenantClaims is typically tid (tenant ID) or a mapped app role.
  • Keycloak: Point remoteJwksUri to the realm's certs endpoint (/realms/<realm>/protocol/openid-connect/certs).
  • Custom IDP: Serve a static JWKS endpoint. If your IDP issues opaque UUIDs but your agent expects readable names, use orgMappings to translate them (e.g., b2f4...: tenant-a).

Tool Filtering vs. Forwarding

The platform enforces tenant isolation differently depending on the tool backend.

Native MCP Servers

Native servers apply strict filters based on the tenant ID. The agent cannot bypass these.

  • Postgres: Each call runs in a transaction that sets app.current_tenant to the verified tenant. The server does not rewrite the SQL. Row-level security applies only when your policies read app.current_tenant (including composite <dept>:<user> values via split_part; see Department and User Boundaries Across Databases).
  • Qdrant: Search and scroll add a payload filter tenant_id equal to the verified tenant. Upsert stamps that field and ignores a tenant id supplied by the caller.

Extra MCP Backends

For backends registered via workspace.tools, Zelkor forwards the tenant identity but does not natively filter the data (as it does not control the external SaaS).

The identity is forwarded as an HTTP header (e.g., X-Tenant-ID) to the extra backend. The external backend is responsible for enforcing its own isolation.

zelkor token mint & localSigning

For local development, testing, or fully air-gapped deployments without an IdP, you can enable Zelkor's native localSigning fallback feature. This allows the platform to act as its own signer.

Configuration in values.yaml for a single-tenant isolated environment:

platform:
  tenants:
    jwt:
      localSigning:
        enabled: true
        # Automatically generate a token for this tenant during install.
        # For a static-key experience in an isolated environment, set a long TTL.
        seedTenant: "tenant-a"
        seedTokenTTL: "8760h" # 1 year

When enabled (which is the default in profiles/values-local.yaml used by the quickstart script), you can also mint valid JWTs using the CLI:

# Mint a token for a specific tenant
zelkor token mint --release zelkor-platform --tenant "tenant-a"

# Mint a token with a specific time-to-live (default 1h)
zelkor token mint --release zelkor-platform --tenant "tenant-b" --ttl "24h"

The resulting token can be passed in the Authorization: Bearer <token> header to the AI Gateway or agent endpoints.