# CIAM Solution Design: [Product or brand name]

> Solution design for customer identity and access management (CIAM): personas and journeys, registration and
> identity proofing, passkey-first authentication, social login, step-up, account recovery, consent and preferences,
> profile store, business-to-business-to-consumer (B2B2C) organisations and delegated administration, fraud and bot
> defence, privacy and data residency, scale, metrics and migration. Assurance levels follow NIST SP 800-63-4 (final,
> July 2025). Protocols follow OpenID Connect Core 1.0, the OAuth 2.0 Security Best Current Practice (RFC 9700) and,
> for financial-grade APIs, the FAPI 2.0 Security Profile (Final, February 2025). Passkeys follow W3C Web
> Authentication Level 3. Privacy references cite the EU GDPR by article. Replace every `[bracketed]` value and every
> row marked *Example*. This is a documentation format, not legal advice.

<!--
Guidance: How to use this template
- Write one design per customer identity platform (one brand or a family of brands sharing accounts). Workforce identity belongs in IAM Solution Design (`security/iam-solution-design`).
- Start with personas and journeys (section 2) and the risk per journey (section 3). CIAM is a product: conversion and abandonment matter as much as security, so every control needs a user-experience cost next to it.
- Build or buy is decided in section 14; write sections 2 to 13 as capabilities first so the evaluation has criteria.
- Cross-reference instead of repeating: Identity provider system design (`system-design/design-identity-sso-provider`) for the internals of an IdP you build, Fraud detection design (`system-design/design-fraud-detection`), Open Banking API Design (`industry/open-banking-api-design`) where FAPI applies, DPIA (`compliance/dpia`), Data Residency and Sovereignty Assessment (`compliance/data-residency-sovereignty-assessment`), Privacy threat model (`security/privacy-threat-model`).
- Pitfall: a strong sign-in undone by a weak recovery path. Attackers take over customer accounts through recovery, SIM swap and support agents far more often than by breaking passkeys.
-->

## Document control

<!-- Guidance: Identify the product, brands and regions served and who owns the design. A change of identity platform, assurance level or data residency region is a new major version. -->

| Field | Value |
|---|---|
| Document ID | [CIAM-SD-001] |
| Product and brands | [Brand A, Brand B] |
| Version | [0.1] |
| Status | [Draft / In review / Approved / Superseded] |
| Owner | [@ciam-architect] |
| Approvers/reviewers | [@product-owner], [@ciso], [@dpo], [@fraud-lead], [@customer-support-lead] |
| Customer volume | [*Example:* 6 million registered, 1.2 million monthly active, peak 4,000 sign-ins per second at campaign launch] |
| Regions and residency | [*Example:* EU customers stored in EU region; US customers in US region] |
| Target assurance | [*Example:* AAL2 for account changes and payments; AAL1 for browsing; IAL1 by default, IAL2 for regulated products] |
| Regulatory drivers | [*Example:* GDPR, PSD2 strong customer authentication, accessibility law] |
| Classification | [Internal / Confidential] |
| Last updated | YYYY-MM-DD |

### Approvals

| Role | Name | Decision | Date |
|---|---|---|---|
| Product owner | [@name] | [Approve / Approve with conditions / Reject] | YYYY-MM-DD |
| Security | [@name] | [Decision] | YYYY-MM-DD |
| Data protection officer | [@name] | [Decision] | YYYY-MM-DD |
| Fraud and risk | [@name] | [Decision] | YYYY-MM-DD |

### Revision history

| Version | Date | Author | Change summary |
|---|---|---|---|
| 0.1 | YYYY-MM-DD | [@name] | First draft |
| 0.2 | YYYY-MM-DD | [@name] | *Example:* Passkey-first sign-in and recovery design agreed with fraud team |
| 1.0 | YYYY-MM-DD | [@name] | *Example:* Approved for build; migration in two waves |

## Contents

<!-- Guidance: Keep this list aligned with the headings. -->

