Skip to main content

Provisioning & SCIM

Summary​

Keymate provisions user identities from external sources through directory synchronization, federated first-login creation, and credential lifecycle management. The platform imports users from directory services (LDAP, Active Directory), synchronizes their attributes on configurable schedules, and manages credential propagation to external systems when passwords change. SCIM (System for Cross-domain Identity Management) provides a standard protocol for automated user lifecycle operations between the platform and external identity consumers.

Why It Exists​

Organizations maintain user identities in multiple systems — corporate directories, HR systems, external credential stores. Manual user creation across all systems is error-prone and delays access. Provisioning automates the user lifecycle: when an employee joins (directory import), changes roles (attribute sync), changes their password (credential propagation), or leaves (account disable propagation). SCIM standardizes this lifecycle across systems that support the protocol.

Where It Fits in Keymate​

Provisioning extends the federation model by automating the user lifecycle beyond initial authentication. Directory synchronization populates the identity model with users and attributes before they ever log in. Credential synchronization ensures that password changes in the platform propagate to external systems. The authentication flow triggers first-login provisioning when a federated user authenticates for the first time. Tenant-scoped identity boundaries control which Tenant receives provisioned users.

Boundaries​

This page covers user provisioning, directory sync, credential propagation, and SCIM support. It does not cover:

How It Works​

Directory Synchronization​

The platform connects to directory services (LDAP, Active Directory) and imports users based on configurable search filters and attribute mappings. Directory sync supports:

  • User import — querying the directory for users matching a filter and creating local users with mapped attributes (name, email, phone, department)
  • Attribute mapping — configurable rules that translate directory attributes to local user fields. Custom mappers handle domain-specific logic such as using a national identifier as the username, filtering by email domain, and synchronizing account status from directory control flags.
  • Account status sync — reading the directory's account status (enabled/disabled) and mirroring it in the local user. The platform can enforce additional business rules during sync, such as requiring a verified email domain or a national identifier for the account to remain enabled.
  • Organizational assignment — automatically assigning imported users to a specific Tenant or Organization based on directory attributes or sync configuration.

Credential Synchronization​

When a user changes their password in the platform, the credential sync mechanism propagates the new password to registered external systems. This ensures that the user's password stays consistent across systems without requiring the user to update each system individually.

Credential sync operates through an extensible provider model:

  1. The user updates their password in the platform
  2. The platform invokes all registered credential sync providers
  3. Each provider transmits the new password to its external system
  4. The platform logs sync results (success or failure per provider) for monitoring
  5. A credential sync failure does not block the password update in the platform — the local password change succeeds regardless of external sync outcomes

This fail-open design ensures that local authentication remains functional even when an external system is temporarily unavailable.

First-Login Provisioning​

When a user authenticates through federation for the first time and no matching local user exists, the platform provisions a new user:

  1. The external identity provider returns the user's identity attributes
  2. The platform checks for an existing local user matching the external identity
  3. If no match exists, the platform creates a local user and populates their profile from the external attributes
  4. The platform can assign the new user to an Organization based on mapping rules
  5. Subsequent logins use the linked local user without re-provisioning

SCIM Protocol Support​

SCIM provides a standard REST-based protocol for managing user lifecycle operations across identity domains. Through SCIM, external systems can:

  • Create users in the platform
  • Update user attributes
  • Deactivate or delete users
  • Query users and groups

SCIM integration enables HR systems and identity governance tools to automate the full user lifecycle without custom integration code.

Deprovisioning and Account Disablement​

When a user is removed from the directory or their account is disabled, the sync process propagates this change:

  • The directory sync detects the changed status and disables the local user
  • An event listener detects the user disable event and terminates all active sessions for that user
  • Subsequent authentication attempts fail because the local account is disabled

This chain ensures that removing a user from the directory immediately revokes their platform access.

Diagram​

Example Scenario​

Scenario​

An Organization connects its Active Directory to the platform for user provisioning. A new employee appears in the directory. The platform imports the employee, maps their attributes, and assigns them to the correct Tenant. Later, the employee changes their password in the platform, and the new password propagates to the external credential system.

Input​

  • Actor: Platform directory sync process
  • Resource: Active Directory user entries
  • Action: Periodic sync import, followed by user-initiated password change
  • Context: Directory sync configured with attribute mapping for name, email, department, and national identifier. Credential sync provider registered for the external system.

Expected Outcome​

  • Applied — The sync process imports the new employee, creates a local user with mapped attributes and an organizational assignment, and enables the account (assuming email domain and identifier validation pass). When the employee later changes their password, the platform updates the local credential and propagates the new password to the external system. If the external system is temporarily unreachable, the local password change succeeds and the sync failure is logged.
  • Why: Directory sync automates user import with attribute mapping. Credential sync propagates password changes with a fail-open design. The local identity remains functional regardless of external system availability.

Common Misunderstandings​

  • "Directory sync creates users instantly when they appear in the directory" — No. Sync runs on a configured schedule or trigger. Users appear in the platform after the next sync cycle processes their directory entry.

  • "Credential sync failure blocks the password change" — No. The platform uses a fail-open design. The local password updates successfully even if one or more external sync targets fail. The platform logs failures for monitoring and retry.

  • "SCIM replaces directory sync" — They serve different directions. Directory sync pulls users from an external directory into the platform. SCIM exposes the platform's user lifecycle to external consumers. Both can coexist in the same deployment.

warning

When configuring directory sync with automatic organizational assignment, verify the mapping rules with a test sync before running against the full directory. Incorrect mapping can assign users to the wrong Tenant, requiring manual cleanup.

Design Notes / Best Practices​

  • Configure directory sync with specific search filters to import only the users who need platform access. Importing the entire directory creates unnecessary user records and increases sync time.
  • Monitor credential sync results through platform logs. Repeated failures for a specific external system indicate connectivity or configuration issues that need attention.
  • Use SCIM for automated lifecycle management from HR systems. SCIM's standardized operations reduce integration effort compared to custom provisioning workflows.
tip

When migrating from a legacy directory to the platform, run the initial directory sync in a preview mode (if available) to verify attribute mappings before committing user creation. This prevents large-scale data quality issues during the initial import.

  • Importing employees from Active Directory with business rule enforcement
  • Propagating password changes to external credential systems
  • Automating user lifecycle through SCIM from an HR system
  • Disabling users in the platform when they are removed from the directory

Federation & External IdPs

Authentication-time federation that triggers first-login provisioning

Identity Model

Local identity representation that provisioning populates

Tenant-Scoped Identity

Tenant boundaries that scope provisioned user assignments

Session Governance

Session termination triggered by user deprovisioning