Skip to content

Migration patterns

Migration patterns

This guide describes recommended patterns for migrating existing access models to Identity Universe collections.

The goal of a migration is not simply to recreate existing groups. The goal is to establish a sustainable, explainable, and maintainable access model based on collections, approval flows, and Group Link.

Migration principles

Before migrating, identify:

  • who currently has access;
  • why they have access;
  • how access is granted today;
  • how access should be granted in the future;
  • which memberships are temporary exceptions;
  • which memberships can be derived from authoritative data.

Avoid treating a migration as a direct one-to-one copy of existing groups.

A migration is an opportunity to replace historical access debt with a clearer access model.

A typical migration follows four phases:

Existing groups
    -> Discovery
        -> Migration collections
            -> Final access collections
                -> Group Link
                    -> Entra ID groups

Phase 1: Discovery

Identify:

  • existing groups;
  • existing owners;
  • current members;
  • access purpose;
  • source systems;
  • approval processes;
  • known exceptions.

For each access group ask:

Why is this identity a member?

If nobody can answer that question, the migration should not blindly preserve the membership.

Phase 2: Build the target model

Create the future-state collection design.

Typical building blocks:

Organizational collections
Attribute-based collections
Joinable collections
Exception collections
Final access collections

Use the design patterns documented in design-patterns.md.

Do not begin by importing memberships.

Begin by modelling how access should work.

Phase 3: Preserve existing access

When existing membership must be preserved temporarily, create a migration collection.

Example:

Migration - Finance reporting - Legacy membership

Members can be imported directly into that collection.

The migration collection is then included in the final access collection.

Access - Finance reporting - User
    contains Employees - Finance
    OR
    contains Requested access - Finance reporting
    OR
    contains Migration - Finance reporting - Legacy membership

This allows access continuity during the transition.

Phase 4: Remove migration membership

As each member is reviewed:

  • move them to criteria-based access;
  • move them to joinable access;
  • move them to exception collections;
  • remove unnecessary access.

Eventually:

Migration collection
    -> empty

The migration collection can then be retired.

Migration from Active Directory groups

A common starting point is:

AD Group
    -> Collection
        -> Group Link
            -> Entra ID Group

Do not assume every existing member belongs in the future-state model.

Typical findings include:

  • inactive users;
  • historical access;
  • temporary consultants;
  • service accounts;
  • inherited administrative memberships.

Review memberships before making them permanent.

Migration from Entra ID groups

Existing Entra ID groups can often be used during migration.

Pattern:

Existing Entra Group
    -> Migration Collection
        -> Final Access Collection
            -> Group Link
                -> Existing Entra Group

This allows the Entra group to remain the application-facing object while the membership source of truth moves into Identity Universe.

Criteria-first migration

Where access can be determined from authoritative data, prefer rebuilding access through criteria collections.

Example:

Current state:

Finance Reporting Group

Future state:

Employees - Finance
    -> Access - Finance reporting - User
        -> Group Link
            -> Finance Reporting Group

This removes manual administration and continuously aligns access with employment data.

Joinable migration

Some memberships cannot be reconstructed from authoritative data.

Typical examples:

  • business need;
  • project participation;
  • temporary responsibility;
  • specialist access.

Pattern:

Requested access - Application X

Existing members may be imported during migration while future access is granted through requests and approval.

Hybrid migration

Most production migrations end up using a hybrid model.

Example:

Employees - Finance
Requested access - Finance reporting
Migration - Finance reporting - Legacy membership
Exceptions - Finance reporting - Include

    -> Access - Finance reporting - User

Over time:

Migration membership
    -> reduced
    -> removed

while organizational and joinable memberships remain.

Migrating exceptions

Not every existing member belongs in a reusable criteria rule.

Where access is legitimate but uncommon:

Exceptions - Application X - Include

Document:

  • why the exception exists;
  • who approved it;
  • who owns it;
  • when it should be reviewed.

Avoid hiding exceptions directly inside increasingly complex criteria conditions.

Bulk import strategy

Joinable collections support administrative member import.

This is useful when:

  • hundreds of users already have access;
  • access must continue immediately after migration;
  • approval workflows should only apply to future requests.

Use migration collections or dedicated onboarding collections rather than importing members into unrelated collections without documentation.

Access review during migration

A migration is often the best opportunity to perform access cleanup.

Recommended review questions:

  • Does the person still require access?
  • Can access be determined automatically?
  • Should access become request-based?
  • Is this an exception?
  • Is there a business owner?

Do not treat existing access as automatically correct.

Once the final access collection is validated:

Final Access Collection
    -> Group Link
        -> Target Group

The collection becomes the source of truth.

Direct changes in the target group should no longer be treated as the authoritative access-management mechanism.

Large-scale migrations

For environments with many collections:

  1. Establish naming standards first.
  2. Establish metadata standards first.
  3. Create reusable organizational collections.
  4. Create joinable templates.
  5. Migrate low-risk access first.
  6. Validate Group Link behavior.
  7. Migrate high-impact access later.

Do not begin with the most critical access groups.

Use early migrations as validation of patterns and operational procedures.

Common anti-patterns

Recreating every historical group

Avoid rebuilding a legacy structure solely because it already exists.

Model access according to business requirements rather than historical implementation.

Permanent migration collections

Migration collections should have an exit strategy.

They are transitional components.

No ownership review

Every migrated access should have a known owner.

Skipping validation

Always compare:

Existing membership
vs
Expected membership
vs
Final collection membership

before cutover.

Multiple authorities

Do not allow:

  • legacy scripts;
  • manual administration;
  • Group Link;
  • automation platforms;

all to maintain the same membership simultaneously.

Migration checklist

  • [ ] Existing access documented.
  • [ ] Owners identified.
  • [ ] Target collection model designed.
  • [ ] Naming and metadata standards applied.
  • [ ] Criteria collections tested.
  • [ ] Joinable collections configured.
  • [ ] Exceptions documented.
  • [ ] Migration collections created where necessary.
  • [ ] Existing memberships reviewed.
  • [ ] Group Link validated.
  • [ ] Application access validated.
  • [ ] Legacy memberships removed.
  • [ ] Migration collections retired.