Skip to Content
We are live but in Staging 🎉
Auth and Access

Authentication, Tenancy, and Access Control

Last validated: 2026-05-11

Control Plane Auth Model (VBase API)

The VBase proto defines per-method auth metadata via common.method_auth_info, including:

  • resource_type
  • optional resource_id_field or resource_org_field
  • required scopes

In production deployments, these checks are typically enforced by upstream gateway/auth middleware around VBase gRPC/HTTP exposure.

Representative scope examples:

  • Cluster APIs: CreateCluster, GetCluster, ScaleCluster, DeleteCluster
  • Database APIs: AllocateServerlessDatabase, DeleteServerlessDatabase
  • Service APIs: ListVBaseService, GetVBaseService, GetVBaseServiceAccess
  • Command API: RunVBaseCommand
  • Backup APIs: CreateBackup, ListBackups, RestoreBackup, DeleteBackup, and policy scopes

Data Plane Auth Model (vbase-proxy)

vbase-proxy performs request-time auth before forwarding to Milvus:

  1. Validate bearer token (when AUTH_REQUIRED=true)
  2. Resolve tenant from host and gRPC method context
  3. Validate endpoint ownership and organization match through VBaseAdminService/GetClusterTenants
  4. Map gRPC action to VBase scope via YAML mapping
  5. Run UMA authorization check for (token, resource, scopes)
  6. Rewrite upstream authorization to tenant Milvus credentials and forward

Tenant Identity Derivation

Proxy extracts tenant identifiers from host labels like:

  • vbase-ct-...
  • vbase-cts-...
  • vbase-dt-...
  • vbase-dts-...
  • vbase-db-...

The resulting tenant slug is used to derive resource identity and authorization context.

IAM Resource Registration

During service provisioning, VBase registers IAM permission resources with DRN-style identifiers:

  • drn:dodil:vbase:<service_id>

Scope bundles differ by resource kind:

  • Cluster resources receive broader cluster + collection + backup + operational scopes.
  • Database resources receive serverless/database-oriented subsets.

Scope Mapping (Proxy)

Proxy action-to-scope mapping is configured in:

  • dodil-vbase/proxy/docs/auth/milvus_scope_mapping.yaml

Behavior notes:

  • If action mapping has a scope, UMA is evaluated for that scope.
  • If action has vbase_scope: null, the proxy treats it as forbidden.
  • If action is unmapped, current logic may skip UMA for that action; treat this as a policy gap requiring explicit mapping hardening.

Header and Metadata Expectations

Incoming proxy requests

  • Authorization: Bearer <token> expected from caller (unless auth disabled)

Upstream Milvus forwarding

Proxy injects:

  • authorization metadata (tenant credential basic token form)
  • dbname metadata when database context is available

RunCommand metadata (VBaseService/RunCommand)

Server-side RunCommand expects:

  • authorization metadata (required)
  • optional db_name or dbname metadata

If db metadata is missing, VBase falls back to tenant access default database when available.

Production Guardrails

vbase-app and vbase-proxy enforce stricter validations in production mode, including:

  • mTLS requirements (server/proxy)
  • auth-required behavior
  • disallowing mock/stub toggles
  • backup feature requirements (proxy/server config paths)

Public/Bypass Endpoints

On proxy, these endpoints are intentionally available for operational checks:

  • /healthz
  • /admin/health
  • /metrics

Backup forwarding endpoints are also exposed on proxy:

  • /backup
  • /backup/*path

Common Failure Patterns

  • Token valid but org does not match endpoint owner -> permission denied.
  • Scope missing in mapping or denied in UMA -> permission denied.
  • Tenant host cannot be resolved/validated -> request rejected.
  • Missing authorization metadata on RunCommand -> unauthenticated error.
  • Disabled auth in dev with incomplete downstream assumptions -> inconsistent behavior.
OverviewVBase API Reference