Refresh Token SCIM Design Document

Design Overview

This design implements refresh token management capabilities for Janssen Server, providing users with visibility and control over applications that have been granted refresh tokens. The solution follows OAuth 2.0 and OpenID Connect best practices while integrating seamlessly with Janssen Server's existing architecture.

The design recommends implementing the feature through the Config API approach, as it aligns better with administrative token management functions and provides more flexibility for future enhancements.

Architecture

High-Level Architecture

graph TB
    UI[User Interface] --> API[Config API Gateway]
    API --> Auth[Authentication Service]
    API --> TokenMgmt[Token Management Service]
    TokenMgmt --> TokenStore[Token Storage]
    TokenMgmt --> AuditLog[Audit Logging]
    TokenMgmt --> Cache[Token Cache]
    
    subgraph "Janssen Server Core"
        Auth
        TokenStore
        AuditLog
    end

Loading

API Integration Decision

Chosen Approach: Config API

Rationale:

• Config API is designed for administrative and management operations
• Better alignment with token lifecycle management functions
• More flexible authentication and authorization mechanisms
• Easier to extend for future administrative features
• Cleaner separation from user profile management (SCIM focus)

Components and Interfaces

1. Token Management Service

Purpose: Core business logic for refresh token operations

Key Methods:

public interface TokenManagementService {
    List<RefreshTokenMetadata> getUserRefreshTokens(String userId);
    boolean revokeRefreshToken(String userId, String tokenHash);
    RefreshTokenMetadata getTokenMetadata(String tokenHash);
}

2. Config API Endpoints

Base Path: /jans-config-api/api/v1/token-management

GET /refresh-tokens

• Purpose: Retrieve refresh token metadata for authenticated user
• Authentication: Bearer token (user's access token)
• Response: List of RefreshTokenMetadata objects

DELETE /refresh-tokens/{tokenHash}

• Purpose: Revoke specific refresh token by hash
• Authentication: Bearer token (user's access token)
• Authorization: User must own the token
• Response: Success/failure confirmation

3. Token Hash Service

Purpose: Generate and validate token hashes for secure token identification

Key Methods:

public interface TokenHashService {
    String generateTokenHash(String refreshToken);
    boolean validateTokenHash(String refreshToken, String hash);
}

4. Audit Service Integration

Purpose: Log all token management operations for security monitoring

Events Logged:

• Token metadata requests
• Token revocation attempts (success/failure)
• Unauthorized access attempts
• Administrative operations

Data Models

RefreshTokenMetadata

{
  "tokenHash": "sha256_hash_of_token",
  "clientId": "client_application_id",
  "clientName": "Human Readable App Name",
  "scopes": ["openid", "profile", "email"],
  "issuedAt": "2025-01-15T10:30:00Z",
  "lastUsed": "2025-01-20T14:22:00Z",
  "expiresAt": "2025-04-15T10:30:00Z",
  "deviceInfo": {
    "userAgent": "Mozilla/5.0...",
    "ipAddress": "192.168.1.100"
  }
}

API Response Models

Success Response

{
  "status": "success",
  "data": [...],
  "timestamp": "2025-01-20T15:30:00Z"
}

Error Response

{
  "status": "error",
  "error": {
    "code": "TOKEN_NOT_FOUND",
    "message": "The specified token hash was not found",
    "details": "Token may have already been revoked or expired"
  },
  "timestamp": "2025-01-20T15:30:00Z"
}

Error Handling

Error Categories

1. Authentication Errors (401)

   • Invalid or expired access token
   • Missing authentication header

2. Authorization Errors (403)

   • User attempting to access tokens they don't own
   • Insufficient permissions for operation

3. Not Found Errors (404)

   • Token hash not found
   • User has no refresh tokens

4. Validation Errors (400)

   • Invalid token hash format
   • Malformed request parameters

5. Server Errors (500)

   • Database connection issues
   • Internal service failures

Error Response Strategy

• Consistent error response format across all endpoints
• Detailed error codes for programmatic handling
• User-friendly error messages
• Security-conscious error messages (no sensitive data exposure)
• Proper HTTP status codes

Security Considerations

Authentication & Authorization

1. User Authentication

   • Require valid access token for all operations
   • Validate token signature and expiration
   • Extract user identity from token claims

2. Authorization Controls

   • Users can only access their own refresh tokens
   • Implement proper scope validation
   • Rate limiting on API endpoints

3. Token Hash Security

   • Use SHA-256 for token hashing
   • Include salt to prevent rainbow table attacks
   • Store only hashed versions in responses

Data Protection

1. Sensitive Data Handling

   • Never return actual refresh token values
   • Limit metadata exposure to necessary fields
   • Implement proper data retention policies

2. Audit Trail

   • Log all access attempts and operations
   • Include sufficient context for security analysis
   • Implement log rotation and retention

Testing Strategy

Unit Testing

1. Service Layer Tests

   • Token management service operations
   • Hash generation and validation
   • Error handling scenarios

2. API Controller Tests

   • Endpoint request/response handling
   • Authentication and authorization
   • Input validation

Integration Testing

1. Database Integration

   • Token storage and retrieval operations
   • Transaction handling
   • Connection pooling

2. External Service Integration

   • Authentication service integration
   • Audit logging integration
   • Cache layer integration

Security Testing

1. Authentication Testing

   • Invalid token scenarios
   • Token expiration handling
   • Cross-user access attempts

2. Authorization Testing

   • Permission boundary validation
   • Role-based access control
   • Privilege escalation prevention

Performance Testing

1. Load Testing

   • High-volume token listing requests
   • Concurrent revocation operations
   • Database query performance

2. Stress Testing

   • System behavior under extreme load
   • Resource exhaustion scenarios
   • Recovery mechanisms

Implementation Considerations

Database Schema Changes

New tables required:

• refresh_token_metadata - Store token metadata and hashes
• token_audit_log - Audit trail for token operations

Caching Strategy

• Cache frequently accessed token metadata
• Implement cache invalidation on token revocation
• Use distributed cache for multi-instance deployments

Monitoring & Observability

• Metrics for API endpoint usage
• Performance monitoring for database queries
• Alert thresholds for unusual token activity

Backward Compatibility

• Ensure existing refresh token functionality remains unchanged
• Gradual migration of existing tokens to include metadata
• Maintain API versioning for future enhancements