Initial commit
This commit is contained in:
Zhongwei Li
417
commands/oauth-migrate.md
Normal file
417
commands/oauth-migrate.md
Normal file
@@ -0,0 +1,417 @@
|
||||
---
|
||||
description: Migration guide for moving from other auth providers to Auth0
|
||||
---
|
||||
|
||||
# OAuth Migration Guide
|
||||
|
||||
Migrate from other authentication providers to Auth0.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
/oauth-migrate [provider]
|
||||
```
|
||||
|
||||
Supported providers:
|
||||
- `firebase` - Firebase Authentication
|
||||
- `okta` - Okta
|
||||
- `cognito` - AWS Cognito
|
||||
- `keycloak` - Keycloak
|
||||
- `custom` - Custom JWT/OAuth implementation
|
||||
- `social-only` - Only social logins (no user DB)
|
||||
|
||||
---
|
||||
|
||||
## Migration: Firebase → Auth0
|
||||
|
||||
### Phase 1: Planning (1-2 hours)
|
||||
|
||||
**Assess current setup**:
|
||||
- How many users? (1k, 100k, 1M+)
|
||||
- Authentication methods? (email/password, social, custom)
|
||||
- Custom claims? (roles, metadata)
|
||||
- Token usage? (access tokens, ID tokens)
|
||||
|
||||
**Timeline**:
|
||||
- Small (1k users): 1 day
|
||||
- Medium (10k users): 3-5 days
|
||||
- Large (100k+ users): 1-2 weeks
|
||||
|
||||
**Parallel running** (recommended):
|
||||
- Keep Firebase running while testing Auth0
|
||||
- Gradual migration: 10% → 25% → 50% → 100%
|
||||
- Rollback plan: If Auth0 issues, fall back to Firebase
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Set Up Auth0 (1-2 hours)
|
||||
|
||||
```bash
|
||||
# Step 1: Create Auth0 account
|
||||
# https://auth0.com/signup
|
||||
|
||||
# Step 2: Create application
|
||||
/oauth-setup-auth0
|
||||
|
||||
# Step 3: Configure connections
|
||||
# - Enable database connection
|
||||
# - Enable same social connections as Firebase
|
||||
# - Copy social app credentials from Firebase
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: User Migration (1-3 days)
|
||||
|
||||
#### Option A: Automatic Migration (Recommended)
|
||||
|
||||
Use Auth0 extensibility to migrate users on first login:
|
||||
|
||||
```javascript
|
||||
// Auth0 Rule: Migrate users from Firebase
|
||||
module.exports = function(user, context, callback) {
|
||||
// Check if user already in Auth0
|
||||
if (user.identities && user.identities.length > 0) {
|
||||
return callback(null, user, context)
|
||||
}
|
||||
|
||||
// Try to authenticate against Firebase
|
||||
const firebase = require('firebase')
|
||||
|
||||
firebase.initializeApp({
|
||||
apiKey: process.env.FIREBASE_API_KEY,
|
||||
authDomain: process.env.FIREBASE_AUTH_DOMAIN,
|
||||
databaseURL: process.env.FIREBASE_DATABASE_URL
|
||||
})
|
||||
|
||||
firebase.auth().signInWithEmailAndPassword(user.email, context.request.query.password)
|
||||
.then(function(firebaseUser) {
|
||||
// Get Firebase custom claims
|
||||
firebaseUser.getIdTokenResult()
|
||||
.then(function(idTokenResult) {
|
||||
// Copy Firebase claims to Auth0
|
||||
user.app_metadata = user.app_metadata || {}
|
||||
user.app_metadata.firebase_id = firebaseUser.uid
|
||||
user.app_metadata.roles = idTokenResult.claims.roles || []
|
||||
|
||||
// Create Auth0 user
|
||||
context.clientMetadata = {
|
||||
firebase_migrated: 'true'
|
||||
}
|
||||
|
||||
callback(null, user, context)
|
||||
})
|
||||
})
|
||||
.catch(function(error) {
|
||||
callback(new Error('Firebase auth failed: ' + error.message))
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
**Benefits**:
|
||||
- ✅ No downtime
|
||||
- ✅ Users migrate automatically on first login
|
||||
- ✅ Can run parallel with Firebase
|
||||
- ✅ Easy rollback
|
||||
|
||||
**Timeline**: 2-3 weeks (let users naturally migrate)
|
||||
|
||||
---
|
||||
|
||||
#### Option B: Bulk Migration
|
||||
|
||||
Export Firebase users and import to Auth0:
|
||||
|
||||
```bash
|
||||
# Step 1: Export users from Firebase
|
||||
firebase auth:export users.json --format json
|
||||
|
||||
# Step 2: Transform to Auth0 format
|
||||
node transform-firebase-to-auth0.js
|
||||
|
||||
# Step 3: Import to Auth0
|
||||
# Auth0 Dashboard → Users → Import (drag CSV)
|
||||
# Or use Management API
|
||||
```
|
||||
|
||||
**transform-firebase-to-auth0.js**:
|
||||
```javascript
|
||||
const fs = require('fs')
|
||||
|
||||
const firebaseUsers = JSON.parse(fs.readFileSync('users.json', 'utf8'))
|
||||
|
||||
const auth0Users = firebaseUsers.users.map(user => ({
|
||||
email: user.email,
|
||||
email_verified: user.emailVerified,
|
||||
user_id: user.localId,
|
||||
identities: [{
|
||||
connection: 'Username-Password-Authentication',
|
||||
user_id: user.localId,
|
||||
provider: 'auth0',
|
||||
isSocial: false
|
||||
}],
|
||||
user_metadata: user.customClaims || {},
|
||||
app_metadata: {
|
||||
roles: user.customClaims?.roles || [],
|
||||
firebase_id: user.localId
|
||||
},
|
||||
blocked: !user.emailVerified,
|
||||
created_at: new Date(parseInt(user.createdAt)).toISOString(),
|
||||
updated_at: new Date(parseInt(user.lastLoginAt)).toISOString()
|
||||
}))
|
||||
|
||||
fs.writeFileSync('auth0-users.json', JSON.stringify(auth0Users, null, 2))
|
||||
console.log(`Converted ${auth0Users.length} users`)
|
||||
```
|
||||
|
||||
**Timeline**: 1-2 hours (bulk import) + verification
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Update Application Code (2-4 hours)
|
||||
|
||||
#### Frontend Migration (React)
|
||||
|
||||
```typescript
|
||||
// BEFORE (Firebase)
|
||||
import { initializeApp } from 'firebase/app'
|
||||
import { getAuth, signInWithEmailAndPassword } from 'firebase/auth'
|
||||
|
||||
const app = initializeApp(firebaseConfig)
|
||||
const auth = getAuth(app)
|
||||
|
||||
async function login(email, password) {
|
||||
const userCredential = await signInWithEmailAndPassword(auth, email, password)
|
||||
const token = await userCredential.user.getIdToken()
|
||||
return token
|
||||
}
|
||||
|
||||
// AFTER (Auth0)
|
||||
import { useAuth0 } from '@auth0/auth0-react'
|
||||
|
||||
function LoginPage() {
|
||||
const { loginWithRedirect } = useAuth0()
|
||||
|
||||
return (
|
||||
<button onClick={() => loginWithRedirect()}>
|
||||
Login with Auth0
|
||||
</button>
|
||||
)
|
||||
}
|
||||
|
||||
export default function App() {
|
||||
const { getAccessTokenSilently } = useAuth0()
|
||||
|
||||
async function getToken() {
|
||||
return await getAccessTokenSilently()
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Backend Migration (Node.js)
|
||||
|
||||
```typescript
|
||||
// BEFORE (Firebase)
|
||||
import * as admin from 'firebase-admin'
|
||||
|
||||
const app = admin.initializeApp()
|
||||
|
||||
function verifyToken(token) {
|
||||
return admin.auth().verifyIdToken(token)
|
||||
}
|
||||
|
||||
// AFTER (Auth0)
|
||||
import { expressjwt } from 'express-jwt'
|
||||
import jwksRsa from 'jwks-rsa'
|
||||
|
||||
const checkJwt = expressjwt({
|
||||
secret: jwksRsa.expressJwtSecret({
|
||||
jwksUri: `https://${process.env.AUTH0_DOMAIN}/.well-known/jwks.json`
|
||||
}),
|
||||
audience: `https://${process.env.AUTH0_DOMAIN}/api/v2/`,
|
||||
issuer: `https://${process.env.AUTH0_DOMAIN}/`,
|
||||
algorithms: ['RS256']
|
||||
})
|
||||
|
||||
app.get('/api/protected', checkJwt, (req, res) => {
|
||||
res.json({ user: req.auth.sub })
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 5: Testing (1-2 days)
|
||||
|
||||
```typescript
|
||||
// Test list
|
||||
- [ ] User login (email/password)
|
||||
- [ ] User signup
|
||||
- [ ] Social login (Google, GitHub, etc)
|
||||
- [ ] Password reset
|
||||
- [ ] Token refresh
|
||||
- [ ] API access with token
|
||||
- [ ] MFA (if enabled)
|
||||
- [ ] Logout clears session
|
||||
- [ ] Session persistence
|
||||
- [ ] Error handling (invalid password, etc)
|
||||
```
|
||||
|
||||
**Test script**:
|
||||
```bash
|
||||
# Test login flow
|
||||
curl -X POST https://YOUR_DOMAIN/oauth/token \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"client_id": "YOUR_CLIENT_ID",
|
||||
"client_secret": "YOUR_CLIENT_SECRET",
|
||||
"audience": "https://YOUR_DOMAIN/api/v2/",
|
||||
"grant_type": "client_credentials"
|
||||
}'
|
||||
|
||||
# Test protected API
|
||||
curl -H "Authorization: Bearer ACCESS_TOKEN" \
|
||||
http://localhost:3001/api/protected
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 6: Deployment (2-4 hours)
|
||||
|
||||
**Deployment checklist**:
|
||||
- [ ] Update environment variables
|
||||
- [ ] Deploy frontend to staging
|
||||
- [ ] Deploy backend to staging
|
||||
- [ ] Run full test suite
|
||||
- [ ] Smoke test in production-like environment
|
||||
- [ ] Deploy to production
|
||||
- [ ] Monitor Auth0 logs for errors
|
||||
- [ ] Monitor application errors
|
||||
- [ ] Have rollback plan ready
|
||||
|
||||
**Gradual rollout**:
|
||||
1. Deploy to 10% of users
|
||||
2. Monitor for 2-4 hours
|
||||
3. If OK, deploy to 50%
|
||||
4. Monitor for 2-4 hours
|
||||
5. Deploy to 100%
|
||||
|
||||
---
|
||||
|
||||
## Migration: Cognito → Auth0
|
||||
|
||||
### Key Differences
|
||||
|
||||
| Feature | Cognito | Auth0 |
|
||||
|---------|---------|-------|
|
||||
| Setup | AWS Dashboard (complex) | Auth0 Dashboard (simple) |
|
||||
| Scopes | Fixed scopes | Custom scopes |
|
||||
| Rules | Limited | Powerful (JavaScript) |
|
||||
| User management | Via AWS API | Via UI or API |
|
||||
| Custom claims | userAttributes | app_metadata, user_metadata |
|
||||
| MFA | Built-in | Multiple options |
|
||||
| Cost | Pay per user | Fixed tier |
|
||||
|
||||
### Migration Steps
|
||||
|
||||
1. **Export Cognito users**:
|
||||
```bash
|
||||
aws cognito-idp list-users --user-pool-id us-east-1_xxx > cognito-users.json
|
||||
```
|
||||
|
||||
2. **Transform to Auth0 format**:
|
||||
```javascript
|
||||
// Similar to Firebase migration
|
||||
// Map Cognito attributes to Auth0 metadata
|
||||
```
|
||||
|
||||
3. **Update token validation**:
|
||||
```typescript
|
||||
// Change from Cognito to Auth0 jwks URI
|
||||
jwksUri: `https://${AUTH0_DOMAIN}/.well-known/jwks.json`
|
||||
```
|
||||
|
||||
4. **Update frontend SDK**:
|
||||
```typescript
|
||||
// Replace Amplify with Auth0 SDK
|
||||
import { useAuth0 } from '@auth0/auth0-react'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Rollback Plan
|
||||
|
||||
### If issues occur:
|
||||
|
||||
1. **Immediately revert** to previous provider
|
||||
2. **Keep both systems running** during migration
|
||||
3. **Have database backup** before migration
|
||||
4. **Monitor error rates** during rollout
|
||||
|
||||
```bash
|
||||
# Revert frontend
|
||||
git revert <commit> # Go back to old SDK
|
||||
npm install # Reinstall old packages
|
||||
npm run deploy # Deploy rollback
|
||||
|
||||
# Check status
|
||||
Auth0 Dashboard → Logs (verify no new logins via Auth0)
|
||||
Firebase Console → Logs (verify resumed usage)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Post-Migration
|
||||
|
||||
### Cleanup
|
||||
- [ ] Decommission old auth system
|
||||
- [ ] Delete old user data (after retention period)
|
||||
- [ ] Update documentation
|
||||
- [ ] Train team on new system
|
||||
- [ ] Close old auth provider account
|
||||
|
||||
### Optimization
|
||||
- [ ] Review Auth0 rules for performance
|
||||
- [ ] Optimize token expiration
|
||||
- [ ] Set up audit logging
|
||||
- [ ] Monitor costs
|
||||
- [ ] Plan security hardening
|
||||
|
||||
---
|
||||
|
||||
## Common Migration Issues
|
||||
|
||||
| Issue | Solution |
|
||||
|-------|----------|
|
||||
| User exists error on import | Deduplicate by email before import |
|
||||
| Scopes missing | Manually add to Auth0 API config |
|
||||
| Custom claims lost | Map to user_metadata in Auth0 |
|
||||
| Password reset broken | Reconfigure email templates in Auth0 |
|
||||
| Social login not working | Re-add social app credentials |
|
||||
|
||||
---
|
||||
|
||||
## Timeline Summary
|
||||
|
||||
| Provider | Automatic | Bulk | Total |
|
||||
|----------|-----------|------|-------|
|
||||
| Firebase (1k users) | 2-3 weeks | 3-5 days | 1 week |
|
||||
| Firebase (100k users) | 3-4 weeks | 2-3 weeks | 4-5 weeks |
|
||||
| Cognito (any size) | 2-3 weeks | Similar to Firebase | 3-5 weeks |
|
||||
| Custom OAuth (simple) | 1 week | 2-3 days | 1 week |
|
||||
| Custom OAuth (complex) | 2-3 weeks | 1-2 weeks | 3-4 weeks |
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Choose migration strategy** (automatic vs bulk)
|
||||
2. **Set up Auth0 tenant** (`/oauth-setup-auth0`)
|
||||
3. **Test integration** (`/oauth-implement [framework]`)
|
||||
4. **Run security audit** (`/oauth-security-audit`)
|
||||
5. **Execute migration** (follow phase-by-phase plan)
|
||||
6. **Monitor closely** during first week
|
||||
|
||||
---
|
||||
|
||||
**Status**: Migration guide ready!
|
||||
**Need help?** `/oauth-troubleshoot` or contact Auth0 support
|
||||
Reference in New Issue
Block a user