LIBRA

• Validates JWT Bearer tokens against Keycloak JWKS with automatic key rotation and clock skew tolerance.
• Enforces tenant-scoped RBAC: role format tenant:{name}:{permission} with hierarchy admin > write > read and wildcard (*) support.
• Propagates identity via X-Auth-Subject, X-Auth-Username, X-Auth-Email, X-Auth-Tenants, X-Auth-Groups, X-Auth-Machine headers.
• NGSI-LD–aware smart cache: content-type keying, query normalization, per-resource TTL, generational invalidation on mutations.
• Request deduplication: single-flight pattern — concurrent identical GET/HEAD requests share one backend call.
• Circuit breaker: opens on repeated backend failures, auto-recovers with backoff, returns 503 while open.
• Rate limiting: token bucket (Governor) with IP extraction, configurable burst size and refill interval.
• Security headers: Helmet middleware (CSP, HSTS, X-Frame-Options, X-Content-Type-Options).
• RFC 9457 errors: all proxy errors as application/problem+json with LIBRA-namespaced type URIs.
• Audit logging: structured logs per request (tenant, user identity, method, path, status).
• Compression: gzip, brotli, deflate, zstd (compile-time feature flags).
• Prometheus metrics: HTTP request metrics at configurable endpoint, excludes health probes.
• CORS: permissive, custom (explicit origins/methods/headers), or disabled.
• Payload limits: configurable max request body size, rejects with 413 Payload Too Large.
• Multi-tenant policies: require-header, authenticate, or allow-public for NGSI-LD-Tenant handling.

• Not a Context Broker - it proxies requests to one (Scorpio, Stellio, Orion-LD).
• Not an identity provider - it validates tokens from Keycloak; user management lives there
• Not a data transformation engine - it passes NGSI-LD traffic through; mapping/ETL belongs to CASSIOPEIA.
• Not a full API management platform - no developer portal, API keys, or usage billing; focused on auth + resilience

• Not a UI-first product - usage is documented mainly via CLI + config files

• 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.
• Processing
• • Global layers: request ID, trace logging, CORS, compression, Prometheus metrics.
  • Protected path: smart cache, request deduplication, Helmet, RFC 9457 error handler, rate limiting, circuit breaker, timeout, payload limit, header sanitization, tenant policy, Keycloak auth, RBAC, audit log, identity propagation.
  • Validates JWT, checks tenant permission against Keycloak roles, injects X-Auth-* headers.
• Outputs
• • Proxied requests to the upstream Context Broker with identity headers.
  • Health/ready/info/metrics responses for Kubernetes probes and observability.
  • Structured audit logs and Prometheus metrics.

LIBRA sits between clients and your NGSI-LD Context Broker:

• Upstream Clients (applications, dashboards, services) sending NGSI-LD requests.
• LIBRA JWT validation, RBAC, caching, circuit breaker, rate limiting, identity propagation.
• Downstream NGSI-LD Context Broker (Scorpio, Stellio, Orion-LD).