ums

UserAccount — Aggregate Architecture

Bounded Context: Identity
Aggregate Root: UserAccount
Module: Ums.Domain.Identity.UserAccount
Status: Production

1. Aggregate Overview

Purpose

The UserAccount aggregate represents a user’s identity within a tenant. It governs registration, activation, blocking, external IdP linkage, password credential management, and MFA enrollment. It is the primary identity object referenced by all other bounded contexts. It fully owns the PasswordCredential and MfaEnrollment child entities.

Delegated Administration: A UserAccount with an administrative role may receive a UserManagementDelegation from another administrator, granting them the authority to manage a restricted set of users within a defined scope (tenant, organization, department, system, or team). This authority is enforced at the application layer by checking for an ACTIVE delegation before processing restricted commands. See UserManagementDelegation · FS-14.

Business Responsibility

Register users within a tenant, assigning them a category and email.
Track lifecycle: Pending → Active → Blocked → Active.
Link users to an external identity reference from an authoritative source system (HR, vendor, government, partner), while authentication protocol selection remains governed by tenant/provider strategy.
Own PasswordCredential and MfaEnrollment child entities.
Emit authentication-related domain events (auth attempted, MFA enrolled/verified).

Aggregate Root

UserAccount is the aggregate root. PasswordCredential and MfaEnrollment must be managed exclusively through UserAccount commands. External aggregates hold UserId references only.

Invariants and Consistency Rules

Email must be unique per TenantId.
A UserAccount in status Blocked cannot authenticate.
A UserAccount in status Pending has no active PasswordCredential.
At most one PasswordCredential can be IsActive = true at any time.
Setting a new password automatically deactivates the previous active credential.
Historical credentials (IsActive = false) are retained for audit — never physically deleted.
PasswordHash must be a valid BCrypt hash (validated by domain service before assignment).
IdentityReference and IdentityReferenceType must be set together or both null.
A FEDERATED user (has IdentityReference) should not have an active PasswordCredential.
Multiple MfaEnrollment records may exist (one per method), but each method may only be enrolled once per user.
MFA enrollment status values follow the implemented model: NotEnrolled, Enrolled, Verified. New enrollments start in Enrolled and move to Verified once the challenge is confirmed.
UserAccount.Status must not be Blocked to enroll a new MFA method.
At least one enrolled MFA method must remain if the tenant requires MFA.
A UserAccount acting as a delegated admin may only execute management commands (RegisterUserCommand, BlockUserCommand, AssignProfileCommand) on users within their ACTIVE delegation scope — validated by IDelegationScopeValidator at application layer.
A UserAccount cannot delegate authority it does not itself possess (no-elevation rule — INV-DEL1).

Domain Events

Commands / Use Cases

Repository / Service Boundaries

IUserAccountRepository — persists UserAccount aggregate including owned credentials and enrollments.
IPasswordHashingService — domain service for BCrypt hashing.
IEmailUniquenessChecker — domain service to verify email uniqueness within a tenant.
IMfaChallengeService — infrastructure service handling OTP generation/TOTP validation.
IDelegationScopeValidator — application service; validates that the acting admin has an ACTIVE UserManagementDelegation covering the target user and requested action before processing delegation-gated commands.

2. Object Model

Classes / Entities / Value Objects

UserAccount (Aggregate Root)
├── Props: UserAccountProps
│   ├── Id: IdValueObject
│   ├── TenantId: TenantId
│   ├── BranchId?: BranchId
│   ├── Email: Email
│   ├── Category: UserCategory
│   ├── Status: UserStatus
│   ├── IdentityReference?: IdentityReference
│   ├── IdentityReferenceType?: IdentityReferenceType
│   └── Audit: AuditValueObject
├── Children
│   ├── PasswordCredential? (0..N stored, 0..1 active)
│   │   └── Props: PasswordCredentialProps (Id, UserAccountId, PasswordHash, IsActive)
│   └── IReadOnlyList<MfaEnrollment>
│       └── Props: MfaEnrollmentProps (Id, UserAccountId, Method, Status)
└── DomainEvents: UserAccountDomainEventsManager

Main Attributes

3. Sequence Diagrams

(Consolidated view covering core flows)

Register User Flow

sequenceDiagram
    participant C as Client
    participant H as RegisterUserHandler
    participant U as UserAccount (AR)
    participant R as IUserAccountRepository
    participant E as IEmailUniquenessChecker

    C->>H: RegisterUserCommand(...)
    H->>E: IsUnique(tenantId, email)
    E-->>H: true
    H->>U: UserAccount.Create(...)
    U->>U: Raise UserRegisteredEvent
    H->>R: Add(userAccount)
    H-->>C: UserId

