export

Runs a source connector and writes users.cmf.jsonl.gz, manifest.json, and a scaffolded mapping.yaml to the output directory. Five sources are supported: flatfile, a generic CSV/JSON file using a recognized column convention (source_id, email, given_name, family_name, username, locale, blocked, password, password_algorithm); kratos, which streams every identity out of a running Ory Kratos instance via its Admin API, including its bcrypt/argon2id password hash; keycloak, which reads a kc.sh export realm file or directory (the Admin API never returns password hashes, so a live-instance export isn’t possible); firebase, which pages through a Firebase Authentication project’s accounts via the Identity Toolkit API, and needs the project’s password hash parameters from the Firebase console to make the exported scrypt hashes portable; and auth0, which runs a user export job on an Auth0 tenant and exports every user, with the attributes you choose, but without passwords, since Auth0 never returns password hashes through its API. A file with other column names, or nested JSON, needs a --mapping (or a prepare step first). Any other flat-file column, or Keycloak attribute, is passed through as app_metadata/user_metadata and flagged as a manual mapping step rather than silently dropped.

For what a Kratos export includes and leaves out, see Export users from Ory Kratos. For Keycloak, see Export users from Keycloak. For Firebase, see Export users from Firebase. For Auth0, including how to get the password hashes from Auth0 support, see Export users from Auth0.

Usage

iamigrate export --source flatfile --in users.csv --format csv --out ./export/

# or, from a file with other column names, described by a mapping
iamigrate export --source flatfile --in users.json --format json --mapping mapping.yaml --out ./export/

# or, from a running Kratos instance
KRATOS_ADMIN_URL=http://127.0.0.1:4434 iamigrate export --source kratos --out ./export/

# or, from a `kc.sh export` realm export
iamigrate export --source keycloak --in ./realm-export/ --out ./export/

# or, from a Firebase project
iamigrate export --source firebase --project acme-prod --service-account ./service-account.json \
  --hash-signer-key "$SIGNER_KEY" --hash-salt-separator "$SALT_SEPARATOR" --out ./export/

# or, from an Auth0 tenant (no passwords), with only some attributes
AUTH0_DOMAIN=acme.us.auth0.com AUTH0_TOKEN=... iamigrate export --source auth0 \
  --fields email,email_verified,given_name,family_name --out ./export/

Flags

Flag	Description
`--source`	Source connector name: `flatfile` \| `kratos` \| `keycloak` \| `firebase` \| `auth0` (required)
`--in`	Input file path (flatfile source), or `kc.sh export` realm file or directory (keycloak source)
`--format`	Input format: `csv` \| `json` (default `csv`, flatfile source)
`--mapping`	`mapping.yaml` renaming and transforming the file’s own columns into the recognized ones, for a file that doesn’t follow the column convention; see `prepare` for its format (flatfile source)
`--out`	Output directory (default `./export/`)
`--admin-url`	Kratos Admin API base URL (or `$KRATOS_ADMIN_URL`, kratos source)
`--project`	Firebase project ID (or `$FIREBASE_PROJECT_ID`; default: the service account’s project; firebase source)
`--service-account`	Service account key JSON path (or `$GOOGLE_APPLICATION_CREDENTIALS`; firebase source)
`--access-token`	OAuth2 access token (or `$FIREBASE_ACCESS_TOKEN`; firebase source); exclusive with `--service-account`
`--hash-signer-key`	The Firebase project’s base64 scrypt signer key (or `$FIREBASE_HASH_SIGNER_KEY`). Without it, password hashes are exported as non-portable.
`--hash-salt-separator`	The Firebase project’s base64 scrypt salt separator (or `$FIREBASE_HASH_SALT_SEPARATOR`)
`--hash-rounds`	The Firebase project’s scrypt rounds (default `8`)
`--hash-mem-cost`	The Firebase project’s scrypt memory cost (default `14`)
`--domain`	Auth0 tenant domain (or `$AUTH0_DOMAIN`; auth0 source)
`--token`	Auth0 Management API token (or `$AUTH0_TOKEN`; auth0 source); exclusive with `--client-id`
`--client-id`	Machine-to-Machine application client ID, to get a token via client credentials (or `$AUTH0_CLIENT_ID`; auth0 source)
`--client-secret`	Machine-to-Machine application client secret (or `$AUTH0_CLIENT_SECRET`; auth0 source)
`--connection-id`	Export only the users of this Auth0 connection, e.g. `con_xxx` (default: every connection; auth0 source)
`--fields`	Export only these Auth0 user attributes, comma-separated: `email`, `email_verified`, `username`, `phone_number`, `phone_verified`, `given_name`, `family_name`, `name`, `nickname`, `picture`, `blocked`, `app_metadata`, `user_metadata`. `user_id` is always exported. Default: all of them (auth0 source)
`--limit`	Export at most this many users, to try an export on a sample (default: no limit; auth0 source)
`--no-gzip`	Write `users.cmf.jsonl` uncompressed instead of `users.cmf.jsonl.gz`. Every command that reads `--in` accepts either.

Output

File	Contents
`users.cmf.jsonl.gz`	The CMF records (`users.cmf.jsonl` with `--no-gzip`)
`manifest.json`	Record counts, per-algorithm hash counts, skipped records
`mapping.yaml`	Scaffolded field mapping; empty for the recognized-column simple case (the `--mapping` fields are kept), with `manual_steps` flagged for any custom `app_metadata`