Migrate Users
Migrating users from an existing system, while minimizing impact on said users, can be a challenging task.
Individual Users​
Creating individual users can be done with this endpoint: ImportHumanUser. Please also consult our guide on how to create users.
{
"userName": "test9@test9",
"profile": {
"firstName": "Road",
"lastName": "Runner",
"displayName": "Road Runner",
"preferredLanguage": "en"
},
"email": {
"email": "test@test.com",
"isEmailVerified": false
},
"hashedPassword": {
"value": "$2a$14$aPbwhMVJSVrRRW2NoM/5.esSJO6o/EIGzGxWiM5SAEZlGqCsr9DAK",
"algorithm": "bcrypt"
},
"passwordChangeRequired": false,
"otpCode": "testotp",
"requestPasswordlessRegistration": false,
"idps": [
{
"configId": "124425861423228496",
"externalUserId": "roadrunner@mailonline.com",
"displayName": "name"
}
]
}
Bulk import​
For bulk import use the import endpoint on the admin API:
{
"timeout": "10m",
"data_orgs": {
"orgs": [
{
"orgId": "104133391254874632",
"org": {
"name": "ACME"
},
"humanUsers": [
{
"userId": "104133391271651848",
"user": {
"userName": "test9@test9",
"profile": {
"firstName": "Road",
"lastName": "Runner",
"displayName": "Road Runner",
"preferredLanguage": "de"
},
"email": {
"email": "test@acme.tld",
"isEmailVerified": true
},
"hashedPassword": {
"value": "$2a$14$aPbwhMVJSVrRRW2NoM/5.esSJO6o/EIGzGxWiM5SAEZlGqCsr9DAK",
"algorithm": "bcrypt"
}
}
},
{
"userId": "120080115081209416",
"user": {
"userName": "testuser",
"profile": {
"firstName": "Test",
"lastName": "User",
"displayName": "Test User",
"preferredLanguage": "und"
},
"email": {
"email": "fabienne@caos.ch",
"isEmailVerified": true
},
"hashedPassword": {
"value": "$2a$14$785Fcdbpo9rn5L7E21nIAOJvGCPgWFrZhIAIfDonYXzWuZIKRAQkO",
"algorithm": "bcrypt"
}
}
},
{
"userId": "145195347319252359",
"user": {
"userName": "wile@test9",
"profile": {
"firstName": "Wile E.",
"lastName": "Coyote",
"displayName": "Wile E. Coyote",
"preferredLanguage": "en"
},
"email": {
"email": "wile.e@acme.tld"
}
}
}
]
}
]
}
}
We will improve the bulk import interface for users in the future. You can show your interest or join the discussion on this issue.
Migrate secrets​
Besides user data you need to migrate secrets, such as password hashes, OTP seeds, and public keys for passkeys (FIDO2). The snippets in the sections below are parts from the bulk import endpoint, to clarify how the different objects can be imported.
Passwords​
ZITADEL stores passwords only as irreversible hashes, never in clear text. Existing password hashes can be imported if they use a supported hash algorithm.
Import password hashes using the import API (snippet from bulk-import):
{
"userName": "test9@test9",
...,
"hashedPassword": {
"value": "$2a$14$aPbwhMVJSVrRRW2NoM/5.esSJO6o/EIGzGxWiM5SAEZlGqCsr9DAK",
"algorithm": "bcrypt"
},
"passwordChangeRequired": false,
...,
}
Upon initial login, ZITADEL validates the imported password using the appropriate verifier.
In ZITADEL, a password verifier checks the validity of a password hash created with an algorithm different from the currently configured one.
It acts as a translator, allowing ZITADEL to understand and validate hashes made with older algorithms like MD5 even when the system has transitioned to newer ones like Argon2.
This is crucial during migrations or when importing user data.
Essentially, a verifier ensures ZITADEL can work with passwords hashed using various algorithms, maintaining security while transitioning to stronger hashing methods.
Regardless of the passwordChangeRequired setting, the password is rehashed using the configured hasher algorithm and stored.
This ensures consistency and allows for automatic updates even when hasher configurations are changed, such as increasing salt cost for bcrypt.
To configure the default hasher for new user passwords, set the Algorithm of the PasswordHasher in the runtime configuration file
or by the environment variable ZITADEL_SYSTEMDEFAULTS_PASSWORDHASHER_HASHER_ALGORITHM, for example:
ZITADEL_SYSTEMDEFAULTS_PASSWORDHASHER_HASHER_ALGORITHM='pbkdf2'
Hasher configuration updates will automatically rehash existing passwords when they are validated or changed.
In case the hashes can't be transferred directly, you always have the option to create a user in ZITADEL without password and prompt users to create a new password.
If your legacy system receives the passwords in clear text (eg, login form) you could also directly create users via ZITADEL API. We will explain this pattern in more detail in this guide.
One-time-passwords (OTP)​
You can pass the OTP secret when creating users:
snippet from bulk-import example:
{
"userName": "test9@test9",
...,
"otpCode": "testotp",
...,
}
Passkeys​
When creating new users, you can trigger a workflow that prompts the users to setup a passkey authenticator.
snippet from bulk-import example:
{
"userName": "test9@test9",
...,
"requestPasswordlessRegistration": false,
...,
}
For passkeys to work on the new system you need to make sure that the new auth server has the same domain as the legacy auth server.
Currently it is not possible to migrate passkeys directly from another system.
Users linked to an external IDP​
A users sub is bound to the external IDP's Client ID.
This means that the IDP Client ID configured in ZITADEL must be the same ID as in the legacy system.
Users should be imported with their externalUserId.
snippet from bulk-import example:
{
"userName": "test9@test9",
...,
"idps": [
{
"configId": "124425861423228496",
"externalUserId": "roadrunner@mailonline.com",
"displayName": "name"
}
...,
}
You can use an Action with post-creation flow to pull information such as roles from the old system and apply them to the user in ZITADEL.
Metadata​
You can store arbitrary key-value information on a user (or Organization) in ZITADEL. Use metadata to store additional attributes of the users, such as organizational unit, backend-id, etc.
Metadata must be added to users after the users were created. Currently metadata can't be added during user creation.
API reference: User Metadata
Request metadata from the userinfo endpoint by passing the required reserved scope in your auth request. With the complement token flow, you can also transform metadata (or roles) to custom claims.
Authorizations / Roles​
You can assign roles from owned or granted projects to a user.
Authorizations must be added to users after the users were created. Currently metadata can't be added during user creation.
API reference: User Authorization / Grants