Skip to content

ADR-0006: Define Authentication, Organization Membership, and Authorization

  • Status: Accepted
  • Date: 2026-10-09
  • Decision Owners: Zelvoryqa Architecture
  • Technical Area: Identity and Access Management / Security / Multi-Tenancy
  • Related ADRs:
  • ADR-0001: Adopt Microservices Based on Business Capabilities
  • ADR-0002: Adopt Multi-Tenant SaaS Architecture
  • ADR-0003: Define Service Data Ownership and Tenant Data Isolation
  • ADR-0004: Adopt Event-Driven Integration
  • ADR-0005: Define Synchronous Service Communication

Context

Zelvoryqa is designed as a multi-tenant SaaS platform composed of independently deployable services aligned to business capabilities.

ADR-0001 establishes that services own their business capabilities and enforce their architectural boundaries.

ADR-0002 establishes that one organization corresponds to one logical tenant boundary and that organization context must be preserved and enforced across distributed operations.

ADR-0003 establishes that services own their operational data and must enforce organization-scoped data access.

ADR-0004 establishes that organization context must be preserved and validated during asynchronous event processing.

ADR-0005 establishes that synchronous service communication must preserve service identity, organization context, authorization, and authoritative service ownership.

Zelvoryqa will support users who may belong to multiple organizations, organizations with multiple users, and independently deployed services that operate on organization-owned resources.

The platform must also support non-interactive workloads, including internal services, background jobs, event consumers, and automated integrations.

These interactions introduce several distinct security concerns:

  • Establishing the identity of users and workloads
  • Managing organization membership
  • Selecting and validating the organization associated with an operation
  • Determining permissions within an organization
  • Restricting access to organization-owned resources
  • Authenticating internal service communication
  • Preserving authorization across synchronous and asynchronous operations
  • Supporting organization membership and permission changes
  • Separating organization administration from platform administration
  • Auditing security-sensitive operations

Without a consistent identity and authorization model, services may interpret organization context differently, duplicate inconsistent security logic, or inadvertently permit cross-tenant access.

Zelvoryqa therefore requires a unified architectural model for authentication, organization membership, authorization, and tenant-aware access enforcement.

Decision

Zelvoryqa will adopt an identity-based, organization-aware authorization model that separates authentication, organization membership, organization context, authorization, and tenant isolation into distinct responsibilities.

All protected operations must establish an authenticated principal and evaluate the authorization requirements appropriate to the requested capability.

Organization-scoped operations must establish valid organization context and enforce the corresponding tenant boundary.

Authorization must be evaluated using trusted identity and organization information rather than relying solely on client-provided identifiers or upstream assertions.

The architecture will establish requirements for:

  • Authentication of users and workloads
  • Identity and principal representation
  • Organization membership
  • Organization context establishment
  • Organization-scoped roles and permissions
  • Resource-level authorization
  • Service-to-service authorization
  • Background jobs and event consumers
  • Platform administration
  • Membership and permission lifecycle
  • Authorization enforcement boundaries
  • Auditability and observability
  • Secure failure behavior

The specific identity provider, authentication protocols, token formats, authorization libraries, and persistence implementations will be selected separately.

Authentication Establishes Principal Identity

Authentication must establish the identity of the principal initiating an operation.

A principal may represent:

  • An interactive user
  • An internal service or workload
  • An automated integration
  • A background processing identity
  • An explicitly authorized platform operator

Authentication answers:

Who is making this request?

Authentication alone does not establish which organizations the principal may access or which actions the principal may perform.

For example, successfully authenticating a user does not automatically authorize that user to retrieve orders belonging to any organization.

Similarly, authenticating an internal service does not grant that service unrestricted access to organization-owned resources.

Protected operations must reject requests when the required identity cannot be established or trusted.

Organization Membership Establishes Organizational Relationships

Zelvoryqa will maintain explicit relationships between users and the organizations they are permitted to access.

A user may belong to multiple organizations.

An organization may have multiple users.

Conceptually:

User A
  |
  +---- Organization A
  |
  +---- Organization B

User B
  |
  +---- Organization A

Organization membership answers:

Which organizations is this user associated with?

