ADR-00008: External IdP Federation Strategy

Approval Status

Status flow: Proposed → Accepted → Reviewed → Approved (or Rejected), or Not Required. A superseded ADR keeps its file; only its status changes to Superseded by NNNNN.

Governance body	Status	Last update
CTN Project Team	Approved	2026-05-29
CTN Technical Advisory Board	Approved	—
CTN Steering Committee	Pending	—
BDI Conformance Team	Proposed	—
BDI Framework Team	Pending	—

Context and Problem Statement

ADR-00003 split the data between two systems: Keycloak (the login system) holds everything about a user’s login, and the ASR (the Association Register, CTN’s own back-end service) is the authoritative record for participant data (the registered organisations). It also made Keycloak the place that tracks which users belong to which participant, using Keycloak’s built-in Organizations feature (version 26.6) — one Keycloak Organization per participant, which is also where each participant’s external login provider gets linked.

This ADR decides which external identity providers (IdPs) the ASR trusts for login, per type of participant, and how a user’s lifecycle (joining, leaving, being deactivated) flows through that setup. An identity provider is the system where a user actually authenticates — for example a company’s own Microsoft Entra ID, the Dutch eHerkenning scheme, or a plain email-and-password account in Keycloak itself.

Which kind of federation this ADR covers

The word “federation” is used for two different things in CTN. This ADR is only about the first:

1. ASR ↔ a participant’s own login system (this ADR): the ASR trusts each participant’s identity provider so the participant’s own people can sign in to the ASR portal.
2. ASR ↔ another ASR (out of scope here): two Association Registers trusting each other so their participants can interoperate — for example the planned link between Portbase and the upcoming Hinterland ASR. That is on the roadmap for the coming months and will get its own decision.

The driving concern: deprovisioning at the source

The core problem is deprovisioning — making sure that when someone leaves a participant organisation, they lose ASR access without CTN having to find out and act manually.

A worked example. A large participant runs its own company login system (some run Microsoft Entra ID; others run their own Keycloak). Their IT-admins already manage all internal accounts there, and a small number of those people also need access to the ASR portal to register endpoints.

• If the ASR kept its own copies of those accounts (the path the DIL prototype took, using Azure AD directly), then CTN would have to learn about and act on every personnel change at the participant.
• If instead the ASR federates login outward to the participant’s own login system, deprovisioning happens at the participant: the moment they disable someone’s account, that person can no longer authenticate at the source, so their ASR access falls away on its own.

Relationship to the earlier decision

This decision was first taken in the prior handover series as ADR-004 “Single IdP (Keycloak) — federatie naar Entra ID / eHerkenning / lokale account” (2026-05-06). This ADR promotes that decision into the official BDI ADR series and refines it against the Keycloak Organizations feature introduced in version 26.6.

Considered Options

Option 1: Single IdP with outward federation (chosen)

• Description: Keycloak is the only IdP that ASR talks to. Per participant, Keycloak federates outward to the identity source the participant brings:
  • Entra ID via OIDC federation, linked to the Keycloak Organization, for participants that have it (Contargo, deepsea carriers, terminal operators).
  • eHerkenning via SAML→OIDC for the NL admin-representation step.
  • Local Keycloak account (email + password + MFA) for participants without an own IdP.
  • Service accounts in Keycloak for machine-to-machine clients (TMS / ERP integrations).
• Pros:
  • Lifecycle at the source: Contargo deactivates an account in Entra → next ASR login fails, existing session expires at the configured TTL, no manual sync needed by ASR.
  • Heterogeneous participant base supported: large parties keep their own IAM; small parties (single-truck operators with no Microsoft stack) get a usable local account without being forced into a third-party tenant.
  • Complexity scales at Keycloak: federation lives in one place; downstream services see one OIDC issuer.
  • Audit clarity: Keycloak’s idp claim records the source (entra-id, eherkenning, local), giving us per-event provenance.
