LIBRA - NGSI-LD API GATEWAY

NGSI-LD Context Brokers power smart cities, IoT platforms, and digital twins. Exposing them directly means you are on the hook for authentication, caching, rate limiting, resilience, and observability — all the things a production API needs. Brokers focus on data; they do not ship with a full gateway stack. Libra exists to provide that layer: one gateway that understands NGSI-LD and plugs into your existing Keycloak and NGSI-LD setup.  

• 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 NGSILD-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).

• Language: Rust
• Web framework: Axum
• Config format: TOML
• Auth: Keycloak JWKS
• Caching: Moka
• Rate limiting: Tower Governor
• Interfaces: CLI (libra ...)
• Observability: Prometheus (axum-prometheus), tracing

• standalone/self-hosted
• embedded in FIWAREBox
• managed as part of FIWAREBox (NGSI-LD Context DataHub)
  

TBD

IT personas: architects, platform engineers, DevOps, integrators, pilots/research  

Auriga, Lynx, Cassiopeia;  upstream brokers: Scorpio, Stellio, Orion-LD