Libra

Libra is an authentication and authorization reverse proxy for NGSI-LD Context Brokers. It sits between clients and the broker, validates JWT tokens against Keycloak, enforces tenant-scoped RBAC, and propagates verified identity to the backend.

Overview

NGSI-LD Context Brokers power smart cities, IoT platforms, and digital twins. Exposing them directly means you must implement authentication, caching, rate limiting, resilience, and observability—everything a production API needs. Brokers focus on data; they do not ship with a full gateway stack. Libra provides that layer: one gateway that understands NGSI-LD and plugs into your existing Keycloak and broker setup.

Libra works with Scorpio, Stellio, and Orion-LD. It is written in Rust with Axum and designed for containerized deployments.

Key Features

  • JWT authentication — Validates Bearer tokens against Keycloak JWKS with automatic key rotation and clock skew tolerance

  • Tenant-scoped RBAC — Role format tenant:{name}:{permission} with hierarchy admin > write > read and wildcard support

  • Identity propagation — Injects X-Auth-Subject, X-Auth-Username, X-Auth-Email, X-Auth-Tenants, X-Auth-Groups, X-Auth-Machine headers

  • Smart response cache — NGSI-LD aware caching with content-type keying, query normalization, per-resource TTL, and generational invalidation on mutations

  • Request deduplication — Single-flight pattern so 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 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 code

  • Prometheus metrics — HTTP request metrics at configurable endpoint, excludes health probes

Architecture Highlights

  • Reverse proxy — Sits between clients and the Context Broker; does not store or transform data

  • Layered middleware — Request ID, CORS, compression, caching, rate limiting, circuit breaker, auth, RBAC, audit

  • Multi-tenant isolation — Enforces NGSILD-Tenant header policies: require-header, authenticate, or allow-public

  • Compression — gzip, brotli, deflate, zstd (compile-time feature flags)

  • Payload limits — Configurable max request body size, rejects with 413 Payload Too Large

Use Cases

  • Platform engineers — Expose NGSI-LD brokers in production without building auth, resilience, and observability from scratch

  • Architects — Integrate Context Brokers with existing Keycloak and infrastructure

  • Integrators — Add a production-ready access layer to Scorpio, Stellio, or Orion-LD deployments

Next Steps

  • How It Works — Architecture, access control, and request flow

  • Roadmap — Planned features and improvements for v2.0