Skip to content

Identity and Trust Set Up

Purpose

This section explains the identity, trust, and authorisation model used by the Federator. Before starting any Federator services, you must understand how trust is established and enforced between domains. This section describes the identity model used in the local demo deployment. You are not required to manually generate certificates.

Stage 2 - Identity and Trust

How to Complete This Stage

  • Understand how MTLS secures Producer–Consumer communication
  • Understand how certificates are configured in the demo
  • Understand the role of the Identity Provider
  • Understand how the Management-Node supplies authorisation
  • Understand how policy-driven filtering enforces minimum trust

No configuration changes are required in this stage. You will validate identity behaviour during Run & Validate.

2.1 The Federator trust model

The Federator enforces explicit, minimum-trust communication between domains. Understanding this model is essential before running any services, as misconfiguration results in complete communication failure rather than degraded operation. The Federator enforces explicit, minimum-trust communication between organisations.

Every interaction between a Federator Producer and a Federator Consumer requires:

  • Mutual authentication (MTLS)
  • Explicit authorisation
  • Policy-driven filtering
  • Controlled ingress

The trust relationship looks like this: Producer <---- MTLS + gRPC ----> Consumer

If identity or policy validation fails, no data is exchanged. Federation fails closed, not open.

2.2 Mutual TLS (MTLS)

Federator services communicate over gRPC secured by MTLS.

MTLS ensures:

  • The Consumer verifies the identity of the Producer
  • The Producer verifies the identity of the Consumer
  • Both trust the same certificate authority (CA)
  • Anonymous access is impossible

If certificates are invalid or misconfigured:

  • The gRPC handshake fails
  • No topics are exposed
  • No data is transferred

2.3 Certificate configuration (demo environment)

In the local demo environment:

  • Certificates are pre-generated
  • Trust chains are preconfigured
  • Docker Compose mounts certificates into the relevant containers

You are not required to manually generate keys or certificates for this guide. It is important to understand that:

  • Producers run with a server certificate
  • Consumers run with a client certificate
  • Both trust a common root CA
  • Certificate configuration is defined in the compose files and service configuration

If certificates configuration is incorrect:

  • MTLS handshake will fail
  • Consumers cannot authenticate
  • Federation does not begin

2.4 Identity Provider

The Identity Provider:

  • Issues short-lived tokens
  • Associates identity with roles
  • Supports policy enforcement

In the local demo environment:

  • The Identity Provider is available for local development
  • Tokens can be issued automatically as part of the configured flow
  • Federator runtime properties must still be configured correctly for token validation and TLS to succeed

In production:

  • Identity would be federated across organisations
  • Token issuance would align with organisational identity standards

2.5 JWT Validation in the Federator

Federator validates access tokens using the aud (audience) claim. The expected value is defined in configuration:

idp.client.id=<client_id>

For authentication to succeed:

  • The token must include the configured client ID in the aud claim
  • The token must be signed by a trusted Identity Provider
  • The token must not be expired

For example, if the Federator is configured with:

idp.client.id=FEDERATOR_HEG then the presented token must include FEDERATOR_HEG in its aud claim.

2.6 Keycloak default behaviour

In default Keycloak configurations:

  • aud is typically set to the service
  • azp contains the client ID
Guidance

Ensure the token audience aligns with idp.client.id before running the Federator.

See Troubleshooting for resolution options.

2.7 The role of the Management-Node

The Management-Node supplies:

  • Topic configuration
  • Role definitions
  • Authorisation rules
  • Filtering policies

Producers and Consumers retrieve configuration from the Management-Node during startup.

This ensures:

  • Topics are not exposed unless explicitly authorised
  • Consumers only see topics granted to their role
  • Policy rules are centrally controlled
  • No implicit topic discovery occurs

If Management-Node configuration is incorrect:

  • Topics may not register
  • Consumers may not see authorised topics
  • Federation may not begin

2.8 Authorisation model

Authorisation is explicit and configuration-driven.

Consumers can only:

  • Discover topics explicitly granted to them
  • Subscribe to authorised topics
  • Receive messages matching their permitted security labels

Producers:

  • Discover source Kafka topics
  • Apply authorisation rules
  • Expose only approved topics
  • Filter messages based on policy before release

There is no wildcard or implicit topic exposure.

2.9 Security label filtering

Federator Producers apply message-level filtering using Kafka headers.

Filtering is based on:

  • The securityLabel header
  • Consumer identity
  • Authorisation rules defined in configuration

Messages that do not match policy:

  • Are ignored
  • Do not cross the boundary
  • Remain inside the source domain

This enforces policy-driven data release.

2.10 Controlled ingress

Consumers write federated data only to: federated.<source-topic-name>

This ensures:

  • Clear separation between local and federated data
  • Explicit identification of cross-boundary traffic
  • Controlled ingress into the Consumer domain

Downstream IA Nodes consume federated topics like normal Kafka topics, but access control remains independent.

2.11 Replay Safety

Consumers use Redis to track offsets.

This ensures:

  • Deterministic consumption
  • No unintended replay after restart
  • No duplicate ingestion under normal restart conditions

Replay safety complements identity enforcement by ensuring data handling remains predictable and auditable.

2.12 Runtime Validation (Preview)

Identity enforcement is validated during Run & Validate.

At runtime, Producer logs should show:

  • gRPC server initialised
  • TLS configuration loaded
  • Certificates successfully bound

Consumer logs should show:

  • Successful MTLS handshake
  • Authentication completed
  • Authorised topics discovered

If identity fails:

  • Certificate validation error
  • Handshake fails
  • Hostname verification issue
  • No federation occurs

2.13 Minimum-Trust Guarantees

The Federator enforces:

  1. Mutual authentication
    Producer and Consumer verify each other using MTLS.

  2. Explicit authorisation
    Topics are granted via configuration, not discovered implicitly.

  3. Policy-driven message release
    Messages are filtered before crossing the boundary.

  4. Controlled ingress
    Data enters only through federated.* topics.

  5. Replay safety
    Redis-tracked offsets ensure deterministic behaviour.

This aligns with NDTP N2 participation requirements.

Checkpoint

At this stage, you should understand:

  • How MTLS establishes Producer–Consumer trust
  • How certificates are configured in the demo environment
  • The role of the Identity Provider
  • How the Management-Node enforces authorisation
  • How filtering prevents unauthorised data release
  • Why the Federator fails closed under misconfiguration

You are now ready to build the Federator components.