ums

Tenant — Arquitectura del Agregado

Idioma: English Español

Bounded Context: Identity Aggregate Root: Tenant Modulo: Ums.Domain.Identity.Tenant Estado: Produccion

1. Descripcion del Agregado

Proposito

Tenant es la unidad organizativa raiz del sistema. Representa a una empresa o division que usa UMS como plataforma de gestion de identidades. Agrupa a todos los usuarios, ramas (Branch), configuraciones de branding (Branding) y proveedores de identidad (IdentityProvider) bajo un espacio de nombres unico y aislado.

Responsabilidad de Negocio

Proveer aislamiento multi-tenant para todos los datos del sistema.
Gestionar el ciclo de vida del tenant: registro, suspension y activacion.
Ser el propietario de Branch, Branding e IdentityProvider como entidades propias.
Definir la estrategia de autenticacion (IdpStrategy) a nivel de dominio.

Branch: Representa una unidad de ubicacion fisica o logica. Provee un ambito geográfico u organizacional. Aplica reglas de geocercado y habilita delegación de administración. Branding: Contiene la configuración de identidad visual (logo, colores, textos) y dominio personalizado con verificación DNS. Controla cómo se renderiza el portal de login. IdentityProvider: Representa un proveedor de autenticación externo (OIDC, SAML2, WS_FED). Registra la intención estratégica y el contrato a nivel de negocio para el tenant.

Aggregate Root

Tenant es su propio aggregate root. Todas las mutaciones de Branch, Branding e IdentityProvider pasan por comandos de Tenant.

Invariantes y Reglas de Consistencia

Tenant: Code debe ser globalmente unico en todo el sistema.
Tenant: Un Tenant con TenantStatus = Suspended bloquea todos los flujos de autenticacion de sus usuarios.
Tenant: IdpStrategy debe ser coherente: si es FEDERATED, debe existir al menos un IdentityProvider activo.
Tenant: Un tenant hijo (ParentTenantId != null) hereda politicas del tenant padre.
Branch: Code debe ser unico dentro del Tenant propietario.
Branch: Una Branch no puede ser eliminada si existen registros activos de UserAccount o Profile asociados.
Branch: GeofencingMetadata debe ser JSON valido cuando se proporciona.
Branch: La desactivacion no elimina; los registros se conservan para trazabilidad historica.
Branding: Solo puede existir un registro Branding por Tenant (relacion 1:1).
Branding: CustomDomain debe ser un hostname valido cuando se proporciona.
Branding: DnsVerificationStatus comienza en PENDING cuando se establece CustomDomain y no puede establecerse manualmente a VERIFIED (solo por el servicio de verificacion DNS).
Branding: LogoFormat debe coincidir con el formato real del URI de Logo subido.
IdentityProvider: Code debe ser unico dentro del Tenant propietario.
IdentityProvider: Un IdentityProvider debe ser desactivado antes de ser eliminado.
IdentityProvider: Desactivar un IdentityProvider que es el unico IdP activo para un tenant Federado no esta permitido a menos que se cambie primero el IdpStrategy.
IdentityProvider: Strategy no puede cambiarse despues del registro — es inmutable una vez establecida.

Entidades Relacionadas / Value Objects

Eventos de Dominio

Comandos / Casos de Uso

Limites de Repositorio / Servicio

Acceso via ITenantRepository.
IBranchDependencyChecker — servicio de dominio para validar dependencias antes de eliminar rama.
IIdpStrategyConsistencyService — valida que la desactivacion de un IdP no deje al tenant sin ruta de autenticacion.

2. Modelo de Objetos

