apps/docs/content/guides/migrate/introduction.mdx
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.
Multi-tenancy in ZITADEL can be achieved through either Instances or Organizations or 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), Administrators, and Users. Please also consult our guide on Solution Scenarios for B2C and B2B for more details.
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.
Projects can be granted to Organization 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 administration overhead low and enabling self-service for Organizations to manage their own Settings and Authorizations.
ZITADEL Actions 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 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. This might be required if an application expects roles/permissions in a certain format or additional attributes (eg, a backend user-id) as claims.
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 accessed directly with the correct scopes or transformed to custom claims (see above).
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.
After you have set up or imported your applications to ZITADEL, you need to update your client's settings, such as issuer, clientID or credentials. It is not possible to create an application with a pre-defined clientID or import existing credentials.
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 for batch migration of users.
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:
For all other cases, we recommend that the legacy system orchestrates the migration of users to ZITADEL for more flexibility:
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: