336 lines
8.7 KiB
Markdown
336 lines
8.7 KiB
Markdown
# Session Callback Logging - Impact Analysis
|
|
|
|
**Date**: 2026-01-01
|
|
**Purpose**: Analyze the impact of reducing session callback logging on the multi-stack architecture
|
|
|
|
---
|
|
|
|
## 🏗️ Architecture Overview
|
|
|
|
### Stack Components
|
|
1. **Next.js Dashboard** (this application)
|
|
2. **Keycloak** (SSO/Authentication provider)
|
|
3. **MinIO** (Object storage for files)
|
|
4. **External Services** (Leantime, Rocket.Chat, News API, etc.)
|
|
|
|
### Integration Points
|
|
- **Keycloak**: OAuth2/OIDC provider, session tokens, role extraction
|
|
- **MinIO**: File storage (mission logos, attachments), S3-compatible API
|
|
- **External APIs**: All require authenticated session
|
|
|
|
---
|
|
|
|
## 📋 Current Session Callback Logging
|
|
|
|
### What's Being Logged
|
|
```typescript
|
|
// Lines 407-472 in app/api/auth/options.ts
|
|
- === SESSION CALLBACK START ===
|
|
- Token error status
|
|
- Access token presence
|
|
- Refresh token presence
|
|
- Token roles
|
|
- Token sub (user ID)
|
|
- Token email
|
|
- Token name
|
|
- Token username
|
|
- User roles for session
|
|
- Creating session user object
|
|
- Setting session tokens
|
|
- ✅ Session created successfully
|
|
- Session user details
|
|
- === SESSION CALLBACK END ===
|
|
```
|
|
|
|
### Why It Was Added
|
|
**Historical Context** (from `DEBUG_502_CALLBACK.md`):
|
|
- Added specifically to debug **502 errors** with Keycloak callbacks
|
|
- Critical for diagnosing authentication failures
|
|
- Helps identify when session callback doesn't execute
|
|
- Essential for troubleshooting SSO flow issues
|
|
|
|
---
|
|
|
|
## 🔍 Impact Analysis
|
|
|
|
### 1. Keycloak Integration Impact
|
|
|
|
**Dependencies**:
|
|
- ✅ **No functional impact**: Logging doesn't affect Keycloak authentication
|
|
- ⚠️ **Debugging impact**: Removing logs makes troubleshooting harder
|
|
- ✅ **Error logging preserved**: Critical errors still logged
|
|
|
|
**Keycloak Flow**:
|
|
```
|
|
1. User authenticates → Keycloak
|
|
2. Keycloak redirects → Next.js callback
|
|
3. JWT callback extracts tokens
|
|
4. Session callback builds session ← LOGGING HERE
|
|
5. Session used for all API calls
|
|
```
|
|
|
|
**Recommendation**:
|
|
- Keep error logging (always)
|
|
- Make success logging conditional (DEBUG_SESSION flag)
|
|
|
|
---
|
|
|
|
### 2. MinIO Integration Impact
|
|
|
|
**Dependencies**:
|
|
- ✅ **No direct dependency**: MinIO doesn't use session callback logs
|
|
- ✅ **Uses session for auth**: Session object used to verify user permissions
|
|
- ✅ **No impact**: Logging changes won't affect MinIO operations
|
|
|
|
**MinIO Flow**:
|
|
```
|
|
1. API route calls getServerSession()
|
|
2. Session callback executes (builds session)
|
|
3. Session used to verify user authentication
|
|
4. MinIO operations proceed with authenticated user
|
|
```
|
|
|
|
**Recommendation**:
|
|
- ✅ **Safe to reduce logging**: No impact on MinIO functionality
|
|
|
|
---
|
|
|
|
### 3. External Services Impact
|
|
|
|
**Services**:
|
|
- Leantime (project management)
|
|
- Rocket.Chat (messaging)
|
|
- News API
|
|
- Email/IMAP
|
|
|
|
**Dependencies**:
|
|
- ✅ **No functional impact**: Services don't read logs
|
|
- ✅ **Session still created**: Logging doesn't affect session creation
|
|
- ✅ **Authentication works**: Session object still valid
|
|
|
|
**Recommendation**:
|
|
- ✅ **Safe to reduce logging**: No impact on external services
|
|
|
|
---
|
|
|
|
### 4. Monitoring & Debugging Impact
|
|
|
|
**Current Usage**:
|
|
- Debugging 502 errors (Keycloak callbacks)
|
|
- Troubleshooting authentication issues
|
|
- Monitoring session creation frequency
|
|
- Identifying session callback failures
|
|
|
|
**Impact of Reducing Logging**:
|
|
- ⚠️ **Harder to debug**: Less visibility into session creation
|
|
- ✅ **Still debuggable**: Error logging preserved
|
|
- ✅ **Can enable on-demand**: DEBUG_SESSION flag for troubleshooting
|
|
|
|
**Recommendation**:
|
|
- Use conditional logging with DEBUG_SESSION flag
|
|
- Keep error logging always enabled
|
|
- Document how to enable debug logging
|
|
|
|
---
|
|
|
|
## ✅ Safe Implementation Strategy
|
|
|
|
### Phase 1: Conditional Logging (Recommended)
|
|
|
|
**Approach**: Make success logging conditional, keep error logging always
|
|
|
|
```typescript
|
|
async session({ session, token }) {
|
|
try {
|
|
// Always log errors
|
|
if (token.error) {
|
|
console.error("❌ Session callback error:", token.error);
|
|
}
|
|
|
|
// Conditional verbose logging
|
|
const DEBUG_SESSION = process.env.DEBUG_SESSION === 'true' ||
|
|
process.env.NODE_ENV === 'development';
|
|
|
|
if (DEBUG_SESSION) {
|
|
console.log('=== SESSION CALLBACK START ===');
|
|
console.log('Token error:', token.error);
|
|
console.log('Has accessToken:', !!token.accessToken);
|
|
// ... rest of verbose logging
|
|
}
|
|
|
|
// Always log critical errors
|
|
if (token.error === "SessionNotActive" ||
|
|
token.error === "NoRefreshToken" ||
|
|
!token.accessToken ||
|
|
!token.refreshToken) {
|
|
console.log("❌ Session invalidated or tokens missing", {
|
|
error: token.error,
|
|
hasAccessToken: !!token.accessToken,
|
|
hasRefreshToken: !!token.refreshToken
|
|
});
|
|
return null as any;
|
|
}
|
|
|
|
// ... rest of callback logic
|
|
|
|
if (DEBUG_SESSION) {
|
|
console.log('✅ Session created successfully');
|
|
console.log('Session user id:', session.user.id);
|
|
console.log('=== SESSION CALLBACK END ===');
|
|
}
|
|
|
|
return session;
|
|
} catch (error) {
|
|
// Always log critical errors
|
|
console.error('❌❌❌ CRITICAL ERROR IN SESSION CALLBACK ❌❌❌');
|
|
console.error('Error:', error);
|
|
throw error;
|
|
}
|
|
}
|
|
```
|
|
|
|
**Benefits**:
|
|
- ✅ Production: Minimal logging (errors only)
|
|
- ✅ Development: Full logging for debugging
|
|
- ✅ On-demand: Enable with DEBUG_SESSION=true
|
|
- ✅ No functional impact
|
|
|
|
---
|
|
|
|
### Phase 2: Environment-Based Logging
|
|
|
|
**Alternative**: Use NODE_ENV
|
|
|
|
```typescript
|
|
const isDevelopment = process.env.NODE_ENV === 'development';
|
|
|
|
if (isDevelopment || token.error) {
|
|
// Verbose logging
|
|
}
|
|
```
|
|
|
|
**Benefits**:
|
|
- ✅ Simple implementation
|
|
- ✅ Automatic in development
|
|
- ⚠️ Less flexible than DEBUG_SESSION flag
|
|
|
|
---
|
|
|
|
## 🎯 Recommended Approach
|
|
|
|
### Option 1: DEBUG_SESSION Flag (Best)
|
|
|
|
**Implementation**:
|
|
- Add `DEBUG_SESSION` environment variable
|
|
- Default: `false` (minimal logging)
|
|
- Set to `true` when debugging needed
|
|
|
|
**Usage**:
|
|
```bash
|
|
# Production (minimal logging)
|
|
DEBUG_SESSION=false npm start
|
|
|
|
# Debugging (verbose logging)
|
|
DEBUG_SESSION=true npm start
|
|
```
|
|
|
|
**Pros**:
|
|
- ✅ Flexible (can enable on-demand)
|
|
- ✅ Production-friendly (minimal logs)
|
|
- ✅ Debug-friendly (full logs when needed)
|
|
- ✅ No code changes needed to toggle
|
|
|
|
**Cons**:
|
|
- ⚠️ Requires environment variable management
|
|
|
|
---
|
|
|
|
### Option 2: NODE_ENV Based (Simpler)
|
|
|
|
**Implementation**:
|
|
- Use `NODE_ENV === 'development'` for verbose logging
|
|
- Always log errors
|
|
|
|
**Pros**:
|
|
- ✅ Simple (no new env vars)
|
|
- ✅ Automatic (works with existing setup)
|
|
|
|
**Cons**:
|
|
- ⚠️ Less flexible (can't enable in production easily)
|
|
|
|
---
|
|
|
|
## 📊 Risk Assessment
|
|
|
|
| Risk | Impact | Mitigation |
|
|
|------|--------|------------|
|
|
| **Lost debugging capability** | Medium | Keep error logging, add DEBUG_SESSION flag |
|
|
| **Harder to troubleshoot 502 errors** | Medium | Document how to enable debug logging |
|
|
| **Performance impact** | Low | Logging overhead is minimal |
|
|
| **Functional impact** | None | Logging doesn't affect functionality |
|
|
|
|
---
|
|
|
|
## ✅ Final Recommendation
|
|
|
|
### Implementation Plan
|
|
|
|
1. **Keep Error Logging Always** ✅
|
|
- Critical errors always logged
|
|
- Session invalidation always logged
|
|
- Exception handling always logged
|
|
|
|
2. **Make Success Logging Conditional** ✅
|
|
- Use `DEBUG_SESSION` environment variable
|
|
- Default: `false` (production-friendly)
|
|
- Can enable: `DEBUG_SESSION=true` (debugging)
|
|
|
|
3. **Document Debugging Process** ✅
|
|
- Add to README or troubleshooting guide
|
|
- Explain when to enable DEBUG_SESSION
|
|
- Document what logs to look for
|
|
|
|
4. **Test in Staging** ✅
|
|
- Verify error logging still works
|
|
- Test with DEBUG_SESSION=true
|
|
- Test with DEBUG_SESSION=false
|
|
|
|
---
|
|
|
|
## 🔧 Implementation Checklist
|
|
|
|
- [ ] Update `app/api/auth/options.ts` with conditional logging
|
|
- [ ] Add `DEBUG_SESSION` to environment variable documentation
|
|
- [ ] Test error logging (should always work)
|
|
- [ ] Test success logging with DEBUG_SESSION=true
|
|
- [ ] Test success logging with DEBUG_SESSION=false
|
|
- [ ] Verify Keycloak authentication still works
|
|
- [ ] Verify MinIO operations still work
|
|
- [ ] Verify external services still work
|
|
- [ ] Update troubleshooting documentation
|
|
|
|
---
|
|
|
|
## 📝 Summary
|
|
|
|
**Impact Level**: 🟢 **LOW RISK**
|
|
|
|
**Key Findings**:
|
|
1. ✅ No functional impact on Keycloak, MinIO, or external services
|
|
2. ✅ Logging was added for debugging, not functionality
|
|
3. ✅ Error logging preserved (critical for troubleshooting)
|
|
4. ✅ Conditional logging provides flexibility
|
|
|
|
**Recommendation**:
|
|
- ✅ **Proceed with conditional logging**
|
|
- ✅ **Use DEBUG_SESSION flag for flexibility**
|
|
- ✅ **Keep error logging always enabled**
|
|
|
|
**Confidence**: 🟢 **HIGH** - Safe to implement
|
|
|
|
---
|
|
|
|
**Generated**: 2026-01-01
|
|
**Next Step**: Implement conditional logging in `app/api/auth/options.ts`
|
|
|