Tenant (Aggregate Root)
├── Props: TenantProps
│   ├── Id: IdValueObject
│   ├── Code: Code
│   ├── Name: Name
│   ├── OrganizationType: OrganizationType
│   ├── IdpStrategy: IdpStrategy
│   ├── CompanyReference?: CompanyReference
│   ├── ParentTenantId?: TenantId
│   ├── Status: TenantStatus
│   └── Audit: AuditValueObject
├── Branch (Entidad Propia, 0..N)
│   └── Props: BranchProps
│       ├── Id: IdValueObject
│       ├── TenantId: TenantId
│       ├── Code: Code
│       ├── Name: Name
│       ├── GeofencingMetadata?: Value (JSON)
│       ├── IsActive: bool
│       └── Audit: AuditValueObject
├── Branding (Entidad Propia, 0..1)
│   └── Props: BrandingProps
│       ├── Id: IdValueObject
│       ├── TenantId: TenantId
│       ├── Logo: Logo
│       ├── LogoFormat: LogoFormat
│       ├── PrimaryColor: HexColor
│       ├── BackgroundStyle: BackgroundStyle
│       ├── HeadlineText: LoginText
│       ├── SecondaryText: LoginText
│       ├── PrimaryButtonLabel: LoginText
│       ├── FooterText: LoginText
│       ├── CustomDomain?: CustomDomain
│       ├── DnsVerificationStatus: DnsVerificationStatus
│       ├── DnsCnameTarget: DnsCnameTarget
│       ├── MagicLinkFallbackEnabled: bool
│       └── Audit: AuditValueObject
└── IdentityProvider (Entidad Propia, 0..N)
    └── Props: IdentityProviderProps
        ├── Id: IdValueObject
        ├── TenantId: TenantId
        ├── Code: Code
        ├── Name: Name
        ├── Description: Description
        ├── Strategy: IdpStrategy
        ├── IsActive: bool
        └── Audit: AuditValueObject

Ciclo de Vida

Tenant:

Active ──► Suspended ──► Active
Active ──► Inactive (terminal)

Branch:

Activo (IsActive = true) ──► Desactivado (IsActive = false) ──► Activo
                                     └──► Eliminado (si no tiene dependientes)

Branding (DNS):

(CustomDomain establecido) -> DnsVerificationStatus = Pending
                                 ├──► Verified  (CNAME DNS coincide)
                                 └──► Failed    (CNAME faltante o incorrecto)
                                         └──► Pending (en reintento)

IdentityProvider:

Registrado (IsActive = false) ──► Activado (IsActive = true) ──► Desactivado ──► Eliminado

3. Diagramas de Secuencia

Flujo: Registrar Tenant

sequenceDiagram
    participant C as Cliente
    participant H as RegisterTenantHandler
    participant R as ITenantRepository

    C->>H: RegisterTenantCommand(code, name, orgType, idpStrategy, createdBy)
    H->>R: ExistsByCode(code)
    R-->>H: false
    H->>H: Crear Tenant (Status = Active)
    H->>H: Emitir TenantCreatedEvent
    H->>R: Add(tenant)
    H-->>C: tenantId

Flujo: Suspender Tenant

sequenceDiagram
    participant C as Cliente
    participant H as SuspendTenantHandler
    participant R as ITenantRepository
    participant T as Tenant (AR)

    C->>H: SuspendTenantCommand(tenantId, actorId)
    H->>R: GetById(tenantId)
    R-->>H: Tenant
    H->>T: tenant.Suspend(actorId)
    T->>T: Guardia: Status debe ser Active
    T->>T: Status = Suspended
    T->>T: Emitir TenantSuspendedEvent
    H->>R: Update(tenant)
    H-->>C: void

Flujo: Agregar Rama

sequenceDiagram
    participant C as Cliente
    participant H as AddBranchHandler
    participant R as ITenantRepository
    participant T as Tenant (AR)

    C->>H: AddBranchCommand(tenantId, code, name, geofencing?)
    H->>R: GetById(tenantId)
    R-->>H: Tenant
    H->>T: tenant.AddBranch(branchId, code, name, geofencing, createdBy)
    T->>T: Guardia: code unico dentro del tenant
    T->>T: Guardia: tenant activo
    T->>T: Crear Branch (IsActive = true)
    T->>T: Emitir BranchCreatedEvent
    H->>R: Update(tenant)
    H-->>C: BranchId

Flujo: Eliminar Rama

sequenceDiagram
    participant C as Cliente
    participant H as RemoveBranchHandler
    participant R as ITenantRepository
    participant T as Tenant (AR)
    participant D as IBranchDependencyChecker

    C->>H: RemoveBranchCommand(tenantId, branchId, actorId)
    H->>D: HasDependents(branchId)
    D-->>H: false
    H->>R: GetById(tenantId)
    R-->>H: Tenant
    H->>T: tenant.RemoveBranch(branchId, actorId)
    T->>T: Eliminar Branch de coleccion
    T->>T: Emitir BranchRemovedEvent
    H->>R: Update(tenant)
    H-->>C: void

Flujo: Configurar Branding

