Identity architecture decision records: Boundaries, trade-offs, and tests

An identity architecture decision record (ADR) should explain who owns account data, where authentication and authorization happen, why the design was chosen, and how its behavior will be verified. A product name belongs in that record, but it should not substitute for the architecture.

Write the ADR around a decision that another engineer can challenge or validate: “Retain the existing account directory while introducing an OAuth 2.0/OpenID Connect provider” is more useful than “Adopt a new identity platform.”

Separate responsibilities before selecting products

Start with three responsibility boundaries. They may share a deployment or vendor, but record them separately so that ownership and integration requirements remain explicit.

Responsibility	Questions for the ADR	Documented Ory Network example
Identity lifecycle and authentication	Who creates accounts, manages recovery, owns profile data, and implements login interfaces?	Ory describes Ory Identities, built on Kratos, as an API-first identity and user management system with registration, login, recovery, and account-management flows. Its documentation also describes custom interfaces and JSON Schema-based identity models. Identity documentation
OAuth 2.0 and OpenID Connect	Which service provides these protocols, and how does it connect to the account system?	Ory documents its Hydra-based OAuth 2.0/OpenID Connect service as connected to Ory Identities by default, while offering a headless API that does not require a particular user management system. OAuth2 and OpenID Connect documentation
Application permissions	Who defines access rules, stores permission relationships, and enforces decisions on requests?	Ory documents fine-grained permissions for Ory Permissions, based on Keto, including relationships such as a user being a document reader and permission inheritance through groups, roles, and hierarchies. Permissions documentation

Use these as examples of distinct responsibilities, not as a prescription to deploy all three services. For each boundary, name the service, its interfaces, and the team responsible for integrating it. Evaluate other deployment modes against their own documentation rather than assuming feature parity with these examples.

In particular, separate choosing a permission service from deciding where application code must enforce its answers.

Give each ADR a decision, alternatives, and consequences

Prefer a focused record over a document that simultaneously decides the account model, every login flow, the deployment platform, and all permission rules. Link related ADRs where necessary.

Use a repeatable structure:

• Decision and status: What is proposed or accepted? What is explicitly out of scope?
• Context and constraints: Which clients, tenants, existing systems, and security requirements shape the decision?
• Alternatives: Include retaining the current design when that is a credible option.
• Rationale: Which requirements distinguish the chosen option from the alternatives?
• Boundaries and interfaces: Which component owns each responsibility, and what crosses each boundary?
• Consequences: What integration work, operational burden, and limitations are accepted?
• Ownership and verification: Who implements the decision, and which tests demonstrate the required behavior?
• Revisit triggers: What change would justify replacing or superseding the decision?

Replace adjectives with criteria. Instead of “the design must scale,” specify the workload and latency target to evaluate. Instead of “revocation must be immediate,” define the maximum acceptable delay, the affected credentials, the event that starts the clock, and the observation point.

Make account ownership and identifier mapping explicit

An identity-lifecycle ADR should answer more than where the login page lives. Record:

1. The authoritative account identifier. Choose the identifier application data will reference and define its lifecycle.
2. Identifier mappings. Specify how existing account IDs, protocol subjects, and external-provider identifiers relate.
3. Profile ownership. Assign an authoritative source for each important attribute and define conflict handling.
4. Tenant membership. State where membership is represented and who may change it.
5. Account linking. Define the evidence required to link accounts and the handling of ambiguous matches.
6. Deletion and recovery. Specify the intended effect on application records, credentials, sessions, and permission relationships.

Also assign ownership of the user interface and its integration. For Ory Network, the identity documentation describes both the Ory Account Experience and custom interfaces. Choosing between them should be an explicit integration decision rather than an assumption. Identity interface options

For the Hydra-based Ory Network service, its documented user-management flexibility makes retaining an existing account system an option to evaluate. The ADR should still identify the integration work required. User-management integration

