Skip to Content
OperationsBulk user migration

Bulk user migration

Bulk import is backend neutral. The source system exports a canonical version-1 document with a stable source and unique externalId for each account. Identity generates the final opaque subject and records the exact external reference for idempotent retries.

Safe sequence

  1. Export from the source database with a consistent snapshot.
  2. Prepare a canonical import with mode: VALIDATE_ONLY.
  3. Submit it and inspect every paginated result.
  4. Prepare the same records with mode: CREATE_ONLY and a new idempotency key.
  5. Submit, wait for SUCCEEDED and verify exact record coverage.
  6. Persist every authoritative externalId to subject mapping in the source backend.
  7. Verify product access by exact issuer and subject.
  8. Perform the source backend’s separate cutover.
./identityctl users import TENANT_UUID customer.validate.json
./identityctl users imports TENANT_UUID 0
./identityctl users import-results TENANT_UUID JOB_UUID 0

Imports accept at most 500 records per job. Reusing an idempotency key with different content is rejected. A successful validation does not create users.

Password migration supports BCrypt. The canonical format can also carry one enabled TOTP factor, remaining recovery-code BCrypt hashes and explicit upstream-account links. Sensitive staged material is cleared after completion, cancellation or exhausted retries.

Profile exports stream NDJSON and intentionally exclude passwords, MFA secrets, recovery codes and upstream credentials. They support reconciliation, not reconstruction of an authentication source.

identityctlAuthentication and MFA