Membership must be established using trusted platform-managed information.

A user must not gain organization membership merely by providing an organization identifier in a request.

Membership records must support an appropriate lifecycle, including:

  • Creation
  • Invitation and acceptance where applicable
  • Activation
  • Suspension or deactivation
  • Removal
  • Changes to organization-scoped roles and permissions

Membership is necessary for ordinary user access to organization-owned resources, but membership alone does not authorize every action within an organization.

For example, a user may belong to an organization while lacking permission to modify inventory or administer organization membership.

Organization Context Establishes the Active Tenant Scope

Operations involving organization-owned resources must execute within an explicitly established organization context.

Organization context answers:

On behalf of which organization is this operation being performed?

For a user belonging to multiple organizations, the active organization must be selected or otherwise unambiguously established for the requested operation.

Conceptually:

Authenticated User
       |
       v
Organization Membership
       |
       +---- Organization A
       |
       +---- Organization B
                  |
                  v
         Active Organization B
                  |
                  v
          Authorized Operation

Organization context must be derived from or validated against trusted identity, membership, and authorization information.

An organization identifier is a reference to an organization, not proof that the principal is authorized to act on its behalf.

The platform must not infer unrestricted organization access from:

  • A client-supplied organization identifier
  • A resource identifier
  • A request header
  • A URL parameter
  • A previously selected organization
  • Authentication alone

These values may be used to identify the requested scope, but the scope must be validated before an organization-owned operation is performed.

Missing, invalid, ambiguous, or unauthorized organization context must not result in unrestricted or platform-level access.

Organization-scoped operations must fail closed when the required context cannot be established.

Authorization Determines Permitted Actions

Authorization must determine whether an authenticated principal is permitted to perform a requested action on a specific resource within the applicable organization or platform scope.

Authorization answers:

What is this principal permitted to do?

An authorization decision may consider:

  • Principal identity
  • Principal type
  • Organization membership
  • Active organization context
  • Assigned roles
  • Granted permissions
  • Requested action
  • Resource type
  • Resource ownership
  • Resource state
  • Applicable business policies
  • Explicit platform-level privileges

For example:

Principal: User A
Organization: Organization A
Action: Update Inventory
Resource: Inventory Item 123

Authorization must establish that the principal is permitted to perform the requested operation and that the resource belongs to the authorized organization scope.

Authorization must not rely solely on possession of a valid resource identifier.

Access must be denied when the applicable authorization requirements are not satisfied.

Organization-Scoped Roles and Permissions

Zelvoryqa will support organization-scoped roles and permissions.

Roles provide a manageable way to assign related permissions to users within an organization.

Permissions represent the actions a principal may perform.

Conceptually:

Organization A
  |
  +---- User A
  |       |
  |       +---- Inventory Manager
  |
  +---- User B
          |
          +---- Inventory Viewer

For example:

An Inventory Manager may be authorized to view and adjust inventory.

An Inventory Viewer may be authorized to view inventory but not modify it.

A user's role in one organization must not automatically apply to another organization.

A user who is an administrator in Organization A may have limited permissions in Organization B.

Role names, permission identifiers, inheritance rules, and the initial role catalog will be defined separately.

The authorization model must support more specific resource-level or policy-based restrictions where business requirements demand them.

Roles must not become an implicit mechanism for bypassing tenant isolation.

Tenant Isolation Must Be Enforced Independently of Roles

Organization membership and authorization do not replace tenant isolation.

A principal must satisfy both the relevant permission requirements and the applicable organization ownership boundary.

Conceptually:

Authenticated User
       |
       v
Validate Organization Membership
       |
       v
Establish Organization Context
       |
       v
Authorize Requested Action
       |
       v
Validate Resource Ownership
       |
       v
Execute Business Operation

For example, a user with permission to update inventory in Organization A must not be able to modify an inventory item belonging to Organization B.

The permission to update inventory does not authorize access outside the user's permitted organization scope.

Services must enforce resource ownership using trusted organization context.

Organization-owned records must remain protected even when a caller supplies a valid resource identifier belonging to another organization.

Cross-organization access must be denied by default.

