How It Works

This page describes the request flow, access control model, and architecture of Libra.

Request Flow

Client requests enter Libra and pass through layered middleware before reaching the Context Broker.

Global layers (all requests):

  • Request ID (UUID)

  • Trace logging (health probes muted)

  • CORS

  • Compression

  • Prometheus metrics

Protected path (/ngsi-ld/v1/*):

  • Smart cache (NGSI-LD aware)

  • Request deduplication

  • Helmet (security headers)

  • RFC 9457 error handler

  • Rate limiting (Governor)

  • Request buffer (backpressure)

  • Circuit breaker

  • Timeout

  • Payload limit

  • Header sanitization

  • Tenant policy

  • Keycloak auth (JWT validation)

  • RBAC (tenant permission check)

  • Audit log

  • Identity propagation (X-Auth-* headers)

Public path (/api/v1/*):

  • /health — Liveness probe

  • /ready — Readiness probe (checks JWKS and broker connectivity)

  • /info — Version, build, git metadata

  • /metrics — Prometheus metrics

After passing through the stack, validated requests are proxied to the upstream Context Broker with identity headers injected.

Access Control Model

Method to Permission Mapping

| HTTP Method | Required Permission | GET, HEAD, OPTIONS | read | POST, PUT, PATCH, DELETE | write | POST /entityOperations/query | read (exception) | TRACE | blocked

Keycloak Role Format

Roles follow the format tenant:{tenant_name}:{permission}.

  • tenant:production:read — Read access to tenant production

  • tenant:*:admin — Admin access to all tenants

  • tenant::read — Read access to the default (unnamed) tenant

Permission Hierarchy

admin → write → read (higher levels satisfy lower requirements).

Missing Tenant Header Policies

  • require-header — Rejects requests without NGSILD-Tenant (401)

  • authenticate — Allows missing header but requires valid JWT

  • allow-public — Anonymous access when no tenant header; tenant requests always require auth

API Endpoints

| Route | Auth | Description | /ngsi-ld/v1/** | JWT + RBAC | Proxied to backend broker with full middleware stack | /api/v1/health | None | Liveness probe | /api/v1/ready | None | Readiness probe (checks JWKS and broker connectivity) | /api/v1/info | None | Build version, git commit, compile-time metadata | /api/v1/metrics | None | Prometheus metrics

All NGSI-LD v1.6+ API routes are proxied: entities (CRUD, batch operations), subscriptions, temporal queries, discovery, context sources, and advanced operations.

Identity Headers

When a request passes authentication, Libra injects these headers before proxying to the broker:

| Header | Source | Example | X-Auth-Subject | JWT sub (fallback: azp) | f47ac10b-58cc-4372-a567-0e02b2c3d479 | X-Auth-Username | JWT preferred_username | jdoe | X-Auth-Email | JWT email | jdoe@example.com | X-Auth-Tenants | Parsed tenant:*:* roles | production:write,staging:read | X-Auth-Groups | JWT groups | /tenants/production,/admins | X-Auth-Tenant-State | Resolved tenant | explicit:production or none | X-Auth-Machine | Service account detection | true (only set for service-account-* users)

Inputs and Outputs

Inputs:

  • Client HTTP requests to /ngsi-ld/v1/ (protected) or /api/v1/ (health, ready, info, metrics)

  • Configuration: TOML (libra.toml) or environment variables

  • Keycloak JWKS endpoint for JWT validation

Outputs:

  • Proxied requests to the upstream Context Broker with identity headers

  • Health, ready, info, and metrics responses for probes and observability

  • Structured audit logs and Prometheus metrics