sequenceDiagram
    participant C as Cliente
    participant H as ConfigureBrandingHandler
    participant R as ITenantRepository
    participant T as Tenant (AR)
    participant DNS as IDnsVerificationService

    C->>H: ConfigureBrandingCommand(tenantId, logo, colores, textos, customDomain?)
    H->>R: GetById(tenantId)
    R-->>H: Tenant
    H->>T: tenant.ConfigureBranding(props, createdBy)
    T->>T: Guardia: Branding no debe existir
    T->>T: Crear Branding (DnsVerificationStatus = Pending si customDomain)
    T->>T: Emitir BrandingCreatedEvent
    H->>R: Update(tenant)
    alt customDomain proporcionado
        H->>DNS: ScheduleVerification(tenantId, cnameTarget, customDomain)
    end
    H-->>C: BrandingId

Flujo: Verificacion DNS (Branding)

sequenceDiagram
    participant DNS as IDnsVerificationService
    participant H as MarkDnsVerifiedHandler
    participant R as ITenantRepository
    participant T as Tenant (AR)

    DNS->>H: MarkDnsVerifiedCommand(tenantId, brandingId)
    H->>R: GetById(tenantId)
    R-->>H: Tenant
    H->>T: tenant.MarkDnsVerified(brandingId)
    T->>T: Branding.DnsVerificationStatus = Verified
    T->>T: Emitir BrandingDnsVerifiedEvent
    H->>R: Update(tenant)
    DNS-->>H: ok

Flujo: Registrar IdP

sequenceDiagram
    participant C as Cliente
    participant H as RegisterIdpHandler
    participant R as ITenantRepository
    participant T as Tenant (AR)

    C->>H: RegisterIdentityProviderCommand(tenantId, code, name, description, strategy, createdBy)
    H->>R: GetById(tenantId)
    R-->>H: Tenant
    H->>T: tenant.RegisterIdentityProvider(idpId, code, name, description, strategy, createdBy)
    T->>T: Guardia: code unico dentro del tenant
    T->>T: Crear IdentityProvider (IsActive = false)
    T->>T: Emitir IdentityProviderRegisteredEvent
    H->>R: Update(tenant)
    H-->>C: IdpId

Flujo: Activar IdP

sequenceDiagram
    participant C as Cliente
    participant H as ActivateIdpHandler
    participant R as ITenantRepository
    participant T as Tenant (AR)
    participant SVC as IIdpStrategyConsistencyService

    C->>H: ActivateIdentityProviderCommand(tenantId, idpId, actorId)
    H->>SVC: ValidateActivation(tenantId, idpId)
    SVC-->>H: valido
    H->>R: GetById(tenantId)
    R-->>H: Tenant
    H->>T: tenant.ActivateIdentityProvider(idpId, actorId)
    T->>T: Buscar IdP en coleccion
    T->>T: IdP.IsActive = true
    T->>T: Emitir IdentityProviderActivatedEvent
    H->>R: Update(tenant)
    H-->>C: void

4. Modelo Entidad-Relacion

