Skip to content

Refresh Token SCIM Design Document

Jump to bottom
Michael Schwartz edited this page Aug 14, 2025 · 2 revisions

Design Document: Refresh Token Management

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 implements the feature through the SCIM API approach, integrating with existing identity management tools and leveraging SCIM's established patterns for user resource management.

Architecture

High-Level Architecture

graph TB
    UI[User Interface] --> SCIM[SCIM API Gateway]
    SCIM --> Auth[SCIM Authentication]
    SCIM --> UserMgmt[User Management Service]
    UserMgmt --> TokenExt[Token Extension Service]
    TokenExt --> TokenStore[Token Storage]
    TokenExt --> AuditLog[Audit Logging]
    
    subgraph "Janssen Server Core"
        Auth
        TokenStore
        AuditLog
    end
    
    subgraph "SCIM Framework"
        UserMgmt
        TokenExt
    end
Loading

API Integration Decision

Chosen Approach: SCIM API

Rationale:

  • SCIM already handles user resource management and extensions
  • Leverages existing SCIM authentication and authorization patterns
  • Integrates naturally with identity management workflows
  • Follows established SCIM extension patterns for custom attributes
  • Provides consistent API patterns with existing user management features

Components and Interfaces

1. SCIM User Extension for Refresh Tokens

Purpose: Extend SCIM User resource with refresh token management capabilities

SCIM Extension Schema:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User", 
             "urn:gluu:params:scim:schemas:extension:RefreshTokens"],
  "urn:gluu:params:scim:schemas:extension:RefreshTokens": {
    "refreshTokens": [...]
  }
}

2. SCIM API Endpoints

Base Path: /jans-scim/restv1/v2/Users/{userId}

GET /Users/{userId}?attributes=urn:gluu:params:scim:schemas:extension:RefreshTokens

  • Purpose: Retrieve user with refresh token extension data
  • Authentication: SCIM Bearer token or OAuth token
  • Response: SCIM User resource with refresh token metadata
  • Filter: Only return refresh token extension attributes

PATCH /Users/{userId}

  • Purpose: Revoke refresh tokens using SCIM PATCH operations
  • Authentication: SCIM Bearer token or OAuth token
  • Authorization: User must own the tokens or have admin privileges
  • Request Body: SCIM PATCH operation to remove specific tokens
  • Response: Updated SCIM User resource

3. SCIM Extension Service

Purpose: Handle SCIM extension operations for refresh tokens

Key Methods:

public interface RefreshTokenExtensionService {
    ScimExtension getUserRefreshTokens(String userId);
    ScimUser revokeRefreshToken(String userId, String tokenHash, PatchRequest patchRequest);
    boolean validateTokenOwnership(String userId, String tokenHash);
}

4. 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);
}

5. SCIM Audit Integration

Purpose: Log all SCIM operations related to token management

Events Logged:

  • SCIM User resource access with token extension
  • SCIM PATCH operations for token revocation
  • Authentication and authorization events
  • Extension-specific operations

Data Models

SCIM User Resource with Refresh Token Extension

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:gluu:params:scim:schemas:extension:RefreshTokens"
  ],
  "id": "user123",
  "userName": "john.doe@example.com",
  "urn:gluu:params:scim:schemas:extension:RefreshTokens": {
    "refreshTokens": [
      {
        "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"
        }
      }
    ]
  },
  "meta": {
    "resourceType": "User",
    "created": "2025-01-10T10:00:00Z",
    "lastModified": "2025-01-20T15:30:00Z",
    "location": "/Users/user123"
  }
}

SCIM PATCH Request for Token Revocation

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "remove",
      "path": "urn:gluu:params:scim:schemas:extension:RefreshTokens:refreshTokens[tokenHash eq \"sha256_hash_of_token\"]"
    }
  ]
}

SCIM Error Response

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": "404",
  "scimType": "noTarget",
  "detail": "The specified refresh token was not found or has already been revoked"
}

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

Clone this wiki locally