Any future cross-organization sharing or collaboration capability must define its authorization, ownership, privacy, and audit requirements explicitly.

Authorization Must Be Enforced at Service Boundaries

The API Gateway may perform authentication and authorization checks for incoming requests.

However, business services remain responsible for enforcing the authorization requirements applicable to their own capabilities and resources.

Conceptually:

Client
   |
   v
API Gateway
   |
   | Authenticate Request
   | Establish Trusted Identity Context
   v
Inventory Service
   |
   | Validate Identity and Organization Context
   | Authorize Requested Action
   | Validate Resource Ownership
   v
Inventory Operational Data

Services must not rely exclusively on the API Gateway to enforce security.

A service may receive requests through:

  • The API Gateway
  • Another internal service
  • A background job
  • An event consumer
  • An authorized administrative workflow

Each execution path must preserve the appropriate authentication, authorization, and organization-isolation requirements.

Authorization enforcement must be consistent across these entry points.

Shared authorization components may provide common validation and policy evaluation capabilities, but they must not remove the receiving service's responsibility for protecting its resources.

Service-to-Service Authentication and Authorization

Internal services must authenticate when communicating with other services through protected synchronous APIs.

Service identity establishes which workload is making the request.

However, service identity alone does not establish authorization to act on behalf of every organization.

Conceptually:

Order Service
      |
      | Authenticated Workload Identity
      | Organization A Context
      | Request Inventory Reservation
      v
Inventory Service
      |
      +---- Authenticate Calling Service
      +---- Validate Organization Context
      +---- Authorize Requested Operation
      +---- Enforce Resource Ownership
      |
      v
Organization A Inventory

Receiving services must evaluate whether the calling workload is permitted to invoke the requested capability.

For organization-scoped operations, the receiving service must also establish that the workload is authorized to act within the requested organization context.

Where a service acts on behalf of an authenticated user, the architecture must preserve sufficient trusted delegation context to enforce applicable user and organization permissions.

A calling service must not be able to impersonate arbitrary users or organizations through unverified request metadata.

Service-level permissions and user-delegated permissions must be distinguishable.

The exact workload identity, delegation, and authorization mechanisms will be defined separately.

Background Jobs and Event Consumers Must Preserve Authorization Boundaries

Background jobs and event consumers often execute without an active user request.

These workloads must still operate under explicitly defined identities and authorization scopes.

Examples include:

  • Processing an OrderCreated event
  • Updating an inventory-derived projection
  • Generating organization-specific analytics
  • Executing scheduled inventory reconciliation
  • Sending notifications
  • Processing shipment updates

Conceptually:

OrderCreated Event
       |
       | Organization A Context
       v
Inventory Event Consumer
       |
       | Validate Event Source
       | Validate Organization Context
       | Apply Authorized Consumer Capability
       v
Organization A Inventory Workflow

Event consumers must not assume that an organization identifier included in an event is sufficient proof of authorization.

Consumers must validate the event's trusted origin and apply the authorization and tenant-isolation requirements appropriate to the operation.

An authenticated event producer does not grant every consumer unrestricted access to organization resources.

Background workloads must not obtain platform-wide access merely because they operate without an interactive user.

The architecture must distinguish between:

  • Work performed on behalf of a user
  • Work performed under an explicitly authorized service capability
  • Work performed under an explicitly authorized platform capability

The applicable authorization scope must remain enforceable throughout the workflow.

Platform Administration Must Be Explicitly Separated

Zelvoryqa may require platform-level administrative capabilities for operations such as:

  • Platform configuration
  • Organization provisioning
  • Tenant lifecycle management
  • Support and incident response
  • Security investigations
  • Operational maintenance

Platform administration is distinct from ordinary organization membership and organization-scoped administration.

For example, an administrator of Organization A must not automatically receive platform-level privileges.

Likewise, a platform operator must not automatically receive unrestricted access to all organization-owned business data merely by holding an operational role.

Privileged capabilities must be explicitly authorized and limited to their intended purpose.

Access to organization-owned data for support or investigation must follow defined privileged access controls.

Such access must be auditable.

