docs/IDENTITY_MIGRATION_GUIDE.md

Identity System Migration Guide

Date: 2025-01-27 Purpose: Guide for migrating projects to unified identity system Status: Complete

---

Overview

This guide provides instructions for migrating projects to use the unified identity system (Keycloak).

---

Prerequisites

• Keycloak deployed and configured
• Realm created
• Client configured
• Users and roles set up

---

Migration Steps

Step 1: Install Keycloak Client

pnpm add keycloak-js

Step 2: Configure Keycloak Client

import Keycloak from 'keycloak-js';

const keycloak = new Keycloak({
  url: process.env.KEYCLOAK_URL || 'http://keycloak:8080',
  realm: process.env.KEYCLOAK_REALM || 'workspace',
  clientId: process.env.KEYCLOAK_CLIENT_ID || 'workspace-api',
});

Step 3: Initialize Keycloak

async function initKeycloak() {
  try {
    const authenticated = await keycloak.init({
      onLoad: 'login-required',
      checkLoginIframe: false,
    });

    if (authenticated) {
      console.log('User authenticated');
    }
  } catch (error) {
    console.error('Keycloak initialization failed', error);
  }
}

Step 4: Update Authentication

Before:

// Old authentication
const token = await getTokenFromLocalStorage();
const response = await fetch('/api/users', {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

After:

// New Keycloak authentication
const token = keycloak.token;
const response = await fetch('/api/users', {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

Step 5: Update Authorization

Before:

// Old role checking
if (user.roles.includes('admin')) {
  // Admin action
}

After:

// New Keycloak role checking
if (keycloak.hasRealmRole('admin')) {
  // Admin action
}

Step 6: Update Backend

import { verifyToken } from '@workspace/shared-auth';

async function authenticateRequest(req: Request) {
  const token = req.headers.authorization?.replace('Bearer ', '');
  if (!token) {
    throw new Error('No token provided');
  }

  // Verify token with Keycloak
  const decoded = await verifyToken(token, {
    issuer: process.env.KEYCLOAK_ISSUER,
    audience: process.env.KEYCLOAK_CLIENT_ID,
  });

  return decoded;
}

---

Best Practices

Token Management

• Use Keycloak token refresh
• Handle token expiration
• Store tokens securely

Role Management

• Use realm roles for global permissions
• Use client roles for application-specific permissions
• Map roles consistently

User Management

• Use Keycloak user federation
• Sync users from external systems
• Manage users centrally

---

Migration Checklist

• Install Keycloak client
• Configure Keycloak connection
• Update authentication code
• Update authorization code
• Update backend verification
• Test authentication
• Test authorization
• Update documentation
• Migrate users
• Set up user federation (if needed)

---

Last Updated: 2025-01-27