mirror of
https://github.com/zitadel/zitadel.git
synced 2025-01-05 22:52:46 +00:00
docs(migrate): Migrate to ZITADEL (#5625)
* docs(guide): migration process guide * outline users * intro * wip * wip * wip - basics * structure migrate * importing users * structure * sidebar * move technical considerations to intro * update users * update sidebar * migrate from auth0 * Apply suggestions from code review Co-authored-by: Fabi <fabienne.gerschwiler@gmail.com> * remove mermaid * add concepts * replace bulk user * add note on code snippets --------- Co-authored-by: Fabi <fabienne.gerschwiler@gmail.com>
This commit is contained in:
mffap
GitHub
parent
440ba9f5ef
commit
ef7c53a6dc
79
docs/docs/guides/migrate/introduction.md
Normal file
79
docs/docs/guides/migrate/introduction.md
Normal file
@ -0,0 +1,79 @@
|
||||
---
|
||||
title: Migrate to ZITADEL
|
||||
sidebar_label: Introduction
|
||||
---
|
||||
|
||||
This section of guides shows you how to migrate from your current auth system to ZITADEL.
|
||||
The individual guides in this section should give you an overview of things to consider before you start the migration.
|
||||
|
||||
When moving from a previous auth solution to ZITADEL, it is important to note that some decisions and features are unique to ZITADEL.
|
||||
Without duplicating too much content here are some important features and patterns to consider in terms of solution architecture.
|
||||
You can read more about the basic structure and important concepts of ZITADEL in our [concepts section](https://zitadel.com/docs/concepts/introduction).
|
||||
|
||||
## Multi-Tenancy Architecture
|
||||
|
||||
Multi-tenancy in ZITADEL can be achieved through either [Instances](/docs/concepts/structure/instance) or [Organizations](/docs/concepts/structure/organizations).
|
||||
Where instances represent isolated ZITADEL instances, Organizations provide a more permeable approach to multi-tenancy.
|
||||
|
||||
In most cases, when you want to achieve multi-tenancy, you use Organizations. Each organization can have their own set of Settings (eg, Security Policies, IDPs, Branding), Managers, and Users.
|
||||
Please also consult our guide on [Solution Scenarios](/docs/guides/solution-scenarios/introduction
|
||||
) for B2C and B2B for more details.
|
||||
|
||||
## Delegated Access Management
|
||||
|
||||
Some solutions, that offer multi-tenancy, require you to copy applications and settings to each tenant and manage changes individually.
|
||||
ZITADEL works differently by using [Granted Projects](/docs/concepts/structure/granted_projects).
|
||||
|
||||
Projects can be granted to [Organization](/docs/concepts/structure/projects#granted-organizations) or even to individual users.
|
||||
You can think of it as a logical link to a Project, which can be used by the receiving Organization or User as if it was their own project, except privileges to modify the Project itself.
|
||||
|
||||
Delegated access management is a great way of keeping the management overhead low and enabling [self-service](/docs/concepts/features/selfservice#managers-in-delegation) for Organizations to manage their own Settings and Authorizations.
|
||||
|
||||
## Actions
|
||||
|
||||
ZITADEL [Actions](/docs/apis/actions/introduction) is the key feature to customize and create workflows and change the default behavior of the platform.
|
||||
|
||||
You define custom code that should be run on a specific Trigger.
|
||||
A trigger could be the creation of a new user, getting profile information about a user, or a login attempt.
|
||||
|
||||
With the [HTTP module](/docs/apis/actions/modules) you can even make calls to third party systems for example to receive additional user information from a backend system, or triggering a workflow in other systems (Webhook).
|
||||
|
||||
You can also create custom claims or manipulate tokens and information on the userinfo endpoint by using the [Complement Token Flow](/docs/apis/actions/complement-token).
|
||||
This might be required, if an application expects roles/permissions in a certain format or additional attributes (eg, a backend user-id) as claims.
|
||||
|
||||
## Metadata
|
||||
|
||||
You can store arbitrary key-value pairs of data on objects such as Users or Organizations.
|
||||
Metadata could link a user to a specific backend user-id or represent an "organizational unit" for your business logic.
|
||||
Metadata can be access directly with the correct [scopes](/docs/apis/openidoauth/scopes#reserved-scopes) or transformed to custom claims (see above).
|
||||
|
||||
## Migrating users
|
||||
|
||||
Migrating users with minimal impact on users can be a challenging task.
|
||||
We provide some more information on migrating users and secrets in [this guide](./users.md).
|
||||
|
||||
## Technical considerations
|
||||
|
||||
### Batch migration
|
||||
|
||||
**Batch migration** is the easiest way, if you can afford some minimal downtime to move all users and applications over to ZITADEL.
|
||||
See the [User guide](./users.md) for batch migration of users.
|
||||
|
||||
### Just-in-time migration
|
||||
|
||||
In case all your applications depend on ZITADEL after the migration date, and ZITADEL is able to retrieve the required user information, including secrets, from the legacy system, then the recommended way is to let **ZITADEL orchestrate the user migration just-in-time**:
|
||||
|
||||
- Create a pre-authentication [Action](/docs/apis/actions/introduction) to request user data from the legacy system and create a new user in ZITADEL.
|
||||
- Optionally, create a post-authentication Action to flag successfully migrated users in your legacy system
|
||||
|
||||
For all other cases, we recommend that the **legacy system orchestrates the migration** of users to ZITADEL for more flexibility:
|
||||
|
||||
- Update your legacy system to create a user in ZITADEL on their next login, if not already flagged as migrated, by using our APIs (you can set the password and a verified email)
|
||||
- Redirect migrated users with a login hint in the [auth request](/docs/apis/openidoauth/authrequest.mdx) to ZITADEL to pre-select the user
|
||||
|
||||
In this case the migration can also be done as an import job or also allowing to create user session in both the legacy auth solution and ZITADEL in parallel with identity brokering:
|
||||
|
||||
- Setup ZITADEL to use your legacy system as external identity provider (note: you can also use JWT-IDP, if you only have a token).
|
||||
- Configure your app to use ZITADEL, which will redirect users automatically to the external identity provider to login.
|
||||
- A session will be created both on the legacy system and ZITADEL
|
||||
- If a user does not exist already in ZITADEL you can auto-register new users and use an Action to pull additional information (eg, Secrets) from your legacy system. Note: ZITADEL links external identity information to users, meaning you can have users use both a password and external identity providers to login with the same user.
|
||||
41
docs/docs/guides/migrate/sources/auth0.md
Normal file
41
docs/docs/guides/migrate/sources/auth0.md
Normal file
@ -0,0 +1,41 @@
|
||||
---
|
||||
title: Migrate from Auth0
|
||||
sidebar_label: From Auth0
|
||||
---
|
||||
|
||||
Migrating users from Auth0 to ZITADEL requires the following steps:
|
||||
|
||||
- Request and download hashed passwords
|
||||
- Export all user data
|
||||
- Import users and password hashes to ZITADEL
|
||||
|
||||
## Export hashed passwords
|
||||
|
||||
Auth0 does not export hashed passwords as part of the bulk user export.
|
||||
You must create a support ticket to download password hashes and password-related information.
|
||||
Please also refer to the Auth0 guide on how to [Export Data](https://auth0.com/docs/troubleshoot/customer-support/manage-subscriptions/export-data#user-passwords).
|
||||
|
||||
:::info
|
||||
You can also import users into ZITADEL with an verified email but without the passwords.
|
||||
Users will be prompted to create a new password after they login for the first time after migration.
|
||||
:::
|
||||
|
||||
1. Go to https://support.auth0.com/tickets and click on **Open Ticket**
|
||||
2. Issue Type: **I have a question regarding my Auth0 account**
|
||||
3. What can we help you with?: **I would like to obtain an export of my tenant password hashes**
|
||||
4. Fill out the form: Request password hashes as bcrypt
|
||||
5. **Submit ticket**
|
||||
|
||||
You will receive a JSON file including the password hashes.
|
||||
See this [community post](https://community.auth0.com/t/password-hashes-export-data-format/58730) for more information about the contents and format.
|
||||
|
||||
## Export all user data
|
||||
|
||||
Create a [bulk user export](https://auth0.com/docs/manage-users/user-migration/bulk-user-exports) from the Auth0 Management API.
|
||||
You will receive a newline-delimited JSON with the requested user data.
|
||||
|
||||
## Import users and password hashes to ZITADEL
|
||||
|
||||
You will need to merge the received password hashes with the user bulk export.
|
||||
|
||||
After you successfully merged the datasets, you can follow the instructions described in the [Migrate Users](../users) guide to import users to ZITADEL.
|
||||
@ -1,5 +1,6 @@
|
||||
---
|
||||
title: Export and import with ZITADEL
|
||||
title: Migrate from v1
|
||||
sidebar_label: From ZITADEL v1
|
||||
---
|
||||
|
||||
## Export from V1 to Import into V2
|
||||
236
docs/docs/guides/migrate/users.md
Normal file
236
docs/docs/guides/migrate/users.md
Normal file
@ -0,0 +1,236 @@
|
||||
---
|
||||
title: Migrate Users
|
||||
sidebar_label: 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](/docs/apis/mgmt/management-service-import-human-user).
|
||||
Please also consult our [guide](/docs/guides/manage/user/reg-create-user) on how to create users.
|
||||
|
||||
```json
|
||||
{
|
||||
"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](https://zitadel.com/docs/apis/admin/admin-service-import-data) on the admin API:
|
||||
|
||||
```json
|
||||
{
|
||||
"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"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
:::info
|
||||
We will improve the bulk import interface for users in the future.
|
||||
You can show your interest or join the discussion on [this issue](https://github.com/zitadel/zitadel/issues/5524).
|
||||
:::
|
||||
|
||||
## 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
|
||||
|
||||
Passwords are stored only as hash.
|
||||
You can transfer the hashes as long as ZITADEL [supports the same hash algorithm](/docs/concepts/architecture/secrets#hashed-secrets).
|
||||
Password change on the next sign-in can be enforced.
|
||||
|
||||
_snippet from [bulk-import](#bulk-import) example:_
|
||||
```json
|
||||
{
|
||||
"userName": "test9@test9",
|
||||
...,
|
||||
"hashedPassword": {
|
||||
"value": "$2a$14$aPbwhMVJSVrRRW2NoM/5.esSJO6o/EIGzGxWiM5SAEZlGqCsr9DAK",
|
||||
"algorithm": "bcrypt"
|
||||
},
|
||||
"passwordChangeRequired": false,
|
||||
...,
|
||||
}
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
:::info
|
||||
In case the hash algorithm you are using is not supported by ZITADEL, please let us know after searching our discussions, issues, and chat for similar requests.
|
||||
:::
|
||||
|
||||
### One-time-passwords (OTP)
|
||||
|
||||
You can pass the OTP secret when creating users:
|
||||
|
||||
_snippet from [bulk-import](#bulk-import) example:_
|
||||
```json
|
||||
{
|
||||
"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](#bulk-import) example:_
|
||||
```json
|
||||
{
|
||||
"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.
|
||||
|
||||
:::info
|
||||
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](https://zitadel.com/docs/guides/manage/console/instance-settings#identity-providers).
|
||||
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](#bulk-import) example:_
|
||||
```json
|
||||
{
|
||||
"userName": "test9@test9",
|
||||
...,
|
||||
"idps": [
|
||||
{
|
||||
"configId": "124425861423228496",
|
||||
"externalUserId": "roadrunner@mailonline.com",
|
||||
"displayName": "name"
|
||||
}
|
||||
...,
|
||||
}
|
||||
```
|
||||
|
||||
You can use an Action with [post-creation flow](https://zitadel.com/docs/apis/actions/external-authentication#post-creation) 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.
|
||||
|
||||
:::info
|
||||
Metadata must be added to users after the users were created. Currently metadata can't be added during user creation.
|
||||
[API reference: User Metadata](https://zitadel.com/docs/category/apis/mgmt/user-metadata)
|
||||
:::
|
||||
|
||||
Request metadata from the userinfo endpoint by passing the required [reserved scope](/docs/apis/openidoauth/scopes#reserved-scopes) in your auth request.
|
||||
With the [complement token flow](/docs/apis/actions/complement-token), you can also transform metadata (or roles) to custom claims.
|
||||
|
||||
## Authorizations / Roles
|
||||
|
||||
You can assign roles from owned or granted projects to a user.
|
||||
|
||||
:::info
|
||||
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](https://zitadel.com/docs/category/apis/auth/user-authorizations-grants)
|
||||
:::
|
||||
@ -105,6 +105,24 @@ module.exports = {
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
type: "category",
|
||||
label: "Migrate",
|
||||
collapsed: false,
|
||||
items: [
|
||||
"guides/migrate/introduction",
|
||||
"guides/migrate/users",
|
||||
{
|
||||
type: "category",
|
||||
label: "Sources",
|
||||
collapsed: true,
|
||||
items: [
|
||||
"guides/migrate/sources/zitadel-v1",
|
||||
"guides/migrate/sources/auth0",
|
||||
]
|
||||
},
|
||||
]
|
||||
},
|
||||
{
|
||||
type: "category",
|
||||
label: "Integrate",
|
||||
@ -154,7 +172,6 @@ module.exports = {
|
||||
"guides/integrate/access-zitadel-apis",
|
||||
"guides/integrate/access-zitadel-system-api",
|
||||
"guides/integrate/event-api",
|
||||
"guides/integrate/export-and-import",
|
||||
{
|
||||
type: "category",
|
||||
label: "Example Code",
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user