Skip to main content

Identity Model

Summary​

Keymate models each user as a subject with a stable identifier, a set of profile attributes, and one or more organizational assignments. The identity model builds on the underlying identity server's user representation and extends it with organizational context, custom attributes, and multi-Tenant awareness. Every identity carries both its authentication state (how the user proved their identity) and its authorization context (which Organizations, departments, and roles the user can operate within).

Why It Exists​

Enterprise environments require more than a username and password record. A single user may belong to multiple Organizations, hold different roles in different departments, and carry custom attributes that influence authorization decisions. The identity model provides a unified representation that captures these dimensions, ensuring that downstream services receive a complete and consistent picture of the caller through token claims and introspection.

Where It Fits in Keymate​

The identity model sits at the foundation of the platform. Authentication flows establish the identity by verifying credentials. The organization model defines the Tenant and department structures that identities attach to. Token issuance assembles identity attributes into access token claims. Authorization policies evaluate decisions based on the identity's roles, attributes, and organizational context.

Boundaries​

This page covers the core identity representation — what an identity contains and how it relates to the broader platform. It does not cover:

How It Works​

Subject and Stable Identifier​

Every identity has a unique, stable identifier that persists across authentication sessions, Tenant assignments, and department switches. This identifier serves as the anchor point for all identity-related data — organizational assignments, attribute values, role bindings, and audit records reference this subject identifier.

Profile Attributes​

The identity carries a set of profile attributes that describe the user. These include standard attributes (name, email, contact information) and can be extended with custom attributes defined by administrators. Custom attributes support typed values, validation rules, and configurable visibility — administrators control which attributes appear in tokens, in the administrative interface, or in user-facing interfaces.

Organizational Assignments​

A user identity can hold assignments to one or more Organizations and departments within a Tenant. Each assignment links the identity to a specific position in the organizational hierarchy, carrying a set of roles and attributes scoped to that assignment. The identity's effective permissions depend on which assignment is active in the current session.

Authentication State​

The identity model tracks how the user authenticated — the method used, the time of authentication, and the session that resulted. This information feeds into session governance and enables downstream services to make freshness-based decisions. The platform supports multiple authentication methods, including credential-based login, external identity provider federation, and multi-factor authentication.

User Types​

The platform distinguishes between different user types to support varied authentication pathways and access patterns. Internal users, external partner users, and system-level service accounts each follow distinct authentication flows and carry different default permissions. The identity records the user type, which influences which authentication methods and session policies apply.

Diagram​

Example Scenario​

Scenario​

A user who holds assignments in two departments needs to access a service that requires department-specific authorization. The service reads the identity's active organizational context from the access token to determine which data the user can access.

Input​

  • Actor: User with assignments to both the Operations and Finance departments
  • Resource: A reporting service that scopes data by department
  • Action: Request department-specific financial report
  • Context: User has switched to the Finance department context via token exchange

Expected Outcome​

  • Granted — The service reads the Finance department context and associated roles from the token claims, confirms the user holds the required role, and returns the Finance report
  • Why: The identity model links the user to the Finance department assignment with the appropriate roles. Token exchange activated this context, and the access token carries the resulting claims.

Common Misunderstandings​

  • "A user can only belong to one Organization" — No. The identity model supports multiple organizational assignments per user. A user can hold positions in different departments and even across different Organizations within the same Tenant.

  • "All identity attributes are visible in tokens" — No. Only attributes explicitly configured for token visibility appear in access tokens. Administrators control projection at the attribute definition level.

  • "User type determines authorization" — User type influences authentication flows and session policies, but authorization decisions depend on roles, attributes, and policies — not on user type alone.

warning

The identity's effective permissions depend on the active organizational assignment. Switching departments via token exchange changes the roles and attributes visible in the token. Design services to read the active context from the token rather than assuming a fixed identity state.

Design Notes / Best Practices​

  • Treat the stable subject identifier as the primary key for cross-service user correlation. Do not rely on mutable attributes like email or display name for identity matching.
  • Configure token attribute projection conservatively — include only the attributes that downstream services require for authorization decisions.
  • Account for multiple organizational assignments when designing user interfaces. Present the user's available contexts and allow explicit switching rather than defaulting to a single assignment.
tip

Use the identity model's organizational assignments as the source of truth for "where can this user operate." Combine with the scoped administration model to delegate management of assignments to department-level administrators.

  • Representing users with cross-departmental responsibilities
  • Federating external identities into the platform with organizational placement
  • Tracking authentication context for session freshness decisions
  • Supporting different user types with tailored authentication flows

Users, Groups, Roles & Organizations

How identity entities relate and how roles resolve

Identity Attributes & Claims

Custom attributes and token claim projection

Organization Model

Tenant and department hierarchy that identities attach to

Token Claims & Context

How identity attributes appear in access tokens