Platform-level operations must require explicit authorization and clearly defined access scopes. Missing organization context must never be interpreted as permission to bypass tenant isolation or access organization-owned resources across tenants.

Membership and Permission Changes Must Take Effect Safely

Organization membership, roles, and permissions may change while users or workloads remain authenticated.

Examples include:

  • A user being removed from an organization
  • An administrator losing elevated privileges
  • A suspended membership
  • A service losing permission to invoke an internal API
  • A compromised identity being revoked

The authorization architecture must account for changes to permissions and membership after initial authentication.

A previously issued authentication credential must not be treated as permanent proof that organization membership and permissions remain valid.

The implementation must define an acceptable authorization freshness model, including appropriate handling of:

  • Credential expiration
  • Credential revocation
  • Session termination
  • Membership changes
  • Role changes
  • Authorization caching
  • Permission propagation delays
  • Long-running workflows

Security-sensitive changes may require stronger freshness or revocation guarantees than ordinary operations.

The exact mechanisms and acceptable propagation delays will be defined separately.

Authorization Must Fail Securely

Protected operations must fail closed when required authentication, organization context, or authorization information is unavailable, invalid, or untrusted.

Examples include:

  • Missing authentication
  • Invalid credentials
  • Expired or revoked credentials
  • Unknown organization
  • Missing organization membership
  • Suspended membership
  • Unauthorized organization selection
  • Insufficient permissions
  • Resource ownership mismatch
  • Untrusted service identity
  • Invalid delegated identity
  • Untrusted event origin
  • Unavailable required authorization information

Authorization failures must not result in fallback access to another organization or unrestricted platform scope.

If an authorization dependency is unavailable or fails, protected operations must not proceed unless authorization can still be established through a trusted and explicitly permitted mechanism. An authorization failure or inability to verify permissions must never result in unrestricted access.

Error responses must avoid disclosing unauthorized organization or resource information.

Where appropriate, the system may avoid revealing whether a resource exists when the caller is not authorized to access it.

Authorization Decisions Must Be Auditable

Security-sensitive operations must produce sufficient audit information to support investigation, accountability, and compliance requirements.

Relevant activities may include:

  • Authentication failures
  • Organization membership changes
  • Role and permission assignments
  • Privileged administrative actions
  • Access denials
  • Security-sensitive resource modifications
  • Changes to service permissions
  • Organization lifecycle operations

Audit information should identify, where appropriate:

  • Acting principal
  • Principal type
  • Organization context
  • Requested action
  • Target resource
  • Authorization outcome
  • Timestamp
  • Correlation or trace identifier
  • Relevant privileged access context

Audit records must avoid unnecessarily exposing credentials, secrets, or sensitive business data.

Audit access must itself be authorized and tenant-aware.

Detailed audit storage, retention, and integrity requirements will be defined separately.

Rationale

Separate Identity from Authorization

Authentication establishes identity, while authorization determines permitted actions.

Separating these concerns prevents authenticated principals from being treated as universally authorized.

Support Multi-Organization Users

Explicit organization membership and context allow users to access multiple organizations without mixing their roles, permissions, or business data.

Preserve Tenant Isolation

Organization-scoped authorization ensures that valid permissions do not override resource ownership boundaries.

Preserve Service Autonomy

Business services remain responsible for protecting their capabilities and operational data.

Support Distributed Workloads

Explicit workload identities and authorization scopes allow synchronous service calls, background jobs, and event consumers to operate without bypassing security boundaries.

Enable Controlled Administration

Separating platform-level privileges from organization-scoped administration reduces the risk of unrestricted tenant access.

Support Future Security Evolution

Keeping identity provider and policy implementation choices separate allows the platform to evolve authentication and authorization technologies without changing its foundational security model.

Alternatives Considered

Alternative 1: Authentication Without Organization-Aware Authorization

Authenticate users and services, then allow access based primarily on identity.

Advantages

  • Simpler initial implementation
  • Fewer authorization concepts
  • Lower initial configuration overhead

Disadvantages

  • Does not adequately enforce tenant boundaries
  • Cannot represent organization-specific permissions
  • Risks treating authenticated users as universally authorized
  • Poor support for users belonging to multiple organizations

Reason Not Selected