Set Password Flow

sequenceDiagram
    participant C as Client
    participant H as SetPasswordHandler
    participant R as IUserAccountRepository
    participant U as UserAccount (AR)
    participant P as IPasswordHashingService

    C->>H: SetPasswordCommand(userId, plainPassword, actorId)
    H->>R: GetById(userId)
    R-->>H: UserAccount
    H->>P: Hash(plainPassword)
    P-->>H: passwordHash
    H->>U: userAccount.SetPassword(credentialId, passwordHash, actorId)
    U->>U: Deactivate existing PasswordCredential
    U->>U: Create new PasswordCredential (IsActive = true)
    H->>R: Update(userAccount)
    H-->>C: void

Enroll MFA Flow

sequenceDiagram
    participant C as Client
    participant H as EnrollMfaHandler
    participant R as IUserAccountRepository
    participant U as UserAccount (AR)
    participant MFA as IMfaChallengeService

    C->>H: EnrollMfaCommand(userId, method, actorId)
    H->>R: GetById(userId)
    R-->>H: UserAccount
    H->>U: userAccount.EnrollMfa(method, actorId)
    U->>U: Guard: method not already enrolled
    U->>U: Create MfaEnrollment (Status = Enrolled)
    U->>U: Raise MfaEnrolledEvent
    H->>R: Update(userAccount)
    H->>MFA: InitiateSetup(userId, method)
    MFA-->>H: setupToken
    H-->>C: enrollmentId, setupToken

4. Entity / Relationship Model

Relación con Delegación: USER_MANAGEMENT_DELEGATION contiene dos FK independientes hacia USER_ACCOUNT — una para cada rol (DelegatingAdminId = grantor, DelegatedAdminId = grantee). Esto es un dual self-join (auto-relación de roles), no una relación M:M clásica. Un mismo UserAccount puede aparecer simultáneamente como grantor en N delegaciones que otorgó y como grantee en M delegaciones que recibe. La circularidad directa (A→B y B→A activos a la vez) se bloquea vía IDelegationAuthorityChecker (INV-DEL5); la auto-delegación se bloquea con CHECK (DelegatingAdminId <> DelegatedAdminId) en BD (INV-DEL2).

