Long term migration via event stream

Guideline only

As a rule of thumb, long-term sync fits user volumes above ~500k. Also prefer it when many apps cut over together but you cannot freeze the legacy system for a long window. These are guidelines — validate against your change rate and downtime constraints.

When we are talking about a long-term migration via event streams, we are referring to a scenario where data from the legacy system is synced to cidaas in a unidirectional way for a few weeks. This approach is often preferred when:

• the amount of user data is quite high (guideline: above ~500k users)
• multiple apps should be migrated at the same time (webshops, mobile apps, websites…) while the source system keeps changing

Here we can make sure, that updates which are happening in the legacy system are populated in real-time to cidaas. This is especially relevant for user related events like "email_changed" or "password_changed". In case a user changes his password, this event will be pushed to cidaas, where we can make sure, that the password is always the latest one.

In the following graph you can see the general flow:

As you can see in the connection between both systems, the data will be synced continuously from the legacy system to cidaas. This can include different events like:

• User created
• User updated
• User deleted By this we can make sure, that also only existing users are getting migrated.

Over the defined timeframe (e.g., 6 weeks) the full user data will be synced for defined events. Within this data we can include a lot of different default and custom data like:

• user data (e.g., email, given_name, family_name)
• password hash (e.g., bcrypt 12)
• verification status for email/mobile (if trustworthy in the source system)

MFA methods such as TOTP, FIDO2, or backup codes cannot be synced; plan user re-enrollment after cutover. See Handling Verification Methods.

Additionally, there might be the consideration to sync also other data than user data to cidaas like clients, social logins providers. But this depends on the exact use case. Most of the other data can be migrated at once since this data is not changing frequently.

After all of this data got migrated, we are ready to Go-Live with cidaas. There we have few considerations to make for the Go-Live:

• Add CName in cidaas: this is required if the same domain should be used after the switch. E.g., accounts.customer.com. Other solution would be to add already beforehand by using different domain like login.customer.com
• DNS switch: this is required in case that the same domain should be used after the switch.

During GO-live the system can be switched to a maintenance-mode (small "downtime") and you decide to switch to cidaas with all applications at once. Downtime in this case is not needed for all scenarios, but might be preferred in case that some applications take little longer to switch or a DNS switch is required.

Now after everything is switched, the sync can be stopped and the full feature set of cidaas can be used in live mode!

Technical implementation

cidaas provides a REST Bulk Migration API:

Path	{your-domain}/users-srv/user/bulk
Max batch size	1000 users per request (recommend smaller batches, e.g. 50–100, via a queue for large migrations)
API reference	Migrate (add or update) user entities

Enablement (two separate steps)

1. API scope — The endpoint requires cidaas:bulk_user_create.
2. migrationMode — Only needed if you must overwrite passwords on users that were already migrated. Ask support to enable this configuration when required.

See the User Migration Guide for token setup and payload mapping.