key-cape/spec/canonical-model.yaml

version: "0.1"
description: >
  Canonical Identity Model for KeyCape / NetKingdom IAM Profile.
  This file is the source of truth for all identity entities.
  All provisioning, tests, and migrations derive from these definitions.

entities:
  User:
    description: "A person or service account in the identity directory."
    fields:
      id:
        type: string
        required: true
        description: "Stable internal identifier. Immutable after creation."
      username:
        type: string
        required: true
        description: "Unique login name. Maps to LDAP uid."
      displayName:
        type: string
        required: true
        description: "Human-readable full name. Maps to LDAP cn."
      email:
        type: string
        required: false
        format: email
        description: "Primary email address. Maps to LDAP mail."
      enabled:
        type: boolean
        required: true
        description: "Whether the account is active."
      groups:
        type: array
        items:
          type: string
          ref: Group.id
        description: "Group memberships by group ID."
      roles:
        type: array
        items:
          type: string
          ref: Role.id
        description: "Role assignments by role ID."
      mfaEnrollment:
        type: object
        ref: MFAEnrollment
        nullable: true
        description: "MFA enrollment record if the user has enrolled."
      ldapAttributes:
        type: object
        additionalProperties: true
        description: "Raw LDAP attributes not covered by the canonical model."

  Group:
    description: "A named collection of users."
    fields:
      id:
        type: string
        required: true
        description: "Stable internal identifier."
      name:
        type: string
        required: true
        description: "Unique group name. Maps to LDAP cn."
      description:
        type: string
        required: false
        description: "Human-readable description."
      members:
        type: array
        items:
          type: string
          ref: User.id
        description: "User IDs belonging to this group."

  Role:
    description: "A named permission set assigned to users."
    fields:
      id:
        type: string
        required: true
        description: "Stable internal identifier."
      name:
        type: string
        required: true
        description: "Unique role name."
      description:
        type: string
        required: false
        description: "Human-readable description."

  Client:
    description: "A registered OIDC client. Registration is static in v0.1."
    fields:
      clientId:
        type: string
        required: true
        description: "OAuth2 client_id."
      displayName:
        type: string
        required: true
        description: "Human-readable client name."
      redirectUris:
        type: array
        items:
          type: string
          format: uri
        required: true
        minItems: 1
        description: "Allowed redirect URIs. Wildcards are NEVER permitted."
      allowedScopes:
        type: array
        items:
          type: string
        required: true
        description: "Scopes this client may request."
      grantTypes:
        type: array
        items:
          type: string
          enum: [authorization_code]
        required: true
        description: "Allowed OAuth2 grant types. Only authorization_code in v0.1."
      clientType:
        type: string
        enum: [confidential, public]
        required: true
        description: "confidential = server-side app; public = SPA or native."
      secretRef:
        type: string
        nullable: true
        description: "Reference to the client secret (confidential clients only)."
      tokenProfile:
        type: string
        description: "Optional: token configuration profile name."
      environments:
        type: array
        items:
          type: string
        description: "Environments this client is registered for (e.g. prod, staging)."

  Membership:
    description: "Explicit link between a user and a group."
    fields:
      userId:
        type: string
        required: true
        ref: User.id
      groupId:
        type: string
        required: true
        ref: Group.id

  MFAEnrollment:
    description: "Records MFA enrollment state for a user via privacyIDEA."
    fields:
      userId:
        type: string
        required: true
        ref: User.id
      provider:
        type: string
        required: true
        enum: [privacyidea]
        description: "MFA provider. Only privacyidea is supported in v0.1."
      state:
        type: string
        required: true
        enum: [enabled, disabled, pending]
        description: "Current enrollment state."
      enrolledAt:
        type: string
        format: datetime
        description: "ISO 8601 timestamp of enrollment."