• Cons:
  • Per-participant federation setup: each large participant requires a one-off OIDC trust configuration in Keycloak. Self-service is feasible only for the local-account path.
  • No native push-deprovisioning: revocation is pull (next login fails) plus session TTL, not push (immediate kill). Aggressive session lifetimes mitigate but do not eliminate the gap.
  • JIT-provisioning policy is a real design question: who gets a Keycloak account on first Entra login — anyone with a valid Entra token, or only after a Contargo admin has invited them? See Open Questions.

Option 2: ASR holds its own user directory; sync from participant IdPs (SCIM)

• Description: ASR (via Keycloak) holds the canonical user records. Participant IdPs push lifecycle events via SCIM 2.0 (create / update / deactivate).
• Pros: Immediate deprovisioning (push). Standard protocol.
• Cons: Requires every participant to operate a SCIM connector — entirely unrealistic for the smaller participants. Asymmetric: works for some, not others. Doubles the directory state (drift risk). Rejected.

Option 3: Direct Entra ID as the primary IdP for all admin users

• Description: The DIL-prototype path. CTN’s own Entra tenant is the IdP for everyone with portal access; participants are invited as guest users.
• Pros: Simple from CTN’s side — one tenant to operate.
• Cons: Forces every participant into CTN’s tenant — including the small operators who don’t use Microsoft at all. Lifecycle ownership flips: CTN learns about Contargo personnel changes via invitation/guest management, not via Contargo’s own directory. Rejected for the same reasons noted in ADR-004.

Decision Outcome

Chosen option: Option 1 — single Keycloak IdP with outward federation per participant type.

Rationale

The three reasons that decided ADR-004 still hold and align cleanly with what Keycloak Organizations 26.6 now offers:

1. Lifecycle is owned where it can actually be observed. Contargo knows when a Contargo employee leaves; CTN doesn’t. Federating outward delegates that knowledge to the system that has it.
2. The participant base is heterogeneous. A solution that requires every participant to operate an IdP excludes the small operators; a solution that puts everyone in CTN’s tenant excludes the operators who don’t use Microsoft. Per-participant IdP choice is the only fit.
3. Federation matrix complexity belongs in Keycloak, not in middleware. Quarkus services in ASR see one OIDC issuer regardless of how many participant IdPs are linked. This is exactly what Keycloak Organizations’ per-org IdP linking is designed for.

Federation Matrix

Participant type	Login source	Trust mechanism	Lifecycle ownership
Large party with Entra ID (e.g. Contargo, deepsea carriers, terminal operators)	Participant’s Entra ID tenant, linked to the Keycloak Organization	OIDC federation	Participant’s Entra
NL admin-representation step	eHerkenning (Digidentity, ConnectIS, etc.)	SAML federation via OIDC bridge	Broker (eH provider)
Small party without an own IdP	Local Keycloak account (email + password + MFA)	Direct in realm	ASR / participant admin
Machine (TMS / ERP)	Service account in Keycloak, scoped to the participant	OAuth2 client-credentials	ASR (rotation policy)

Mapping to Keycloak Organizations

• Each ASR participant has a corresponding Keycloak Organization (per ADR-00003).
• For Entra-federated participants, the participant’s Entra ID tenant is linked as an IdP to that Keycloak Organization.
• First-login mapping uses Organization Group mappers:
  • Hardcoded Group mapper for the simple case (“everyone arriving via this IdP joins /member”).
  • Advanced Claim to Group mapper when the participant’s Entra exposes a role/group claim that distinguishes who gets /admin vs /member.
• The Keycloak idp claim is preserved through to the access token and logged for audit.

Consequences

• Positive:
  • Deprovisioning at the Entra source: a deactivated Contargo employee cannot obtain a new ASR session and existing sessions die at TTL.
  • Downstream services see a single OIDC issuer; no per-IdP code paths in Quarkus services.
  • Audit trail records the source IdP per event.
  • Participant-specific identity policy (MFA rules, conditional access) is enforced at the source, not duplicated in Keycloak.
