Centralised Authentication — Architecture Documentation

1. Introduction and Goals

Business Context

The Centralised Authentication component provides the OAuth / OIDC server used by the Association Register. It issues OAuth client credentials for M2M flows and signs the VAD tokens that data providers validate locally. The 2026 architecture has a single shared authentication layer; there is no separate authentication service per CTN domain.

Primary Goals

• Unified authentication — one OAuth / OIDC server for all CTN participants and ASR-issued tokens.
• VAD token management — issuance and validation of VAD (Verifiable Association Data) tokens signed with the association’s private key.
• EU data compliance — full GDPR alignment; EU-resident infrastructure and key material.
• High availability — reliable authentication for critical trade operations.
• Standards compliance — OAuth 2.0 (client credentials), OpenID Connect, JWS RS256.

Quality Goals

• Security — robust signing, JWKS-based key distribution, HSM-backed private keys.
• Performance — <200ms token issuance, <100ms token validation.
• Reliability — 99.95% uptime.
• Compliance — EU data residency, GDPR.
• Scalability — thousands of concurrent authentication requests.

Stakeholders

• Participants — organisations consuming or providing data.
• Association administrators — managing onboarding and OAuth client lifecycle.
• Data providers — validating VAD tokens before releasing data.
• EU regulatory bodies — ensuring compliance with data-protection regulations.

2. Architecture Constraints

Technical

• OAuth 2.0 — full client-credentials support; OIDC where human authentication is involved.
• EU data residency — all authentication data inside EU jurisdiction.
• JWS — JWT signing with RS256 minimum.
• High availability — multi-region deployment within the EU.

Regulatory

• GDPR — data protection.
• eIDAS — compatible with eHerkenning for authorised-representative login.
• Audit — complete audit trail.

Integration

• Single OAuth server — serves the entire CTN ASR estate; no per-domain split.
• Webhook support — events for OAuth-client lifecycle.

3. System Scope and Context

Technical Context

• Upstream: KvK, KBO, VIES, GLEIF, eHerkenning.
• Downstream: the Association Register and every data provider that validates VAD tokens.
• Integration points: JWKS endpoint, OAuth APIs, webhook receivers, audit pipeline.

4. Solution Strategy

Key Decisions

• Self-hosted OAuth server — Keycloak is the chosen IdP (see ADR-00002).
• EU-first design — all services and data storage within EU boundaries.
• Standards-based integration — OAuth 2.0, OpenID Connect, JWS RS256.

Technology choice

Keycloak (self-hosted) is the chosen IdP — see ADR-00002. The detailed M2M integration is described in Keycloak M2M Authentication; per-participant federation (Entra ID, eHerkenning, local) is decided in ADR-00008.

Key material lives in an HSM-backed key vault (e.g. Azure Key Vault Managed HSM, AWS KMS Managed HSM, or HashiCorp Vault).

5. Building Block View

Core Components

• OAuth provider — authentication and authorisation server.
• VAD token service — generates VAD tokens with participation claims.
• Key management — cryptographic key storage and rotation.
• Admin interface — administration of users and OAuth clients.
• JWKS endpoint — public-key discovery for token validation.

Integration Components

• API gateway — rate limiting, monitoring, API management.
• Webhook service — events for OAuth-client lifecycle.
• Audit service — logging for compliance and security monitoring.
• Identity federation — integration with eHerkenning and eIDAS.

Security Components

• Certificate management — X.509 lifecycle.
• MFA — for administrative access.
• Rate limiting — protection against authentication attacks.
• Anomaly detection — suspicious authentication patterns.

6. Runtime View

VAD Issuance (M2M, client credentials)

Consumer → OAuth server: POST /oauth/v2/token (client_credentials)
OAuth server → Key management: retrieve signing key
OAuth server → VAD token service: generate VAD with participation claims
VAD token service → OAuth server: signed VAD (JWS RS256)
OAuth server → Consumer: access_token (VAD)
OAuth server → Audit service: log issuance

VAD Validation (at the data provider)

Provider → JWKS endpoint: GET /.well-known/jwks (cached)
JWKS endpoint → Provider: public keys
Provider → Provider: verify signature, claims, expiry
Provider → Audit service: log validation result

Token Format Example

VAD Token Structure