erDiagram
    USER_ACCOUNT ||--o{ PASSWORD_CREDENTIAL        : "authenticates_with"
    USER_ACCOUNT ||--o{ MFA_ENROLLMENT             : "enrolls_mfa"
    USER_ACCOUNT }o--|| TENANT                     : "belongs_to"
    USER_ACCOUNT }o--o| BRANCH                     : "scoped_to"
    USER_ACCOUNT ||--o{ USER_MANAGEMENT_DELEGATION : "grants  (DelegatingAdminId)"
    USER_ACCOUNT ||--o{ USER_MANAGEMENT_DELEGATION : "receives (DelegatedAdminId)"

    USER_ACCOUNT {
        uniqueidentifier Id PK
        uniqueidentifier TenantId FK "RLS"
        uniqueidentifier BranchId FK "Nullable"
        nvarchar Email "Unique per TenantId"
        nvarchar Category "INTERNAL-EXTERNAL-B2B-PARTNER"
        nvarchar Status "PENDING-ACTIVE-BLOCKED"
        nvarchar IdentityReference "Nullable"
        nvarchar IdentityReferenceType "Nullable - HR_ID-VENDOR_CODE-GOVERNMENT_ID-PARTNER_REF"
        datetime2 CreatedAt
        uniqueidentifier CreatedBy
        datetime2 UpdatedAt
        uniqueidentifier UpdatedBy
    }

    PASSWORD_CREDENTIAL {
        uniqueidentifier Id PK
        uniqueidentifier UserAccountId FK
        nvarchar PasswordHash "BCrypt"
        bit IsActive "Only one active at a time"
        datetime2 CreatedAt
        uniqueidentifier CreatedBy
        datetime2 UpdatedAt
        uniqueidentifier UpdatedBy
    }

    MFA_ENROLLMENT {
        uniqueidentifier Id PK
        uniqueidentifier UserAccountId FK
        nvarchar Method "TOTP-SMS-EMAIL-WEBAUTHN"
        nvarchar Status "NOT_ENROLLED-ENROLLED-VERIFIED"
        datetime2 CreatedAt
        uniqueidentifier CreatedBy
        datetime2 UpdatedAt
        uniqueidentifier UpdatedBy
    }

    USER_MANAGEMENT_DELEGATION {
        uniqueidentifier Id PK
        uniqueidentifier TenantId FK "RLS"
        uniqueidentifier DelegatingAdminId FK "→ USER_ACCOUNT (grantor)"
        uniqueidentifier DelegatedAdminId FK "→ USER_ACCOUNT (grantee)"
        varchar ScopeTypeId "TENANT-ORGANIZATION-DEPARTMENT-SYSTEM-TEAM"
        uniqueidentifier ScopeId "Nullable — required when ScopeType ≠ TENANT"
        nvarchar AllowedActionsJson "JSON: CREATE_USER BLOCK_USER ASSIGN_PROFILE ..."
        datetimeoffset ValidFrom
        datetimeoffset ValidUntil
        int MaxDurationDays "Nullable"
        bit RequiresApproval
        uniqueidentifier ApprovalRequestId "Nullable FK"
        int StatusId "DRAFT-PENDING_APPROVAL-ACTIVE-REVOKED-EXPIRED-COMPLETED-REJECTED-ARCHIVED"
        datetimeoffset RevokedAt "Nullable"
        uniqueidentifier RevokedBy "Nullable FK → USER_ACCOUNT"
        nvarchar RevocationReason "Nullable"
        datetime2 CreatedAt
        uniqueidentifier CreatedBy
        datetime2 UpdatedAt
        uniqueidentifier UpdatedBy
    }

Nota INV-DEL2 / INV-DEL5: La tabla incluye CHECK (DelegatingAdminId <> DelegatedAdminId) en BD. La anti-circularidad (A→B no puede coexistir con B→A ACTIVE) se detecta en aplicación porque requiere buscar filas — los CHECK constraints de SQL no pueden hacer lookups cruzados. Ver UserManagementDelegation §7.

5. Bounded Context Model

flowchart TD
    subgraph Identity["Identity BC"]
        UA[UserAccount AR]
        PC[PasswordCredential]
        MFA[MfaEnrollment]
        UMD[UserManagementDelegation AR]
        UA --> PC
        UA --> MFA
        UMD -. "DelegatingAdminId\n(grantor FK)" .-> UA
        UMD -. "DelegatedAdminId\n(grantee FK)" .-> UA
    end

    subgraph Authorization["Authorization BC"]
        PROF[Profile]
    end

    subgraph Approvals["Approvals BC"]
        AR[ApprovalRequest]
        UD[UserDocument]
    end

    subgraph IGA["IGA BC"]
        PR[PromotionRequest]
        RMS[RoleMaturityStatus]
    end

    subgraph AppServices["Application Services"]
        HASH[IPasswordHashingService]
        TOTP[IMfaChallengeService]
        DSV[IDelegationScopeValidator]
        DAC[IDelegationAuthorityChecker]
    end

    UA  -->|UserRegisteredEvent| PROF
    UA  -->|UserId reference| AR
    UA  -->|UserId reference| UD
    UA  -->|UserId reference| PR

    DSV -->|"queries ACTIVE delegations"| UMD
    DSV -->|"gates RegisterUser / BlockUser\nAssignProfile commands"| UA
    DAC -->|"INV-DEL1: no elevation\nINV-DEL5: no circular"| UMD

    HASH -->|BCrypt hash| PC
    TOTP -->|OTP validation| MFA

    AR  -->|ApproveDelegationCommand| UMD

Dual self-join en Identity BC: UserManagementDelegation vive dentro del mismo BC que UserAccount pero es un AR independiente. Las dos FK (DelegatingAdminId, DelegatedAdminId) apuntan ambas a UserAccount — líneas punteadas en el diagrama. La validación de autoridad se hace por IDelegationScopeValidator (application service), no dentro del propio AR de UserAccount.

6. API / Application Layer Contract

Commands

Queries

7. Persistence Notes

Transaction Boundary

UserAccount, PasswordCredential, and MfaEnrollment are saved in a single SaveChanges() call.

Indexes

Security

PasswordHash column must never appear in query projections returned to clients.
PasswordHash must never appear in AuditRecord.WhatChanged payloads.
Column must be encrypted at rest (SQL Server Always Encrypted or TDE).

8. Security and Audit

Authorization Rules

Delegation Gate: When present, the handler also accepts requests from a UserAccount holding an ACTIVE UserManagementDelegation that covers the target user and the listed action. Validated by IDelegationScopeValidator before the command reaches the aggregate. See UserManagementDelegation.

Audit Events

USER_REGISTERED, USER_ACTIVATED, USER_BLOCKED, USER_RESTORED
PASSWORD_SET, MFA_ENROLLED, MFA_VERIFIED
AUTHENTICATION_ATTEMPTED (with AuditResult: SUCCESS/FAILURE)

This site is open source. Improve this page.

ums