Skip to content

ADR-012 — Authentication, Authorization and Identity Baseline

Status: ACCEPTED — I1-B4 Technology Decision Gate
Accepted: 2026-09-21

Context

Touriffique has global authenticated people, multi-tenant memberships, tenant-scoped Customers, separately privileged platform staff, Custom/headless machine clients and guest conversion flows.

Making the Identity Provider authoritative for tenant membership or embedding the full authorization model in tokens would conflict with the frozen Tenant and permission model.

Decision

Identity Provider

Use Keycloak 26.x for human authentication and identity brokering.

Use one human-identity realm per environment, not one realm per Tenant.

Keycloak persistence is separate from Touriffique application schemas/migrations.

Interactive protocol

Use OIDC Authorization Code + PKCE S256.

Do not use Direct Grant/Resource Owner Password Credentials or implicit browser flow.

Application identity

Map external authentication to a global Touriffique User using OIDC issuer + subject.

Email address is not the primary identity key.

Customer boundary

Tenant CRM Customer remains separate from global User.

A verified CustomerAccountLink may associate a User with a Tenant's Customer.

Email equality alone cannot create or merge that association.

Authorization

Touriffique owns:

  • TenantMembership;
  • Platform Staff assignments;
  • roles;
  • permissions;
  • Tenant/Business Unit/Site/Location scopes;
  • entitlements;
  • domain authorization policy.

Roles are permission bundles.

The initial grant model is allow-only/default-deny.

Platform staff authority is separate from tenant membership.

MFA

MFA is mandatory for every platform and tenant staff account.

Customer MFA is optional initially.

Passkeys/WebAuthn are preferred, TOTP is an accepted fallback, and recovery codes are supported.

Browser credentials

Durable refresh/session credentials must not be stored in JavaScript-readable browser persistence.

Exact BFF/server-session implementation is deferred to I1-B6.

Machine identities

Trusted server-to-server clients use OAuth 2.0 Client Credentials with application-owned scope metadata.

Provider webhooks retain provider-specific verification.

Invitations and impersonation

Membership invitations are one-time, short-lived, verified and auditable.

Support impersonation uses an explicit temporary delegated context and preserves both real actor and effective subject in audit data. Target user credentials/sessions are never borrowed.

Consequences

  • Keycloak can be upgraded/replaced without redefining TenantMembership semantics;
  • role revocations and entitlement changes are not trapped inside stale identity-provider token claims;
  • one human can interact with several Tenants without realm proliferation;
  • tenant Customers remain isolated even when linked to one global authenticated User;
  • staff accounts have a stronger authentication baseline than ordinary customers;
  • authorization becomes a testable application policy layer rather than a collection of role-name conditionals.