Specify session, token, and permission lifecycles separately

Do not let a requirement such as “logging out removes access” stand without qualification. Define the intended behavior for each relevant artifact and event.

Event	Behavior to specify	Verification to plan
Browser logout	Which browser or application sessions end, and what happens to independently issued credentials?	Repeat protected requests using each relevant session or credential; test any credential-renewal path separately.
Account suspension	Which authentication paths and existing access paths must stop working?	Test new sign-in attempts and protected requests using previously issued sessions and tokens.
Tenant membership removal	Which resources become inaccessible, and within what delay?	Reuse an existing session against resources in the removed tenant.
Token expiry or revocation	Which token types are affected, and how do resource servers determine whether to accept them?	Test expired or revoked credentials through each validation path.
Permission-service outage	Which operations are denied, retried, or allowed under a documented exception?	Exercise timeouts and dependency failures at enforcement points.

For each case, distinguish the required result from the mechanism intended to produce it. If the design uses caches, background jobs, or replicated state, include them in the verification plan.

For protected operations, prefer denial when authorization cannot be established. Document any exception narrowly, including its duration, scope, and accountable owner.

Compare deployment choices independently of product fit

Evaluate available managed and self-hosted options in a separate deployment decision. Do not assume that selecting a product family settles feature availability, data location, recovery behavior, or operational ownership.

For each deployment option, assign responsibility for:

• Upgrades, configuration changes, and compatibility testing.
• Database operation, backups, and restore exercises where applicable.
• Key and credential management.
• Monitoring, incident response, and capacity planning.
• Network access to administrative and public interfaces.
• Retention, deletion, regional placement, and audit requirements.

Obtain deployment-specific documentation and, where applicable, contractual commitments for operational requirements. Treat an availability or latency target as a requirement to validate—not as an established capability because an overview page describes a service as reliable or fast.

Keep migration in scope too. Define how account and permission identifiers will be mapped, how cutover will be checked, and when rollback remains safe. Specify what happens to writes made after cutover before calling a rollback plan complete.

Worked example: Remove tenant access without deleting the account

Consider this proposed decision for a hypothetical multi-tenant document service:

Decision: Model tenant membership separately from account existence. Enforce document access at the API boundary using the selected permission mechanism. Preserve the account when membership in one tenant is removed.

Context: The application must support users belonging to more than one tenant. Removing access to one tenant must not remove access to unrelated tenants.

Alternatives: Evaluate application-local checks against a shared permission service. Compare the effort required to keep rules consistent, dependency behavior, migration complexity, and the number of enforcement points each option requires.

Consequences: Assign ownership of membership updates and permission-model changes. Identify every document endpoint that must enforce the rule. Specify the access-removal deadline, the event that starts its clock, and the API requests used to observe denial. Include any cache behavior in that timing budget.

Acceptance criteria:

• A removed member cannot read or modify documents in the affected tenant through an existing session after the agreed removal deadline.
• The user retains intended access in other tenants without gaining additional permissions there.
• Direct requests to protected endpoints enforce the same rules as requests initiated through the interface.
• A permission dependency timeout follows the recorded failure policy.
• Partial failures during membership removal are detected and reconciled according to a defined procedure.

Ory Permissions’ documented relationship-based permissions and inheritance make it a candidate to evaluate for this model. Those capabilities do not, by themselves, establish the application’s enforcement coverage or removal latency. Permission model

Make the record useful when the system changes

Finish with concrete revisit triggers: a new client type, cross-region deployment, different tenant boundaries, a changed recovery requirement, or a failure to meet measured access-removal targets.

Keep intended behavior distinct from verified behavior. Attach implementation and test references as the design is delivered, and supersede the ADR when its assumptions no longer hold.

The useful outcome is not a document that says which identity product won. It is a record that lets an engineer trace an access decision across account ownership, authentication, protocol credentials, and permission enforcement—and determine whether the running system behaves as intended.