Authentication alone does not establish authorization or organization ownership.

Alternative 2: Global Roles Shared Across Organizations

Assign roles to users globally and apply those roles across all organizations.

Advantages

  • Simple role assignment
  • Straightforward initial permission checks
  • Fewer membership-specific role records

Disadvantages

  • Cannot adequately represent different responsibilities in different organizations
  • Risks granting excessive cross-organization privileges
  • Conflicts with tenant-scoped administration
  • Limits flexibility for multi-organization users

Reason Not Selected

Zelvoryqa requires organization-specific permissions and must preserve independent tenant boundaries.

Alternative 3: Gateway-Only Authorization

Perform authentication and authorization at the API Gateway and trust all downstream requests.

Advantages

  • Centralized enforcement
  • Less authorization logic in business services
  • Simple external request flow

Disadvantages

  • Does not adequately protect direct service-to-service calls
  • Does not cover background jobs and event consumers
  • Creates reliance on a single enforcement boundary
  • Risks bypassing service-owned resource authorization
  • Weakens defense in depth

Reason Not Selected

Business services must enforce the authorization and ownership requirements applicable to their own capabilities and resources.

Alternative 4: Organization-Aware Identity and Authorization

Separate authentication, organization membership, organization context, authorization, and tenant isolation.

Enforce authorization at the relevant service boundaries using trusted identity and organization information.

Advantages

  • Supports multi-organization users
  • Supports organization-specific roles and permissions
  • Preserves tenant isolation
  • Protects internal service boundaries
  • Supports workload and delegated identities
  • Separates platform and organization administration
  • Enables auditable access decisions

Disadvantages

  • More complex than authentication-only approaches
  • Requires organization membership management
  • Requires consistent authorization enforcement
  • Introduces permission lifecycle and revocation considerations
  • Requires secure context propagation across distributed workflows
  • Adds testing and operational responsibilities

Reason Selected

This approach provides the security model required for Zelvoryqa to operate as a multi-tenant SaaS platform with independently deployed services and distributed workflows.

Consequences

Positive Consequences

  • Authentication and authorization responsibilities are clearly separated.
  • Users may belong to multiple organizations.
  • Organization-scoped roles and permissions are supported.
  • Organization context must be established before accessing tenant-owned resources.
  • Resource ownership remains enforceable independently of role permissions.
  • Internal services and background workloads have explicit security requirements.
  • Platform administration is separated from organization administration.
  • Security-sensitive operations can be audited.
  • Identity and authorization implementations can evolve independently of the architectural model.

Negative Consequences

  • Organization membership and authorization require additional implementation complexity.
  • Services must consistently enforce authorization and resource ownership.
  • Distributed workflows require trusted context propagation.
  • Permission changes and revocation require defined consistency guarantees.
  • Authorization checks may introduce additional latency.
  • Authorization caching must be carefully controlled.
  • Privileged platform operations require additional safeguards.
  • Security testing must cover multiple identities, organizations, roles, and execution paths.

Risks

  • Inconsistent authorization logic across services
  • Trusting client-supplied organization identifiers
  • Cross-tenant resource access
  • Overly broad service permissions
  • Unauthorized service impersonation
  • Stale membership or permission information
  • Delayed revocation
  • Excessively privileged platform operators
  • Missing authorization checks in background processing
  • Untrusted event context
  • Sensitive information exposed through errors or logs
  • Incomplete audit coverage

Implementation Considerations

Future implementation must define:

  • Identity provider selection
  • Authentication protocols
  • User identity representation
  • Workload identity mechanisms
  • Credential and token formats
  • Credential validation
  • Session management
  • Organization membership data model
  • Organization selection workflow
  • Organization-scoped roles and permissions
  • Resource-level authorization policies
  • Authorization policy evaluation
  • Delegated user authorization
  • Service-to-service authorization
  • Trusted organization context propagation
  • Authorization caching and freshness
  • Membership and permission revocation
  • Administrative access controls
  • Audit logging
  • Security monitoring
  • Authorization testing
  • Identity and organization lifecycle APIs

Implementation choices must preserve the requirements established by this ADR.

Operational Considerations