• Negative:
  • Onboarding a large participant includes a one-time OIDC trust configuration between Keycloak and the participant’s Entra tenant — not self-service.
  • Revocation latency is bounded by access-token TTL plus refresh-token policy. Requires us to choose conservative lifetimes for the federated paths (see Open Questions).
  • JIT provisioning rules must be explicit per participant — open SSO from a participant’s entire Entra tenant is not the same as ASR access.
• Neutral:
  • For local-account participants, all the identity-side mutations from ADR-00007 apply unchanged. For Entra-federated participants, most of those mutations are not ASR’s concern — refining this is a follow-up to ADR-00007.

Open Questions

1. JIT-provisioning policy. On first federated login from a participant’s Entra: do we create the Keycloak user automatically (open trust), or do we require a prior invitation from a participant admin (closed trust)? Closed is safer; open is operationally cheaper. Likely closed by default with an opt-in per participant.
2. Session and token lifetimes for federated users. Short access-token TTL bounds revocation latency but increases load. Proposal: access-token TTL on the order of minutes for federated users; refresh-token TTL bounded by the federated session.
3. Back-channel logout / session revocation. Does Keycloak’s OIDC back-channel logout suffice, or do we additionally poll the source IdP? Depends on what the participant’s Entra emits.
4. Group/claim mapping per participant. Which Entra claim, group, or app role do we map to ASR’s /admin vs /member? Each large participant will negotiate this individually.
5. Multi-Entra-tenant edge cases. A person who works at two participants that both federate Entra: do they end up as one Keycloak user with two organization memberships, or two separate Keycloak users? Likely one user keyed on a stable cross-tenant identifier (email is not safe; OIDC sub is per-IdP).
6. Audit retention for deactivated source identities. When the source IdP no longer recognises a user, can we still resolve historical audit entries to a person? Need to capture enough identity context at session time to keep audit interpretable.

Implementation Plan

1. Phase 1: Configure a reference Entra ID federation in a non-production Keycloak realm using a willing pilot participant (Contargo if available). Validate the deprovisioning behaviour end-to-end: deactivate a test account, confirm session timeout, confirm refresh-token revocation.
2. Phase 2: Resolve the open questions on JIT-provisioning policy and token lifetimes; document as an extension to this ADR.
3. Phase 3: Define the operational runbook for onboarding a new federated participant (information needed from the participant, Keycloak configuration steps, claim mapping negotiation).
4. Phase 4: Extend ADR-00007 to differentiate identity-side mutation paths per participant type (Entra-federated vs local).

Compliance and Validation

• Security review completed (focus: session revocation, JIT-provisioning trust boundary, multi-tenant user identification)
• Performance impact assessed (token TTL, federation latency)
• Integration impact evaluated (downstream services see only Keycloak as issuer)
• Documentation updated
• Stakeholder approval obtained

Related Documents

• 00002-define-a-preferred-stack.md
• 00003-separate-users-and-participants.md (Keycloak Organizations, per-participant IdP linking)
• 00006-token-claim-composition.md (the idp claim is part of what the token carries)
• 00007-identity-mutation-proxy.md (mutation paths differ per participant type — to be extended)
• Prior handover series, ADR-004 “Single IdP (Keycloak) — federatie naar Entra ID / eHerkenning / lokale account” (2026-05-06) — original source of this decision
• BDI Association Federation Using Keycloak (2026-01-29) — earlier ASR↔ASR federation work that listed Entra ID as a compatibility target
• ASR kickoff notes (2026-05-11)
• Keycloak blog, “Organization Groups” (2026-04-29): https://www.keycloak.org/2026/04/org-groups

Status History

Date	Status	Notes
2026-05-06	Accepted (prior handover, ADR-004)	Original decision in handover series
2026-05-29	Proposed	Promoted into official BDI ADR series; refined against Keycloak Organizations 26.6