erDiagram
    TENANT ||--o{ BRANCH : "opera"
    TENANT ||--o| BRANDING : "configura"
    TENANT ||--o{ IDENTITY_PROVIDER : "registra"
    TENANT ||--o{ USER_ACCOUNT : "tiene"
    TENANT |o--o{ TENANT : "es_padre_de"
    BRANCH ||--o{ USER_ACCOUNT : "alcance"
    BRANCH ||--o{ PROFILE : "contexto_para"
    IDENTITY_PROVIDER ||--o{ IDP_CONFIGURATION : "configured_by"

    TENANT {
        uniqueidentifier TenantId PK
        nvarchar Code "Unico global"
        nvarchar Name
        nvarchar OrganizationType "COMPANY-DIVISION-BRANCH_OFFICE"
        nvarchar IdpStrategy "LOCAL-FEDERATED-HYBRID"
        nvarchar CompanyReference "Nullable"
        uniqueidentifier ParentTenantId "Nullable FK"
        nvarchar Status "ACTIVE-SUSPENDED-INACTIVE"
        datetime2 CreatedAt
        uniqueidentifier CreatedBy
        datetime2 UpdatedAt
        uniqueidentifier UpdatedBy
    }

    BRANCH {
        uniqueidentifier BranchId PK
        uniqueidentifier TenantId FK
        nvarchar Code "Unico por TenantId"
        nvarchar Name
        nvarchar GeofencingMetadata "JSON Nullable"
        bit IsActive
        datetime2 CreatedAt
        uniqueidentifier CreatedBy
        datetime2 UpdatedAt
        uniqueidentifier UpdatedBy
    }

    BRANDING {
        uniqueidentifier BrandingId PK
        uniqueidentifier TenantId FK "Unico - 1:1"
        nvarchar Logo "URI Storage Path"
        nvarchar LogoFormat "PNG-SVG-JPEG"
        nvarchar PrimaryColor "Hex Color"
        nvarchar BackgroundStyle "Glassmorphism-SleekDark"
        nvarchar HeadlineText
        nvarchar SecondaryText
        nvarchar PrimaryButtonLabel
        nvarchar FooterText
        nvarchar CustomDomain "FQDN Nullable"
        nvarchar DnsVerificationStatus "PENDING-VERIFIED-FAILED"
        nvarchar DnsCnameTarget "CNAME de Plataforma"
        bit MagicLinkFallbackEnabled
        datetime2 CreatedAt
        uniqueidentifier CreatedBy
        datetime2 UpdatedAt
        uniqueidentifier UpdatedBy
    }

    IDENTITY_PROVIDER {
        uniqueidentifier IdpId PK
        uniqueidentifier TenantId FK
        nvarchar Code "Unico por TenantId"
        nvarchar Name
        nvarchar Description
        nvarchar Strategy "OIDC-SAML2-WS_FED"
        bit IsActive
        datetime2 CreatedAt
        uniqueidentifier CreatedBy
        datetime2 UpdatedAt
        uniqueidentifier UpdatedBy
    }

5. Modelo de Bounded Context

flowchart TD
    subgraph Identity["Identity BC"]
        T[Tenant AR]
        B[Branch Entity]
        BR[Branding Entity]
        IDP[IdentityProvider Entity]
        UA[UserAccount AR]
        T --> B
        T --> BR
        T --> IDP
        UA -->|TenantId| T
        UA -->|BranchId opcional| B
    end

    subgraph Authorization["Authorization BC"]
        PROF[Profile AR]
        PROF -->|BranchId alcance opcional| B
    end

    subgraph Configuration["Configuration BC"]
        IDPC[IdpConfiguration AR]
    end

    subgraph Infrastructure["Infrastructure"]
        DNS[DNS Verification Service]
        STORE[File Storage - Logo URI]
        EXTIDP[IdP Externo - Azure AD, Okta]
    end

    subgraph Audit["Audit BC"]
        AUD[AuditRecord]
    end

    IDP -->|IdentityProviderRegisteredEvent| IDPC
    IDP -->|IdentityProviderDeactivatedEvent| IDPC
    EXTIDP -->|Contrato de Protocolo| IDP
    DNS -->|MarkDnsVerifiedCommand| BR
    DNS -->|MarkDnsFailedCommand| BR
    STORE -->|Logo URI almacenado| BR
    T -->|eventos de dominio| AUD
    B -->|eventos de dominio| AUD
    BR -->|eventos de dominio| AUD
    IDP -->|eventos de dominio| AUD

6. Contrato de Capa de Aplicacion

Comandos

Consultas

Casos de Error

7. Notas de Persistencia

Indices

Consideraciones Multi-Tenant

Todas las consultas de entidades hijas deben estar filtradas por TenantId.
Code en Tenant es clave unica global — no por tenant.
CustomDomain unico entre todos los tenants (un dominio no puede ser reclamado por dos tenants).

8. Seguridad y Auditoria

Reglas de Autorizacion

Eventos de Auditoria

Tenant: TENANT_CREATED, TENANT_SUSPENDED, TENANT_ACTIVATED
Branch: BRANCH_CREATED, BRANCH_DEACTIVATED, BRANCH_REACTIVATED, BRANCH_REMOVED
Branding: BRANDING_CONFIGURED, BRANDING_UPDATED, BRANDING_REMOVED, DNS_VERIFIED, DNS_FAILED
IdentityProvider: IDP_REGISTERED, IDP_ACTIVATED, IDP_DEACTIVATED, IDP_REMOVED

Datos Sensibles

IdentityProvider en si no almacena credenciales. Los secretos viven en IDP_CONFIGURATION.SecretRef (ruta al vault).

This site is open source. Improve this page.