Skip to main content

Identity Attributes & Claims

Summary​

Keymate supports custom identity attributes through a definition-based model. Administrators create attribute definitions that specify the data type, validation rules, scoping level, and visibility settings for each attribute. Users receive attribute values that conform to these definitions. The platform selectively projects attribute values into access token claims based on the visibility configuration, enabling downstream services to consume identity attributes without secondary lookups.

Why It Exists​

Standard identity profiles cover basic user information, but enterprise environments require domain-specific attributes — approval status, clearance level, employee classification, cost center, and other fields unique to each deployment. The attribute model enables administrators to define these fields with typed validation and control precisely which attributes appear in tokens, in administrative interfaces, or in user-facing interfaces. This prevents token bloat while ensuring services receive the attributes they need for authorization.

Where It Fits in Keymate​

Attribute definitions extend the identity model with custom data fields. Attribute values are assigned to users within organizational contexts. The token issuance layer reads attributes with token visibility enabled and projects them as claims. The authorization layer can evaluate policies based on these projected claims, enabling attribute-based access control.

Boundaries​

This page covers attribute definitions, value assignment, scoping, and token projection. It does not cover:

How It Works​

Attribute Definitions​

Administrators create attribute definitions that serve as the schema for custom identity attributes. Each definition specifies:

  • Data type — text, selection list, boolean, number, or date
  • Validation rules — required/optional, allowed values for selection lists
  • Visibility settings — whether the attribute appears in access tokens, in the administrative interface, or in user-facing interfaces
  • Sensitivity marking — whether the attribute contains sensitive data that should be masked in interfaces
  • Encryption options — whether values require encryption at rest or in transit
  • Retention policy — how long values are retained and whether to anonymize on user deletion
  • Data classification — a label for regulatory or compliance categorization

Attribute Scoping​

Attribute definitions support multiple scoping levels that control where the definition applies:

  • Global scope — the definition applies across all Tenants in the realm
  • Tenant scope — the definition applies only within a specific Tenant
  • Tenant type scope — the definition applies to all Tenants of a specific type

Scoping ensures that Tenant-specific attributes remain isolated. A Tenant that requires a "clearance level" attribute can define it at Tenant scope without affecting other Tenants.

Value Assignment​

After creating a definition, administrators assign values to individual users. Each value assignment records:

  • Which definition the value conforms to
  • The actual value
  • The scoping context (which Tenant the value belongs to)
  • The data source (whether the value was set by an administrator, synchronized from an external directory, or self-reported by the user)
  • The active/inactive status of the value

A single user can have different values for the same attribute definition across different Tenant or organizational contexts.

Token Projection​

When the platform issues an access token, it checks each attribute definition associated with the user's active context. The platform includes attributes with token visibility enabled as claims in the access token. Attributes without token visibility remain in the identity store and do not appear in tokens.

This selective projection keeps tokens compact and limits exposure of sensitive data. Downstream services that need an attribute not present in the token can request it through the introspection or attribute retrieval APIs.

Attribute Templates​

Administrators can define attribute templates to create reusable sets of attribute definitions. When creating a new department or organizational structure, applying a template pre-populates the required attribute definitions. Templates support default values and can be grouped for bulk management.

Diagram​

Example Scenario​

Scenario​

An administrator defines a "document clearance" attribute at the Tenant level with a selection list of allowed values. The administrator enables token visibility for this attribute. A user receives this attribute with the value "confidential." When the user authenticates and obtains an access token, the clearance value appears as a claim.

Input​

  • Actor: Authenticated user with a "document clearance" attribute set to "confidential"
  • Resource: Document management service that restricts access based on clearance
  • Action: Request a classified document
  • Context: Access token carries the clearance claim due to token visibility setting

Expected Outcome​

  • Granted — The document service reads the clearance claim from the token, confirms "confidential" meets the document's classification requirement, and returns the document
  • Why: The attribute definition has token visibility enabled, so the platform projected the value into the access token as a claim. The downstream service uses this claim for access control without querying the identity store.

Common Misunderstandings​

  • "All custom attributes automatically appear in tokens" — No. Only attributes with token visibility explicitly enabled appear in tokens. This is a deliberate design to control token size and data exposure.

  • "Attribute definitions are global by default" — No. The scoping level is configurable. Tenant-scoped definitions are isolated to their Tenant boundary and do not affect other Tenants.

  • "Changing an attribute definition retroactively changes existing values" — No. Modifying a definition (such as changing allowed values) affects future validation, but existing assigned values retain their current state.

warning

Marking an attribute as sensitive does not prevent it from appearing in tokens. Sensitivity controls UI masking. To exclude an attribute from tokens, disable its token visibility setting.

Design Notes / Best Practices​

  • Enable token visibility only for attributes that downstream services require for authorization. Each projected attribute increases token size and potential data exposure.
  • Use attribute scoping to prevent Tenant-specific attributes from leaking across Tenant boundaries. Global scope is appropriate for attributes that every Tenant needs; Tenant scope is appropriate for Tenant-specific extensions.
  • Configure retention policies and data classification for attributes that contain personally identifiable information or regulated data.
tip

Use attribute templates when onboarding new Organizations to ensure consistent attribute definitions across departments. Templates reduce manual configuration and prevent inconsistencies.

  • Defining domain-specific attributes (clearance, cost center, employee type) per Tenant
  • Projecting authorization-relevant attributes into tokens for stateless policy evaluation
  • Configuring encryption and retention policies for regulated identity data
  • Synchronizing attributes from external directories with scoped value assignment

Identity Model

Core identity representation that attributes extend

Token Claims & Context

How projected attributes appear in access tokens

Tenant-Scoped Identity

How Tenant boundaries isolate attribute definitions

Attributes

Attribute definitions, inheritance, and compliance tags