164 lines
3.0 KiB
Markdown
164 lines
3.0 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
pnpm add keycloak-js
|
|
```
|
|
|
|
### Step 2: Configure Keycloak Client
|
|
|
|
```typescript
|
|
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
|
|
|
|
```typescript
|
|
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**:
|
|
```typescript
|
|
// Old authentication
|
|
const token = await getTokenFromLocalStorage();
|
|
const response = await fetch('/api/users', {
|
|
headers: {
|
|
'Authorization': `Bearer ${token}`,
|
|
},
|
|
});
|
|
```
|
|
|
|
**After**:
|
|
```typescript
|
|
// New Keycloak authentication
|
|
const token = keycloak.token;
|
|
const response = await fetch('/api/users', {
|
|
headers: {
|
|
'Authorization': `Bearer ${token}`,
|
|
},
|
|
});
|
|
```
|
|
|
|
### Step 5: Update Authorization
|
|
|
|
**Before**:
|
|
```typescript
|
|
// Old role checking
|
|
if (user.roles.includes('admin')) {
|
|
// Admin action
|
|
}
|
|
```
|
|
|
|
**After**:
|
|
```typescript
|
|
// New Keycloak role checking
|
|
if (keycloak.hasRealmRole('admin')) {
|
|
// Admin action
|
|
}
|
|
```
|
|
|
|
### Step 6: Update Backend
|
|
|
|
```typescript
|
|
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
|
|
|