{
  "iss": "https://association.ctn.network",
  "sub": "participant-organisation-id",
  "aud": "https://ctn.network",
  "iat": 1754764800,
  "exp": 1754851200,
  "token_type": "VAD",
  "participation_status": "active",
  "compliance_verified": true,
  "https://schemas.ctn.network/claims/legal_entity/name": "Transport Company BV",
  "https://schemas.ctn.network/claims/legal_entity/registry/kvk": "12345678"
}

Token validation checklist (data service provider)

A provider validates every incoming VAD/access token in this order; reject on the first failure:

1. Signature — valid against the ASR’s JWKS public keys → 401 on failure.
2. Expiry — exp is in the future (allow ~30s clock skew) → 401.
3. Issuer — iss equals the expected ASR issuer → 401.
4. Audience — aud contains the provider’s own client ID → 403. Critical: without this check, a token minted for another API would be accepted here.
5. Organisation — read the participant identity from the token for local business rules.

Operational rules: cache JWKS and refresh on an unknown kid; reject alg: none; never log raw tokens (log the jti for traceability).

Integration Patterns

• OAuth 2.0 client-credentials flow — M2M.
• JWT bearer pattern — stateless authentication with cryptographic verification.
• JWKS discovery — automated public-key distribution.
• Webhook notifications — event-driven updates for OAuth-client lifecycle.

7. Deployment View

EU Deployment

• Primary region: EU-West (Frankfurt or Amsterdam).
• Secondary region: EU-Central (Dublin or Paris) for disaster recovery.
• Data residency: all authentication data inside EU boundaries.

Scaling Strategy

• Horizontal scaling — multiple OAuth server instances behind a load balancer.
• Database scaling — read replicas for token validation, master for token issuance.
• Caching — JWKS cache at the consumer and provider edge.

8. Cross-cutting Concepts

Security Patterns

• Zero Trust — every request authenticated; no implicit trust.
• Defence in depth — multiple security layers.
• Principle of least privilege.
• Continuous monitoring.

EU Compliance

• GDPR-compliant data processing.
• Data portability.
• Right to be forgotten.
• Consent management.

Token Lifecycle (simplified example)

const generateVad = async (claims, audience) => {
  const token = await tokenService.create({
    type: 'VAD',
    claims: validateClaims(claims),
    audience: audience,
    expirySeconds: 86400,
    signingKey: await keyManager.getCurrentKey(),
  });
  await auditService.logTokenGeneration(token, claims);
  return token;
};

Error Handling

• Graceful degradation if a component fails.
• Circuit breaker for downstream calls.
• Audit preservation for all errors.
• User-facing error messages without exposing system internals.

10. Quality Requirements

Performance

• VAD issuance <200ms.
• Token validation <100ms.
• 10,000+ token operations per minute supported.
• JWKS endpoint <50ms.

Security

• RSA-2048 (or stronger) signing.
• Automated key rotation every 90 days.
• 100% of authentication events logged.
• <4h response time for security incidents.

Compliance

• GDPR-compliant.
• 100% authentication data in the EU.
• Minimum 7 years audit retention.
• SOC 2 Type II (or equivalent) target.

Availability

• 99.95% uptime.
• RTO 15 minutes, RPO 1 minute.
• Multi-region failover within 15 minutes.
• 24/7 monitoring with automated alerting.

11. Risks and Technical Debt

Current Risks

• Vendor lock-in — mitigated by Keycloak’s open-source status and the standard OAuth/OIDC protocols (other compliant IdPs could replace it if ever needed).
• Regulatory change — privacy and identity rules evolve; design assumes regular review.
• Single point of failure — the OAuth server is central by design; multi-region failover mitigates this.
• Non-EU participants — handle case by case.

Technical Debt

• Token versioning — no formal versioning strategy yet (see risks register, TD-2).
• Provider migration playbook — to be documented.
• Compliance automation — some controls are still manual.

Future Improvements

• Multi-provider support for resilience.
• AI-powered anomaly detection.
• Full eIDAS-2 wallet integration.
• Quantum-safe cryptography readiness.

---

This document is part of the 2026 CTN scope. Components related to dossier-bound authorisation (the Orchestration Register and dual-token validation) are out of scope for 2026 — see the Roadmap.