Federation Migration Guide

Step-by-step guide to migrating from local permissions to federated authorization.

This guide walks through migrating your applications from local permission systems to PlatformXe federated authorization. The process uses four phases to minimize risk.

Phase 1: Shadow mode

Run both your local permission system and PlatformXe side by side. On every permission check, call the shadow check endpoint to compare decisions.

// In your permission middleware
const localDecision = await localAuth.check(userId, path, action);

const shadow = await px.permissions.shadowCheck({
  adminId: userId,
  path,
  action,
  localDecision,
});

if (shadow.data.discrepancy) {
  logger.warn('Permission mismatch', {
    userId, path, action,
    local: shadow.data.localAllowed,
    remote: shadow.data.remoteAllowed,
  });
}

// Still use local decision during shadow phase
return localDecision;

Run shadow mode for at least one week under production traffic. Fix discrepancies by adjusting roles, policies, and overrides in PlatformXe.

Phase 2: Dual-write

Once discrepancies are near zero, start writing permission changes to both systems:

// When a role changes, update both
await localAuth.updateRole(roleId, changes);
await px.permissions.updateRole(roleId, changes);

This ensures PlatformXe stays in sync as you continue to make permission changes.

Phase 3: Read cutover

Switch your application to read permissions from PlatformXe instead of your local system. Keep the local system running as a fallback.

// Switch to PlatformXe as primary
const result = await px.permissions.check({
  adminId: userId,
  path,
  action,
});

return result.data.allowed;

Phase 4: Cleanup

After running on PlatformXe for at least two weeks with no issues:

1. Remove local permission tables and code
2. Remove dual-write logic
3. Remove shadow check calls
4. Update your CI to remove local permission tests

Federation-specific migration

If you are migrating multiple apps into a federation group:

1. Create the group and add all member apps with their prefixes
2. Register modules in each member app via the API
3. Pull modules into the federation namespace
4. Create federated roles that span modules across apps
5. Push permissions to all members
6. Run shadow checks per app before cutting over each one