Migration Guide

Migrating data from your existing identity system to cidaas is a critical step in your integration journey — typically users, passwords, and related identity data (and where relevant apps, consents, or sessions). This guide covers planning and execution of that data migration.

Configure hosted pages, fields, and applications separately in the Instance Setup Guide before or in parallel with data migration.

Migration Overview

User migration involves transferring user accounts, credentials, and associated data from your legacy system to cidaas. The migration process ensures that your users can seamlessly continue using your services without interruption.

Planning Your Migration

Before starting the technical data migration, review these guides:

• Migration Planning Guide - Strategic guidance on merging sources, defining attributes, and handling social providers
• Instance Setup Guide - Configure the instance (hosted pages, fields, consents, verification methods, applications) so it matches the data you will import

Technical Implementation

For step-by-step technical guidance, see the User Migration Guide which covers API usage, data mapping, and security considerations.

Migration Procedures

Choose the migration approach that best fits your requirements. User counts below are guidelines only (~500k as a rough split); downtime tolerance, change rate, and go-live style matter as much as volume.

Approach	Volume guideline	Typical go-live
One-time	below ~500k users	all-in-one cutover with a maintenance window
Long-term sync	above ~500k users	all-in-one cutover after continuous sync
Bidirectional sync	above ~500k users	step-by-step app cutover while both IdPs stay in sync

One-Time Migration

Migrate all users at once from your legacy system. Ideal for:

• Complete system replacement
• Smaller to mid-size user bases (guideline: below ~500k)
• When you can schedule a maintenance window

Use when: You want to migrate all users in a single operation and then decommission the old system.

Long-Term Sync Migration

Continuously synchronize users from your source system to cidaas. Ideal for:

• Larger user bases (guideline: above ~500k)
• When the legacy system keeps changing until cutover
• When you need to run both systems in parallel before an all-in-one switch

Use when: You need to migrate users over an extended period while keeping both systems operational until a single cutover.

Bidirectional Sync Migration

Keep user data synchronized in both directions between cidaas and your source system. Ideal for:

• Larger user bases (guideline: above ~500k)
• Step-by-step app migration
• When users must authenticate against either IdP during rollout

Use when: You need to maintain synchronization between cidaas and your existing system in both directions.

Related approaches

IdP-driven provisioning (SCIM): If your source system is an identity provider with outbound SCIM provisioning, you may provision users continuously via SCIM instead of the Migration API. See SCIM 2.0 User Provisioning.

Migration Topics

Password Migration

Learn how to migrate passwords with different hashing algorithms. Understand:

• Supported hashing algorithms
• Password hash format requirements
• Migration mode configuration

Native App Cutover (Migration)

Special considerations when cutting over native mobile applications from a legacy IdP:

• Discovery / well-known cutover and matching client_id
• Refresh token migration so users can stay signed in after go-live
• Parallel sync while old app versions remain in the field

For integration patterns (PKCE, browser login, Custom Tabs), see Mobile and Native Clients.

API Reference

For detailed API documentation, see the User Migration API Reference (POST /users-srv/user/bulk).

Quick Start Checklist

Use this checklist to get started with migration:

• Complete Migration Planning (merging sources, defining attributes)
• Review your current user data structure
• Map source data fields to cidaas user entity structure
• Choose the appropriate migration procedure
• Enable migrationMode only if password overwrite on already-migrated users is required
• Set up authentication for migration API (Client Credentials flow)
• Test migration with a small user subset
• Plan password migration strategy if applicable
• Plan refresh token migration if apps should keep users signed in after cutover
• Schedule migration window (for one-time migration)
• Monitor migration progress
• Verify migrated user data
• Plan user communication strategy (including MFA re-enrollment if needed)

For a comprehensive planning checklist, see the Migration Planning Guide.

Next Steps

After completing user migration, proceed to the Integration Guide to learn about:

• Best practices for integrating cidaas
• Client-specific integration patterns
• Available plugins and devkits
• Advanced configuration options