Identity and authorization systems are security-critical platform dependencies.

Operational monitoring must support investigation of:

  • Authentication failures
  • Authorization denials
  • Membership and role changes
  • Credential expiration and revocation
  • Service authentication failures
  • Invalid organization context
  • Suspicious cross-organization access attempts
  • Privileged administrative activity
  • Authorization dependency failures

Authorization failures should be distinguishable from ordinary business validation failures without exposing sensitive information to unauthorized callers.

Operational procedures must account for:

  • Identity provider outages
  • Authorization dependency outages
  • Credential compromise
  • Service identity compromise
  • Membership removal
  • Privilege revocation
  • Organization suspension
  • Security incident response
  • Recovery of identity and authorization configuration

Protected operations must not silently bypass authorization when required security dependencies are unavailable.

Organization identifiers and relevant security context may be included in structured logs and distributed traces where appropriate.

Sensitive credentials, secrets, and unnecessary personal information must not be recorded in logs or traces.

Organization identifiers should not be added indiscriminately as metric labels because unbounded organization-level dimensions may increase metric cardinality and operational cost.

Platform operators may require access to security and audit information for incident response.

Such access must be explicitly authorized, appropriately scoped, and auditable.

Validation

This decision will be considered successfully implemented when Zelvoryqa can demonstrate that:

  • Protected operations require appropriate authentication.
  • Authentication does not automatically grant organization access.
  • Users can belong to multiple organizations.
  • Users can hold different roles in different organizations.
  • Organization context is explicitly established and validated.
  • Client-supplied organization identifiers do not grant access by themselves.
  • Organization-scoped operations fail when valid organization context is missing.
  • Authorization considers the requested action and applicable resource ownership.
  • Organization A users cannot access Organization B resources without an explicitly authorized capability.
  • Business services enforce their own authorization requirements.
  • API Gateway checks do not replace service-level enforcement.
  • Internal service calls use authenticated workload identities.
  • Service authentication does not grant unrestricted tenant access.
  • Delegated user operations preserve appropriate authorization context.
  • Background jobs and event consumers enforce organization boundaries.
  • Platform administration is distinct from organization administration.
  • Privileged access requires explicit authorization.
  • Membership removal and permission changes are enforced according to the defined freshness policy.
  • Invalid or unavailable authorization information does not result in unrestricted access.
  • Authorization failures do not disclose unauthorized organization data.
  • Security-sensitive operations produce appropriate audit records.
  • Audit information is protected by authorization controls.
  • Authorization behavior is covered by automated tests.

Follow-Up

The following architectural decision builds on this ADR:

  • ADR-0007: Define API Gateway and External API Architecture

Additional later decisions will define:

  • Identity provider and authentication protocol selection
  • Workload identity and secrets management
  • Organization membership and role data models
  • Authorization policy implementation
  • Session and credential lifecycle management
  • Service-to-service identity propagation
  • Audit logging and retention
  • Privileged platform access
  • Security monitoring and incident response
  • Rate limiting, quotas, and tenant fairness

References

  • ADR-0001: Adopt Microservices Based on Business Capabilities
  • ADR-0002: Adopt Multi-Tenant SaaS Architecture
  • ADR-0003: Define Service Data Ownership and Tenant Data Isolation
  • ADR-0004: Adopt Event-Driven Integration
  • ADR-0005: Define Synchronous Service Communication
  • Zelvoryqa Architecture Overview
  • Zelvoryqa Product Vision
  • Zelvoryqa Goals

Status Definitions

  • Proposed — The decision is under review.
  • Accepted — The decision has been approved and should guide implementation.
  • Deprecated — The decision is no longer recommended but remains for historical context.
  • Superseded — The decision has been replaced by a newer ADR.

ADR Guidelines

This ADR records one significant architectural decision.

The ADR should:

  • Explain the context that required the decision.
  • State the decision clearly.
  • Document the reasoning behind the decision.
  • Record meaningful alternatives and tradeoffs.
  • Separate durable architectural requirements from implementation details.
  • Avoid selecting technologies that belong in later decisions.
  • Be superseded rather than rewritten when the architectural decision fundamentally changes.