1. [Scope, goals and principles](#1-scope-goals-and-principles)
2. [Personas, channels and journeys](#2-personas-channels-and-journeys)
3. [Risk and assurance per journey](#3-risk-and-assurance-per-journey)
4. [Registration and identity proofing](#4-registration-and-identity-proofing)
5. [Authentication](#5-authentication)
6. [Account recovery](#6-account-recovery)
7. [Protocols, tokens and API security](#7-protocols-tokens-and-api-security)
8. [Consent, preferences and privacy](#8-consent-preferences-and-privacy)
9. [Profile store and data model](#9-profile-store-and-data-model)
10. [B2B2C organisations and delegated administration](#10-b2b2c-organisations-and-delegated-administration)
11. [Fraud, bot and abuse defence](#11-fraud-bot-and-abuse-defence)
12. [Scale, availability and performance](#12-scale-availability-and-performance)
13. [Integrations and identity events](#13-integrations-and-identity-events)
14. [Platform choice and build vs buy](#14-platform-choice-and-build-vs-buy)
15. [Metrics and KPIs](#15-metrics-and-kpis)
16. [Migration, delivery and risks](#16-migration-delivery-and-risks)
17. [Requirements traceability and acceptance](#17-requirements-traceability-and-acceptance)
18. [Glossary and references](#18-glossary-and-references)

## 1. Scope, goals and principles

<!-- Guidance: State which brands, channels and customer types are covered and what the business wants from identity. Questions: Is the goal conversion, fraud reduction, a single customer view or regulatory compliance? Pitfall: copying workforce IAM assumptions (managed devices, HR source of truth) into a consumer context where none of them hold. -->

### 1.1 Scope

| In scope | Out of scope |
|---|---|
| *Example:* Web, iOS and Android apps for two brands with a shared account | Staff and agent accounts (workforce IAM) |
| *Example:* Business customers who manage their own users | Payment card data (handled by the payment provider) |
| *Example:* Third-party apps accessing customer data with consent | Marketing analytics platform internals |
| [Item] | [Item] |

### 1.2 Business goals

| ID | Goal | Measure | Target |
|---|---|---|---|
| CG-001 *(Example)* | Increase registration completion | Started vs completed registrations | From 61% to 75% |
| CG-002 *(Example)* | Reduce account takeover | Confirmed ATO cases per 100,000 active accounts per month | Halve in 12 months |
| CG-003 *(Example)* | One account across brands | Customers with a single profile | 90% after migration |
| [CG-NNN] | [Goal] | [Measure] | [Target] |

### 1.3 Design principles

| ID | Principle | Consequence |
|---|---|---|
| CP-001 *(Example)* | Passkey first, password optional | New customers are offered a passkey at registration; passwords remain for devices without passkey support |
| CP-002 *(Example)* | Collect the least data that the journey needs | Progressive profiling; no date of birth unless a product requires it |
| CP-003 *(Example)* | Friction follows risk | Browsing needs no step-up; changing payout details does |
| CP-004 *(Example)* | Consent is a record, not a checkbox | Every consent has version, timestamp, channel and purpose (section 8) |
| CP-005 *(Example)* | Standard protocols only | OIDC and OAuth 2.0 for all channels; no custom token formats |
| [CP-NNN] | [Principle] | [Consequence] |

## 2. Personas, channels and journeys

<!-- Guidance: List who the customers are, how they reach you and the journeys identity must support. Questions: Which journeys drive revenue? Which are used rarely but are high risk (recovery, email change)? Pitfall: designing only sign-in and forgetting account linking, deletion and guardian accounts. -->

### 2.1 Personas

| Persona | Description | Channels | Identity needs |
|---|---|---|---|
| Guest shopper *(Example)* | Buys once, no account | Web | Guest checkout, optional account creation after purchase |
| Returning customer *(Example)* | Signs in weekly | Mobile app, web | Fast passkey sign-in, long sessions on trusted device |
| Business admin *(Example)* | Manages 20 to 500 users of a business customer | Web | Invite users, assign roles, federate the company's own IdP |
| Minor with guardian *(Example)* | Under the age of digital consent in their country | App | Guardian consent and linked guardian account |
| Third-party app *(Example)* | Fintech or partner using customer data | API | OAuth consent, scoped and revocable access |
| [Persona] | [Description] | [Channels] | [Needs] |

### 2.2 Journey catalogue

| ID | Journey | Frequency | Risk | Key steps |
|---|---|---|---|---|
| JRN-001 *(Example)* | Register | Once | Low | Email or phone, verify, create passkey, optional profile |
| JRN-002 *(Example)* | Sign in | High | Medium | Passkey autofill; password fallback |
| JRN-003 *(Example)* | Change email or phone | Rare | High | Step-up, notify old and new contact, cooling-off for payouts |
| JRN-004 *(Example)* | Recover account | Rare | High | Section 6 |
| JRN-005 *(Example)* | Link social account | Occasional | Medium | Sign in to existing account first, then link |
| JRN-006 *(Example)* | Delete account | Rare | Medium | Step-up; grace period; erasure across systems (section 8) |
| JRN-007 *(Example)* | Grant third-party access | Occasional | High | OAuth consent screen with scopes and duration |
| [JRN-NNN] | [Journey] | [Frequency] | [Risk] | [Steps] |

## 3. Risk and assurance per journey

<!-- Guidance: Apply the SP 800-63-4 digital identity risk management process to customer journeys: assess harm, pick initial levels, tailor, keep evaluating. Questions: What is the worst outcome if an attacker completes this journey? Pitfall: forcing the highest level on all journeys, which kills conversion, or the lowest on all, which invites fraud. -->

SP 800-63-4 asks you to define the service, assess impact, select initial IAL, AAL and FAL, tailor them and keep evaluating. For a consumer service, record the tailoring with the fraud signals that compensate for lower proofing.

| ID | Journey or product | Impact if compromised | IAL | AAL | Compensating or supplemental controls |
|---|---|---|---|---|---|
| CAS-001 *(Example)* | Browse, wish list | Low | None (self-asserted) | AAL1 | Bot management |
| CAS-002 *(Example)* | Place order with saved card | Moderate financial | None | AAL1 session, AAL2 step-up for new delivery address | Device reputation, velocity rules |
| CAS-003 *(Example)* | Change payout bank account | High financial | IAL1 | AAL2, phishing-resistant preferred | 24-hour hold, notification to all channels |
| CAS-004 *(Example)* | Regulated product (credit, age-restricted goods) | High, legal | IAL2 | AAL2 | Document and selfie check through proofing provider |
| CAS-005 *(Example)* | Third-party data access (open finance) | High | Inherited | AAL2 with strong customer authentication | FAPI 2.0 Security Profile (section 7.3) |
| [CAS-NNN] | [Journey] | [Impact] | [IAL] | [AAL] | [Controls] |

## 4. Registration and identity proofing

<!-- Guidance: Define what is collected at sign-up, how contact points are verified and when stronger proofing is needed. Questions: Email, phone or both as the identifier? When do you call a proofing provider? Pitfall: requiring heavy proofing at registration for every customer when only a few products need it. -->

### 4.1 Registration design

| Element | Design |
|---|---|
| Identifier *(Example)* | Email address, verified by one-time link or code before the account becomes active; phone optional |
| Credential at sign-up *(Example)* | Offer passkey creation immediately; WebAuthn Level 3 conditional create lets the browser or password manager add a passkey automatically, without an extra prompt (usually with a notification), after a password sign-in on supporting browsers |
| Progressive profiling *(Example)* | Name at first order; date of birth only for age-restricted products |
| Duplicate detection *(Example)* | Same verified email cannot register twice; offer sign-in or recovery instead, without revealing whether the address exists to unauthenticated callers |
| Terms and consent *(Example)* | Terms version accepted and marketing consent captured separately, unticked by default (section 8) |
| Accessibility *(Example)* | Registration meets WCAG 2.2 AA; no puzzle CAPTCHA without an accessible alternative |
| [Element] | [Design] |

### 4.2 Identity proofing (when required)

| Trigger | Proofing method | Target IAL | Provider | Data retained |
|---|---|---|---|---|
| *Example:* Apply for credit | Remote document plus selfie with liveness, plus authoritative database check | IAL2 | [Provider] | Result, reference, evidence type; images deleted after [30] days unless law requires |
| *Example:* Age-restricted purchase | Age estimation or document check | Tailored (age only) | [Provider] | Over or under threshold flag only |
| [Trigger] | [Method] | [IAL] | [Provider] | [Retention] |

Record proofing results as attributes with source, date and level, not as a permanent "verified" flag; re-proof when a regulated product or SP 800-63A-4 tailoring requires.

## 5. Authentication

<!-- Guidance: Define the authenticators offered, their order, social login rules, step-up and sessions. Questions: What is the fallback when a customer's device has no passkey? Can social login create an account? Pitfall: allowing email magic links or SMS codes as the only factor for high-risk actions. -->

### 5.1 Authenticator options

| Option | Use | Assurance | Notes |
|---|---|---|---|
| Passkey (synced or device-bound) *(Example)* | Default sign-in on all channels | AAL2 when the passkey asserts user verification | SP 800-63B-4 permits syncable authenticators up to AAL2. Use conditional mediation (autofill) for low friction. Use related origin requests if brands share one account across domains |
| Password plus second factor *(Example)* | Fallback | AAL2 | Breached-password check at set and sign-in; no composition rules; length per SP 800-63B-4 |
| Authenticator app code *(Example)* | Second factor | AAL2 with password | Not phishing resistant |
| SMS one-time code *(Example)* | Second factor for customers without alternatives | AAL2 with password, restricted | SP 800-63B-4 classes PSTN as restricted; check SIM-swap and porting signals before trusting it |
| Email one-time link or code *(Example)* | Contact verification and recovery only | Not an authenticator | SP 800-63B-4 does not allow email for out-of-band authentication; if the business still accepts email links for low-risk sign-in, record it as a tailored exception in section 3 |
| Social login (OIDC providers) *(Example)* | Optional sign-in | Depends on provider; treat as AAL1 unless the provider asserts more | Link only to an existing account after the customer proves control of it |
| [Option] | [Use] | [Assurance] | [Notes] |

### 5.2 Step-up and risk-based authentication

The flow shows a returning customer who signs in with a passkey and is asked to step up before changing payout details. The API signals the need for step-up with the `insufficient_user_authentication` error and the `acr_values` and `max_age` parameters defined in RFC 9470 (OAuth 2.0 Step Up Authentication Challenge Protocol).

```mermaid
sequenceDiagram
  participant C as Customer app
  participant AS as Authorization server
  participant R as Risk engine
  participant API as Account API
  C->>AS: Authorization request (code flow, PKCE, acr_values=basic)
  AS->>R: Device, IP, behaviour signals
  R-->>AS: Low risk
  AS-->>C: Passkey sign-in, tokens with acr=basic
  C->>API: Change payout account
  API-->>C: 401 insufficient_user_authentication (requires acr=strong)
  C->>AS: New authorization request with acr_values=strong, max_age=0
  AS->>C: Passkey with user verification, or password plus second factor
  AS-->>C: Tokens with acr=strong, auth_time=now
  C->>API: Retry with new token
  API->>API: Check acr and auth_time, place 24-hour hold, notify customer
```

### 5.3 Sessions

| Channel | Session design | Limits |
|---|---|---|
| Web *(Example)* | Server session cookie (HttpOnly, Secure, SameSite=Lax) issued after OIDC sign-in | Idle [30 days] on trusted device, [12 hours] otherwise; step-up valid [10 minutes] |
| Mobile app *(Example)* | Refresh token in platform secure storage, bound with DPoP where supported | Refresh token rotation for public clients; absolute lifetime [90 days] |
| [Channel] | [Design] | [Limits] |

## 6. Account recovery

<!-- Guidance: Recovery is the highest-risk journey in CIAM. Define each path, its assurance and the protections. Questions: What happens when a customer loses the only device with their passkey and also the email account? Pitfall: support agents who can change the email address on a call after two knowledge questions. -->

| ID | Path | When offered | Protection | Result |
|---|---|---|---|---|
| REC-001 *(Example)* | Second registered passkey or synced passkey on another device | Always first | None needed | Normal sign-in |
| REC-002 *(Example)* | Recovery code saved at enrolment | Customer has the code | Single use, rate limited | Sign-in, then prompt for new passkey |
| REC-003 *(Example)* | Verified email link plus verified phone code | No passkey available | Both contacts must be unchanged for [7] days; risk score low | Limited session; high-risk actions locked for [72] hours |
| REC-004 *(Example)* | Identity proofing re-check (document plus selfie) | Contacts lost or changed | IAL2 match against proofing on file | Full recovery after review |
| REC-005 *(Example)* | Assisted recovery by support agent | Last resort | Agent cannot see or set credentials; triggers REC-004 link; dual approval for high-value accounts | Same as REC-004 |
| [REC-NNN] | [Path] | [When] | [Protection] | [Result] |

After any recovery: revoke all sessions and refresh tokens, notify every registered channel, and show the customer a list of recent changes.

## 7. Protocols, tokens and API security

<!-- Guidance: Fix the protocol profile for every client type so that teams cannot drift. Questions: Which clients are public (apps, SPAs) and which confidential? Are any APIs in scope of open banking or FAPI? Pitfall: tokens in browser local storage and long-lived bearer tokens that work anywhere once stolen. -->

### 7.1 Client profiles

| Client type | Flow | Client authentication | Token handling |
|---|---|---|---|
| Web app with backend *(Example)* | OIDC authorisation code with PKCE | `private_key_jwt` | Tokens stay on the server; browser holds only a session cookie (backend-for-frontend) |
| Single-page app *(Example)* | Authorisation code with PKCE through a backend-for-frontend | Backend authenticates | No tokens in local storage |
| Native mobile app *(Example)* | Authorisation code with PKCE via system browser or platform passkey APIs | Public client | Refresh token in secure enclave or keystore; DPoP where supported |
| Partner backend *(Example)* | Client credentials or token exchange | mTLS or `private_key_jwt` | Audience-restricted, short-lived |
| [Client] | [Flow] | [Authentication] | [Handling] |

### 7.2 Baseline from RFC 9700

- Use the authorisation code flow with PKCE for every client; do not use the implicit or resource owner password grants.
- Match redirect URIs exactly; reject wildcards.
- Restrict access tokens to an audience and keep their lifetime short (*Example:* 5 to 15 minutes).
- Sender-constrain tokens (DPoP, RFC 9449, or mTLS) where theft would cause harm.
- Rotate refresh tokens for public clients or bind them to the client.

### 7.3 FAPI 2.0 profile for financial-grade APIs

Where APIs move money or expose financial data (for example open banking or open finance), apply the FAPI 2.0 Security Profile (Final, February 2025): pushed authorisation requests with client authentication, PKCE with S256, response type `code` only, sender-constrained access tokens through mTLS or DPoP, client authentication through mTLS or `private_key_jwt`, and single-use authorisation codes with a maximum lifetime of 60 seconds. Check the profile for the remaining limits and the separate FAPI 2.0 Attacker Model. Jurisdiction-specific open banking profiles add consent and API rules; see Open Banking API Design (`industry/open-banking-api-design`).

### 7.4 Token claims

| Claim | Content | Notes |
|---|---|---|
| `sub` *(Example)* | Pairwise subject per relying party for third parties; public subject for first-party apps | Prevents cross-party tracking |
| `acr`, `amr`, `auth_time` *(Example)* | Assurance reached and methods used | APIs enforce step-up from these |
| `org_id`, `org_roles` *(Example)* | B2B2C organisation context (section 10) | Only in tokens for business apps |
| [Claim] | [Content] | [Notes] |

## 8. Consent, preferences and privacy

<!-- Guidance: Define how consent and preferences are captured, stored, changed and enforced, and how privacy rights are served. Questions: Which processing relies on consent and which on another lawful basis? Pitfall: marketing consent stored only in the marketing tool, so a withdrawal in one channel never reaches the others. -->

### 8.1 Consent and preference records

| Record | Lawful basis (GDPR Art. 6) | Captured where | Stored fields | Enforced by |
|---|---|---|---|---|
| Terms of service *(Example)* | Contract | Registration | Terms version, timestamp, channel | CIAM |
| Marketing email *(Example)* | Consent (Art. 7 conditions) | Registration, preference centre | Purpose, wording version, timestamp, channel, withdrawal time | Marketing platform via event (section 13) |
| Third-party data sharing *(Example)* | Consent or contract per product | OAuth consent screen | Client, scopes, expiry, revocation | Authorization server |
| Guardian consent for a minor *(Example)* | Consent by holder of parental responsibility (Art. 8) | Guardian flow | Guardian account link, verification method | CIAM |
| [Record] | [Basis] | [Where] | [Fields] | [Enforced by] |

### 8.2 Privacy rights and data protection

| Right or duty | GDPR article | CIAM design |
|---|---|---|
| Access *(Example)* | Art. 15 | Self-service export of profile, consents and sign-in history |
| Erasure *(Example)* | Art. 17 | Delete journey JRN-006; erasure event to all downstream systems; tombstone ID kept to block replay |
| Portability *(Example)* | Art. 20 | Machine-readable export |
| Data protection by design *(Example)* | Art. 25 | Minimal attributes, pairwise identifiers, short retention |
| Security of processing *(Example)* | Art. 32 | Encryption, access logging, section 11 |
| Impact assessment *(Example)* | Art. 35 | DPIA for proofing and fraud profiling, recorded in DPIA (`compliance/dpia`) |
| International transfers *(Example)* | Chapter V (from Art. 44) | Regional data stores; transfer mechanism per processor |

Check the consolidated GDPR text and local law (for example child consent age and sector rules) for each market. This section records design decisions, not legal conclusions.

### 8.3 Data residency

Place each customer's profile in the region of their market and keep identity-provider metadata, logs and backups in the same region unless an approved transfer applies. Record decisions in the Data Residency and Sovereignty Assessment (`compliance/data-residency-sovereignty-assessment`).

## 9. Profile store and data model

<!-- Guidance: Define where customer identity data lives, which system owns each attribute and how profiles are linked. Questions: Is the CIAM store the master for name and contact, or the CRM? Pitfall: two masters for email address, so changes in one get overwritten by a nightly sync from the other. -->

| Entity or attribute | Owner system | Notes |
|---|---|---|
| Account (immutable ID, status, created, region) *(Example)* | CIAM | ID never reused |
| Credentials (passkeys, password hash, factors) *(Example)* | CIAM | Never exported to other systems |
| Verified contact points (email, phone with verification date) *(Example)* | CIAM | Changes raise events |
| Profile (name, preferred language, addresses) *(Example)* | CIAM for identity attributes; commerce for addresses | Document the split |
| Linked identities (social provider, subject) *(Example)* | CIAM | Unlink allowed if another sign-in method remains |
| Consents and preferences *(Example)* | Consent service within CIAM | Section 8 |
| Organisation membership *(Example)* | CIAM organisations | Section 10 |
| Customer value, segments *(Example)* | CRM or customer data platform | Not stored in CIAM |
| [Attribute] | [Owner] | [Notes] |

Use the CIAM account ID as the join key across systems, not the email address. Keep sensitive proofing evidence outside the general profile, with its own retention.

## 10. B2B2C organisations and delegated administration

<!-- Guidance: If business customers manage their own users, define organisations, admin roles and enterprise federation. Questions: Can one person belong to several organisations? Who can invite and remove users? Pitfall: treating each business customer as a separate tenant of the identity platform, which multiplies configuration and cost. -->

| Topic | Design |
|---|---|
| Organisation model *(Example)* | Organisation entity with members; a person can belong to many organisations with different roles |
| Delegated admin roles *(Example)* | Organisation owner, user admin, billing admin, member |
| Invitations *(Example)* | Email invitation valid [7] days; joining requires sign-in or registration |
| Enterprise federation *(Example)* | Business customer may connect its own IdP via OIDC or SAML for its domain; home realm discovery by email domain after domain ownership is verified |
| Provisioning *(Example)* | SCIM 2.0 endpoint per organisation for customers that want automatic joiner and leaver handling |
| Isolation *(Example)* | Every API call carries `org_id`; authorisation checks membership per request (see `system-design/design-authorization-service`) |
| [Topic] | [Design] |

## 11. Fraud, bot and abuse defence

<!-- Guidance: List the attacks expected against each journey and the layered controls. Questions: What is your current credential-stuffing volume? Who reviews risk decisions? Pitfall: blocking on a single signal and locking out legitimate customers at scale. -->

| ID | Threat | Journeys | Controls | Owner |
|---|---|---|---|---|
| FRD-001 *(Example)* | Credential stuffing | JRN-002 | Passkeys reduce exposure; breached-password check; rate limits per account, IP and device; bot management at the edge | [@fraud-lead] |
| FRD-002 *(Example)* | Fake account creation | JRN-001 | Email and phone reputation, velocity, invisible challenges, disposable domain lists | [@fraud-lead] |
| FRD-003 *(Example)* | SIM swap to hijack SMS | JRN-003, JRN-004 | Carrier SIM-change signal where available; SMS not sufficient alone for recovery | [@fraud-lead] |
| FRD-004 *(Example)* | Phishing of codes (adversary in the middle) | JRN-002 | Passkeys; detect impossible travel and new device plus high-risk action | [@security-lead] |
| FRD-005 *(Example)* | Social engineering of support agents | JRN-004 | Agents cannot change credentials; scripted REC-005; call recording | [@support-lead] |
| FRD-006 *(Example)* | Account enumeration | JRN-001, JRN-004 | Uniform responses and timing; rate limits | [@security-lead] |
| [FRD-NNN] | [Threat] | [Journeys] | [Controls] | [@owner] |

Feed decisions and outcomes back to the risk engine; measure false positives (legitimate customers challenged or blocked) next to fraud caught. For the scoring pipeline itself, see Fraud detection design (`system-design/design-fraud-detection`); for threat analysis, Threat model (`security/threat-model`).

## 12. Scale, availability and performance

<!-- Guidance: Size the platform for the peak, not the average, and say what happens when it fails. Questions: What is the sign-in peak during a campaign or ticket sale? Can customers still check out if the CIAM is degraded? Pitfall: per-request calls from every API to the identity platform instead of local token validation. -->

| Item | Value | Basis |
|---|---|---|
| Registered accounts *(Example)* | 6,000,000, growing 15% a year | Current CRM count |
| Peak sign-ins *(Example)* | 4,000 per second for 10 minutes | Last campaign × 2 safety factor |
| Token validation *(Example)* | Local JWT validation at APIs with cached keys; no call to CIAM per request | Keeps CIAM out of the hot path |
| Availability target *(Example)* | 99.95% for sign-in and token endpoints | Revenue impact estimate |
| Latency target *(Example)* | Sign-in page 95th percentile under 300 ms server time | Conversion data |
| Degraded mode *(Example)* | Existing sessions continue; guest checkout stays open; registration queues | Business continuity decision |
| Multi-region *(Example)* | Active-active per residency region; no cross-region profile replication | Section 8.3 |
| [Item] | [Value] | [Basis] |

Recompute every figure with your own data; values above are examples.

## 13. Integrations and identity events

<!-- Guidance: List the systems that consume identity data and the events they need. Questions: How does a deletion or consent withdrawal reach every system? Pitfall: point-to-point nightly exports that leave stale data for a day. -->

| Event | Consumers | Delivery | Purpose |
|---|---|---|---|
| `account.created` *(Example)* | CRM, commerce | Event stream | Create customer record |
| `contact.changed` *(Example)* | CRM, notifications, fraud | Event stream | Update and alert |
| `consent.changed` *(Example)* | Marketing platform, CDP | Event stream, within [5] minutes | Enforce withdrawal |
| `account.deleted` *(Example)* | All downstream systems | Event stream with acknowledgement | Erasure evidence |
| `session.revoked`, `credential.compromised` *(Example)* | Partner relying parties | OpenID Shared Signals Framework with CAEP and RISC events | End sessions at partners |
| [Event] | [Consumers] | [Delivery] | [Purpose] |

## 14. Platform choice and build vs buy

<!-- Guidance: Compare platform options against the capabilities in sections 4 to 13 with weighted criteria. Questions: Which capabilities are differentiating and which are commodity? Pitfall: choosing on per-user price at today's volume and ignoring monthly active user growth and add-on modules. -->

| Criterion | Weight | Option A: SaaS CIAM | Option B: Self-hosted open source IdP | Option C: Build |
|---|---|---|---|---|
| Passkeys and WebAuthn Level 3 features *(Example)* | 15 | [Score] | [Score] | [Score] |
| FAPI 2.0 and OAuth BCP conformance *(Example)* | 10 | [Score] | [Score] | [Score] |
| B2B2C organisations and delegated admin *(Example)* | 10 | [Score] | [Score] | [Score] |
| Data residency regions *(Example)* | 15 | [Score] | [Score] | [Score] |
| Fraud and bot integration *(Example)* | 10 | [Score] | [Score] | [Score] |
| Scale to peak and SLA *(Example)* | 15 | [Score] | [Score] | [Score] |
| Five-year cost at projected volume *(Example)* | 15 | [Score] | [Score] | [Score] |
| Exit and data export, including credential portability *(Example)* | 10 | [Score] | [Score] | [Score] |

Record the full comparison in Build vs Buy Analysis (`architecture/build-vs-buy-analysis`) and the decision as an ADR. Check whether certification (for example OpenID Foundation conformance for OIDC and FAPI) is current for the exact product version.

## 15. Metrics and KPIs

<!-- Guidance: Pick a small set of metrics that cover conversion, security and operations, with owners and targets. Pitfall: measuring only security metrics, so product teams see identity as a cost centre. -->

| ID | Metric | Definition | Target | Owner |
|---|---|---|---|---|
| KPI-001 *(Example)* | Registration completion | Completed / started registrations | 75% | [@product-owner] |
| KPI-002 *(Example)* | Passkey adoption | Active accounts with at least one passkey | 50% in 12 months | [@ciam-architect] |
| KPI-003 *(Example)* | Sign-in success rate | Successful / attempted sign-ins excluding bots | 97% | [@product-owner] |
| KPI-004 *(Example)* | Account takeover rate | Confirmed ATO per 100,000 MAU per month | Halve baseline | [@fraud-lead] |
| KPI-005 *(Example)* | Recovery contact rate | Support contacts about sign-in per 1,000 MAU | Down 30% | [@support-lead] |
| KPI-006 *(Example)* | Consent propagation time | 95th percentile from withdrawal to enforcement in marketing | Under 5 minutes | [@dpo] |
| [KPI-NNN] | [Metric] | [Definition] | [Target] | [@owner] |

## 16. Migration, delivery and risks

<!-- Guidance: Plan how existing customers move without forced resets, and list delivery risks. Questions: Can existing password hashes be imported? How are duplicate accounts across brands merged? Pitfall: forcing every customer to reset their password on day one. -->

### 16.1 Migration approach

| Step | Design |
|---|---|
| Hash import *(Example)* | Import existing password hashes if the target supports the algorithm; rehash to the target algorithm at next sign-in |
| Lazy migration *(Example)* | Where hashes cannot be imported, verify against the legacy store at first sign-in, then store the new hash and retire the legacy record |
| Account merge *(Example)* | Merge accounts across brands by verified email only after the customer signs in to both; never merge silently on unverified data |
| Passkey campaign *(Example)* | Prompt for passkey creation after successful sign-in for [N] weeks |
| Cutover *(Example)* | Per brand, behind a feature flag, with rollback to the legacy login for [14] days |

### 16.2 Risks

| ID | Risk | Mitigation | Owner |
|---|---|---|---|
| RSK-001 *(Example)* | Conversion drop when the new sign-in launches | A/B launch, monitor KPI-001 and KPI-003 daily, rollback flag | [@product-owner] |
| RSK-002 *(Example)* | Legacy hash algorithm not supported | Lazy migration path | [@ciam-architect] |
| RSK-003 *(Example)* | Fraud moves to recovery once passkeys block stuffing | Section 6 controls live before passkey launch | [@fraud-lead] |
| [RSK-NNN] | [Risk] | [Mitigation] | [@owner] |

Use Cutover Plan (`project/cutover-plan`) for each brand's go-live.

## 17. Requirements traceability and acceptance

<!-- Guidance: Trace requirements to design and test; write acceptance criteria as observable outcomes. -->

| Req ID | Requirement | Section | Verification | Acceptance criterion |
|---|---|---|---|---|
| CIAM-REQ-001 *(Example)* | Customers can register and sign in with a passkey on all channels | 4.1, 5.1 | Test on supported browser and OS matrix | Passkey create and sign-in pass on every matrix entry |
| CIAM-REQ-002 *(Example)* | High-risk changes require step-up | 5.2 | Automated test calling API with basic token | API rejects with step-up error; accepts after strong sign-in |
| CIAM-REQ-003 *(Example)* | Consent withdrawal enforced everywhere within 5 minutes | 8.1, 13 | End-to-end test | Marketing send suppressed within 5 minutes |
| CIAM-REQ-004 *(Example)* | Financial APIs meet FAPI 2.0 | 7.3 | OpenID Foundation conformance suite | All required tests pass |
| CIAM-REQ-005 *(Example)* | No account enumeration | 11 | Security test | Identical response and timing for known and unknown identifiers |
| [CIAM-REQ-NNN] | [Requirement] | [Section] | [Method] | [Criterion] |

## 18. Glossary and references

<!-- Guidance: Define terms and record exact versions consulted, with the date checked. -->

### 18.1 Glossary

| Term | Meaning |
|---|---|
| CIAM | Customer identity and access management |
| B2B2C | Business-to-business-to-consumer: business customers manage their own users on your platform |
| Passkey | WebAuthn credential that replaces a password; synced across a provider's devices or bound to one device |
| Conditional mediation | WebAuthn feature that offers passkeys through the browser's autofill |
| Step-up | Asking for stronger authentication before a sensitive action |
| PAR | Pushed authorisation request (RFC 9126) |
| DPoP | Demonstrating proof of possession, a way to bind tokens to a client key (RFC 9449) |
| ATO | Account takeover |
| MAU | Monthly active users |

### 18.2 References

| Reference | Version or date | Use |
|---|---|---|
| NIST SP 800-63-4, Digital Identity Guidelines (63A-4, 63B-4, 63C-4) | Final, July 2025 | Risk process, assurance levels, authenticator rules |
| OpenID Connect Core 1.0 incorporating errata set 2 | December 2023 | Sign-in protocol |
| RFC 9700, Best Current Practice for OAuth 2.0 Security | January 2025 | OAuth baseline |
| FAPI 2.0 Security Profile, OpenID Foundation | Final, approved 19 February 2025 (specification dated 22 February 2025) | Financial-grade APIs |
| RFC 9126 (PAR), RFC 9449 (DPoP), RFC 9470 (step-up challenge) | 2021, 2023, 2023 | Request and token protection, step-up |
| W3C Web Content Accessibility Guidelines (WCAG) 2.2 | W3C Recommendation, October 2023 | Accessible registration and sign-in |
| W3C Web Authentication Level 3 | W3C Recommendation, 25 August 2026 | Passkeys, conditional create, related origins, backup flags |
| OpenID Shared Signals Framework 1.0, CAEP 1.0, RISC 1.0 | Final, September 2025 | Identity events to partners |
| RFC 7643 and RFC 7644, SCIM 2.0 | September 2015 | B2B provisioning |
| Regulation (EU) 2016/679 (GDPR), EUR-Lex | Consolidated text | Articles 6, 7, 8, 15, 17, 20, 25, 32, 35, Chapter V |
| [Market-specific law] | [Version] | [Use] |

## Standard and licence note

Based on NIST SP 800-63-4 Digital Identity Guidelines (final, July 2025), a work of the US Government, and on the public specifications OpenID Connect Core 1.0 and the FAPI 2.0 Security Profile (OpenID Foundation), RFC 9700, RFC 9126, RFC 9449, RFC 9470, RFC 7643 and RFC 7644 (IETF) and W3C Web Authentication Level 3. GDPR articles are cited by number and paraphrased; this is a documentation format, not legal advice. No specification text is reproduced; this template is original text written for this collection. Product names belong to their owners. Check the current official versions and the consolidated legal text before use. Template licence: MIT.