Skip to content

RFC 7523 Enhancement Requirements, Design, Tasks

Jump to bottom
Michael Schwartz edited this page Aug 18, 2025 · 1 revision

Requirements Document

Introduction

This document outlines the requirements for implementing RFC 7523 "JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants" support in the Janssen Auth Server. This implementation will enable clients to use JWT Bearer tokens for both client authentication and as authorization grants when requesting OAuth 2.0 access tokens.

RFC 7523 defines two primary use cases:

  1. Using JWTs as authorization grants to request access tokens
  2. Using JWTs for client authentication when interacting with the token endpoint

The implementation must ensure full compliance with the RFC 7523 specification while integrating seamlessly with Janssen's existing OAuth 2.0 infrastructure.

Requirements

Requirement 1

User Story: As an OAuth 2.0 client developer, I want to use JWT Bearer tokens as authorization grants, so that I can request access tokens using existing trust relationships without direct user approval.

Acceptance Criteria

  1. WHEN a client sends a token request with grant_type "urn:ietf:params:oauth:grant-type:jwt-bearer" THEN the authorization server SHALL accept and process the JWT assertion
  2. WHEN the assertion parameter contains a valid JWT THEN the authorization server SHALL validate the JWT according to RFC 7523 requirements
  3. WHEN the JWT contains required claims (iss, sub, aud, exp) THEN the authorization server SHALL process the authorization grant request
  4. WHEN the JWT is invalid or expired THEN the authorization server SHALL return an "invalid_grant" error response
  5. WHEN the scope parameter is included THEN the authorization server SHALL honor the requested scope if authorized

Requirement 2

User Story: As an OAuth 2.0 client developer, I want to use JWT Bearer tokens for client authentication, so that I can authenticate to the token endpoint using cryptographic assertions instead of shared secrets.

Acceptance Criteria

  1. WHEN a client sends client_assertion_type "urn:ietf:params:oauth:client-assertion-type:jwt-bearer" THEN the authorization server SHALL accept JWT-based client authentication
  2. WHEN the client_assertion parameter contains a valid JWT THEN the authorization server SHALL validate the JWT for client authentication
  3. WHEN the JWT subject claim equals the client_id THEN the authorization server SHALL authenticate the client
  4. WHEN the JWT client authentication is invalid THEN the authorization server SHALL return an "invalid_client" error response
  5. WHEN JWT client authentication is used with any grant type THEN the authorization server SHALL process the complete request

Requirement 3

User Story: As a system administrator, I want JWT validation to follow RFC 7523 security requirements, so that the system maintains proper security posture and prevents token abuse.

Acceptance Criteria

  1. WHEN validating JWTs THEN the authorization server SHALL verify the digital signature or MAC
  2. WHEN checking JWT claims THEN the authorization server SHALL validate iss, sub, aud, and exp claims as required
  3. WHEN the aud claim is present THEN the authorization server SHALL verify it contains the server's identity
  4. WHEN the exp claim indicates expiration THEN the authorization server SHALL reject expired tokens with allowable clock skew
  5. WHEN nbf claim is present THEN the authorization server SHALL not accept tokens before the specified time
  6. WHEN jti claim is present THEN the authorization server SHALL optionally implement replay protection
  7. WHEN iat claim is present THEN the authorization server SHALL optionally validate reasonable issuance time

Requirement 4

User Story: As a system administrator, I want to configure JWT Bearer token support, so that I can control which clients and issuers are authorized to use JWT assertions.

Acceptance Criteria

  1. WHEN configuring JWT support THEN the system SHALL allow enabling/disabling JWT Bearer grant type
  2. WHEN configuring client authentication THEN the system SHALL allow enabling/disabling JWT Bearer client authentication
  3. WHEN managing trusted issuers THEN the system SHALL provide configuration for authorized JWT issuers
  4. WHEN managing audience validation THEN the system SHALL allow configuration of accepted audience values
  5. WHEN configuring key validation THEN the system SHALL support JWKS endpoints and static key configuration

Requirement 5

User Story: As a developer integrating with Janssen, I want comprehensive error handling for JWT Bearer tokens, so that I can properly diagnose and handle authentication and authorization failures.

Acceptance Criteria

  1. WHEN JWT signature validation fails THEN the system SHALL return appropriate error responses with descriptive messages
  2. WHEN required claims are missing THEN the system SHALL return "invalid_grant" or "invalid_client" with specific error descriptions
  3. WHEN audience validation fails THEN the system SHALL return error responses indicating audience mismatch
  4. WHEN JWT is expired or not yet valid THEN the system SHALL return temporal validation error responses
  5. WHEN issuer is not trusted THEN the system SHALL return issuer validation error responses

Requirement 6

User Story: As a system administrator, I want JWT Bearer token processing to integrate with existing Janssen features, so that JWT-based flows work with scopes, client policies, and audit logging.

Acceptance Criteria

  1. WHEN processing JWT authorization grants THEN the system SHALL apply existing scope validation and policies
  2. WHEN authenticating clients with JWTs THEN the system SHALL integrate with existing client management and policies
  3. WHEN JWT Bearer tokens are used THEN the system SHALL generate appropriate audit logs and metrics
  4. WHEN JWT processing occurs THEN the system SHALL respect existing rate limiting and security policies
  5. WHEN JWT Bearer flows complete THEN the system SHALL issue standard OAuth 2.0 access tokens with proper metadata

Requirement 7

User Story: As a system operator, I want JWT Bearer token support to be performant and scalable, so that it doesn't impact overall system performance.

Acceptance Criteria

  1. WHEN validating JWT signatures THEN the system SHALL cache public keys and JWKS responses appropriately
  2. WHEN processing multiple JWT requests THEN the system SHALL handle concurrent validation efficiently
  3. WHEN JWT validation fails THEN the system SHALL fail fast without unnecessary processing
  4. WHEN caching JWT validation results THEN the system SHALL respect token expiration and replay protection requirements
  5. WHEN monitoring JWT processing THEN the system SHALL provide metrics for validation success/failure rates and performance

Design Document

Overview

This design document outlines the implementation of RFC 7523 "JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants" in the Janssen Auth Server. The implementation will add support for:

  1. JWT Bearer Authorization Grants - Using JWTs as authorization grants to request access tokens
  2. JWT Bearer Client Authentication - Using JWTs for client authentication at the token endpoint

The design leverages Janssen's existing OAuth 2.0 infrastructure, JWT handling capabilities, and client authentication framework while ensuring full RFC 7523 compliance.

Architecture

High-Level Architecture

graph TB
    Client[OAuth 2.0 Client] --> TokenEndpoint[Token Endpoint]
    TokenEndpoint --> GrantHandler[Grant Type Handler]
    TokenEndpoint --> AuthHandler[Client Auth Handler]
    
    GrantHandler --> JWTBearerGrant[JWT Bearer Grant Processor]
    AuthHandler --> JWTBearerAuth[JWT Bearer Auth Processor]
    
    JWTBearerGrant --> JWTValidator[JWT Validator Service]
    JWTBearerAuth --> JWTValidator
    
    JWTValidator --> CryptoProvider[Crypto Provider]
    JWTValidator --> ClientService[Client Service]
    JWTValidator --> ConfigService[Configuration Service]
    
    JWTBearerGrant --> TokenService[Token Service]
    JWTBearerAuth --> TokenService
Loading

Integration Points

The JWT Bearer implementation integrates with existing Janssen components:

  • TokenRestWebServiceImpl - Main token endpoint implementation
  • GrantType enum - Extended to include JWT_BEARER grant type
  • ClientAssertion - Existing JWT client authentication infrastructure
  • AbstractCryptoProvider - JWT signature validation
  • Client - Client configuration and validation
  • AppConfiguration - Server configuration for JWT Bearer support

Components and Interfaces

1. Grant Type Extension

GrantType Enum Enhancement

public enum GrantType implements HasParamName, AttributeEnum {
    // Existing grant types...
    JWT_BEARER("urn:ietf:params:oauth:grant-type:jwt-bearer");
}

2. JWT Bearer Grant Handler

JwtBearerGrantHandler

  • Processes JWT Bearer authorization grant requests
  • Validates JWT assertions according to RFC 7523
  • Integrates with existing token issuance flow

Key Responsibilities:

  • Parse and validate JWT assertion parameter
  • Verify JWT signature and claims
  • Extract subject and scope information
  • Generate access tokens based on validated assertions

3. JWT Bearer Authentication Processor

JwtBearerAuthProcessor

  • Extends existing ClientAssertion functionality
  • Handles JWT-based client authentication
  • Validates client identity through JWT assertions

Key Responsibilities:

  • Process client_assertion_type and client_assertion parameters
  • Validate JWT for client authentication
  • Verify client_id matches JWT subject claim
  • Integrate with existing authentication flow

4. JWT Validation Service

JwtBearerValidationService

  • Centralized JWT validation logic for both grant and authentication flows
  • Implements RFC 7523 validation requirements
  • Handles signature verification and claim validation

Key Responsibilities:

  • Validate required claims (iss, sub, aud, exp)
  • Verify JWT signature using configured keys
  • Check temporal validity (exp, nbf, iat)
  • Implement replay protection (optional jti handling)
  • Validate audience claims against server configuration

5. Configuration Extensions

JWT Bearer Configuration Properties

@DocProperty(description = "Enable JWT Bearer grant type support")
private Boolean jwtBearerGrantEnabled = false;

@DocProperty(description = "Enable JWT Bearer client authentication")
private Boolean jwtBearerClientAuthEnabled = false;

@DocProperty(description = "Accepted audience values for JWT Bearer tokens")
private List<String> jwtBearerAcceptedAudiences = new ArrayList<>();

@DocProperty(description = "Maximum JWT lifetime in seconds")
private Integer jwtBearerMaxLifetime = 3600;

@DocProperty(description = "Enable JWT replay protection using jti claim")
private Boolean jwtBearerReplayProtectionEnabled = false;

Data Models

1. JWT Bearer Grant Request

public class JwtBearerGrantRequest {
    private String grantType; // "urn:ietf:params:oauth:grant-type:jwt-bearer"
    private String assertion; // JWT assertion
    private String scope;     // Optional scope parameter
    private String clientId;  // Optional client identification
}

2. JWT Bearer Validation Context

public class JwtBearerValidationContext {
    private Jwt jwt;
    private String clientId;
    private ValidationPurpose purpose; // AUTHORIZATION_GRANT or CLIENT_AUTHENTICATION
    private List<String> acceptedAudiences;
    private Integer maxLifetime;
    private boolean replayProtectionEnabled;
}

3. JWT Bearer Validation Result

public class JwtBearerValidationResult {
    private boolean valid;
    private String subject;
    private String issuer;
    private List<String> scopes;
    private String errorCode;
    private String errorDescription;
    private Date expiration;
}

Error Handling

1. Authorization Grant Errors

Following RFC 7523 Section 3.1, invalid JWT authorization grants return:

  • Error Code: invalid_grant
  • HTTP Status: 400 Bad Request
  • Error Descriptions: Specific validation failure reasons

Common Error Scenarios:

  • Invalid JWT signature → "JWT signature validation failed"
  • Missing required claims → "Missing required claim: [claim_name]"
  • Expired JWT → "JWT has expired"
  • Invalid audience → "Audience validation failed"
  • Untrusted issuer → "JWT issuer not trusted"

2. Client Authentication Errors

Following RFC 7523 Section 3.2, invalid JWT client authentication returns:

  • Error Code: invalid_client
  • HTTP Status: 401 Unauthorized
  • Error Descriptions: Specific authentication failure reasons

Common Error Scenarios:

  • Subject mismatch → "JWT subject does not match client_id"
  • Invalid assertion type → "Unsupported client assertion type"
  • Missing client assertion → "Client assertion required but not provided"

3. Error Response Format

{
  "error": "invalid_grant",
  "error_description": "JWT signature validation failed",
  "error_uri": "https://tools.ietf.org/html/rfc7523#section-3"
}

Testing Strategy

1. Unit Tests

JWT Validation Tests

  • Valid JWT processing with all required claims
  • Invalid signature handling
  • Expired token rejection
  • Missing claim validation
  • Audience validation scenarios
  • Replay protection testing (when enabled)

Grant Type Handler Tests

  • Valid JWT Bearer grant processing
  • Integration with token issuance
  • Scope handling and validation
  • Error response generation

Client Authentication Tests

  • Valid JWT client authentication
  • Subject/client_id matching
  • Integration with existing auth flow
  • Error handling scenarios

2. Integration Tests

Token Endpoint Integration

  • End-to-end JWT Bearer grant flow
  • JWT client authentication with various grant types
  • Combined JWT authentication and authorization
  • Configuration-driven behavior testing

Security Tests

  • Signature tampering detection
  • Replay attack prevention
  • Clock skew handling
  • Malformed JWT handling

3. Performance Tests

JWT Processing Performance

  • Signature verification performance
  • Concurrent request handling
  • Key caching effectiveness
  • Memory usage optimization

Implementation Phases

Phase 1: Core JWT Bearer Grant Support

  1. Extend GrantType enum with JWT_BEARER
  2. Implement JwtBearerGrantHandler
  3. Add JWT validation service
  4. Integrate with TokenRestWebServiceImpl
  5. Add basic configuration properties

Phase 2: Enhanced JWT Bearer Client Authentication

  1. Extend existing ClientAssertion functionality
  2. Implement enhanced JWT validation for client auth
  3. Add client authentication integration
  4. Implement comprehensive error handling

Phase 3: Advanced Features and Optimization

  1. Add replay protection support
  2. Implement key caching and performance optimizations
  3. Add comprehensive audit logging
  4. Implement advanced configuration options

Phase 4: Security Hardening and Compliance

  1. Security review and penetration testing
  2. RFC 7523 compliance validation
  3. Performance optimization
  4. Documentation and deployment guides

Security Considerations

1. JWT Signature Validation

  • Mandatory signature verification for all JWTs
  • Support for RS256 (mandatory-to-implement per RFC 7523)
  • Configurable algorithm support (RS256, RS384, RS512, ES256, etc.)
  • Proper key management and rotation support

2. Temporal Validation

  • Strict expiration time enforcement with configurable clock skew
  • Optional not-before (nbf) claim validation
  • Reasonable issued-at (iat) claim validation
  • Configurable maximum JWT lifetime limits

3. Audience Validation

  • Mandatory audience claim validation
  • Configurable accepted audience values
  • Support for token endpoint URL as audience
  • Strict string comparison per RFC 3986

4. Replay Protection

  • Optional JWT ID (jti) claim-based replay protection
  • Configurable replay protection window
  • Memory-efficient jti storage and cleanup
  • Integration with existing security policies

5. Issuer Trust Management

  • Configurable trusted issuer validation
  • Integration with existing client management
  • Support for dynamic issuer discovery
  • Proper error handling for untrusted issuers

Performance Considerations

1. JWT Processing Optimization

  • Efficient JWT parsing and validation
  • Signature verification caching where appropriate
  • Minimal memory allocation during processing
  • Fast-fail validation for invalid tokens

2. Key Management

  • JWKS endpoint caching with proper TTL
  • Static key configuration support
  • Efficient key lookup and validation
  • Proper key rotation handling

3. Scalability

  • Stateless JWT validation design
  • Horizontal scaling compatibility
  • Minimal database interactions
  • Efficient concurrent request handling

4. Monitoring and Metrics

  • JWT validation success/failure rates
  • Processing time metrics
  • Error categorization and tracking
  • Performance baseline establishment

Implementation Plan

  • 1. Extend GrantType enum to support JWT Bearer grant type

    • Add JWT_BEARER("urn:ietf:params:oauth:grant-type:jwt-bearer") to the GrantType enum
    • Update any grant type validation logic to include the new type
    • Add unit tests for the new grant type enum value
    • Requirements: 1.1, 1.2

  • 2. Create JWT Bearer validation service infrastructure

    • 2.1 Implement JwtBearerValidationService class

      • Create service class with JWT validation methods according to RFC 7523 requirements
      • Implement signature verification using existing AbstractCryptoProvider
      • Add methods for validating required claims (iss, sub, aud, exp)
      • Requirements: 3.1, 3.2, 3.3

    • 2.2 Create JWT Bearer validation data models

      • Implement JwtBearerValidationContext class for validation parameters
      • Create JwtBearerValidationResult class for validation outcomes
      • Add JwtBearerGrantRequest class for parsing grant requests
      • Requirements: 3.1, 3.4

    • 2.3 Implement comprehensive JWT claim validation

      • Add issuer (iss) claim validation with trusted issuer checking
      • Implement subject (sub) claim validation for both grant and auth flows
      • Create audience (aud) claim validation against configured values
      • Add temporal validation for exp, nbf, and iat claims with clock skew handling
      • Requirements: 3.1, 3.2, 3.3, 3.4, 3.5, 3.6

  • 3. Implement JWT Bearer authorization grant handler

    • 3.1 Create JwtBearerGrantHandler class

      • Implement grant handler that processes JWT Bearer grant requests
      • Add JWT assertion parameter parsing and validation
      • Integrate with existing token issuance infrastructure
      • Requirements: 1.1, 1.2, 1.3

    • 3.2 Integrate JWT Bearer grant with TokenRestWebServiceImpl

      • Modify token endpoint to recognize and route JWT Bearer grant requests
      • Add grant type switching logic for JWT Bearer processing
      • Ensure proper error handling and response formatting
      • Requirements: 1.1, 1.4, 5.1, 5.2

    • 3.3 Implement scope handling for JWT Bearer grants

      • Add scope parameter processing for JWT Bearer requests
      • Integrate with existing scope validation and policy enforcement
      • Ensure scope restrictions are properly applied to issued tokens
      • Requirements: 1.5, 6.1

  • 4. Enhance JWT Bearer client authentication

    • 4.1 Extend ClientAssertion class for JWT Bearer authentication

      • Enhance existing ClientAssertion to support JWT Bearer client authentication
      • Add validation for client_assertion_type parameter matching JWT Bearer
      • Implement client_id and JWT subject claim matching validation
      • Requirements: 2.1, 2.2, 2.3

    • 4.2 Integrate JWT Bearer client auth with authentication filter

      • Modify client authentication filter to handle JWT Bearer assertions
      • Add proper error handling for invalid client authentication
      • Ensure integration with existing client management and policies
      • Requirements: 2.4, 6.2

  • 5. Add configuration support for JWT Bearer features

    • 5.1 Extend AppConfiguration with JWT Bearer properties

      • Add configuration properties for enabling JWT Bearer grant type
      • Add properties for JWT Bearer client authentication enablement
      • Create configuration for accepted audience values and JWT lifetime limits
      • Requirements: 4.1, 4.2, 4.3, 4.4

    • 5.2 Implement JWT Bearer configuration validation

      • Add validation for JWT Bearer configuration properties
      • Implement configuration-driven feature enablement
      • Add proper default values and validation rules
      • Requirements: 4.5

  • 6. Implement comprehensive error handling

    • 6.1 Create JWT Bearer specific error responses

      • Implement RFC 7523 compliant error responses for authorization grants
      • Add specific error codes and descriptions for JWT validation failures
      • Create proper HTTP status codes and error formatting
      • Requirements: 5.1, 5.2, 5.3

    • 6.2 Add client authentication error handling

      • Implement invalid_client error responses for JWT authentication failures
      • Add descriptive error messages for different failure scenarios
      • Ensure proper error logging and audit trail
      • Requirements: 5.4, 5.5

  • 7. Add security features and replay protection

    • 7.1 Implement optional JWT replay protection

      • Add JWT ID (jti) claim-based replay protection mechanism
      • Create configurable replay protection window and storage
      • Implement efficient jti tracking and cleanup
      • Requirements: 3.7, 4.5

    • 7.2 Enhance JWT signature validation security

      • Ensure mandatory signature verification for all JWT Bearer tokens
      • Add support for multiple signature algorithms (RS256, ES256, etc.)
      • Implement proper key validation and algorithm verification
      • Requirements: 3.1, 3.9

  • 8. Create comprehensive unit tests

    • 8.1 Write JWT validation service tests

      • Create tests for valid JWT processing with all required claims
      • Add tests for invalid signature detection and handling
      • Implement tests for expired token rejection and temporal validation
      • Test missing claim validation and audience verification
      • Requirements: 3.1, 3.2, 3.3, 3.4, 3.5, 3.6

    • 8.2 Write JWT Bearer grant handler tests

      • Test valid JWT Bearer grant processing and token issuance
      • Add tests for scope handling and validation
      • Create tests for error response generation and formatting
      • Test integration with existing token service infrastructure
      • Requirements: 1.1, 1.2, 1.3, 1.4, 1.5

    • 8.3 Write JWT Bearer client authentication tests

      • Test valid JWT client authentication flow
      • Add tests for subject/client_id matching validation
      • Create tests for client authentication error scenarios
      • Test integration with existing authentication infrastructure
      • Requirements: 2.1, 2.2, 2.3, 2.4

  • 9. Create integration tests for end-to-end flows

    • 9.1 Write token endpoint integration tests

      • Create end-to-end tests for JWT Bearer authorization grant flow
      • Add tests for JWT Bearer client authentication with various grant types
      • Test combined JWT authentication and authorization scenarios
      • Requirements: 1.1, 1.2, 2.1, 2.2, 6.1, 6.2

    • 9.2 Write configuration-driven behavior tests

      • Test feature enablement/disablement through configuration
      • Add tests for audience validation configuration
      • Create tests for JWT lifetime and replay protection settings
      • Requirements: 4.1, 4.2, 4.3, 4.4, 4.5

  • 10. Add audit logging and monitoring integration

    • 10.1 Implement JWT Bearer audit logging

      • Add audit logs for JWT Bearer grant processing
      • Create logs for JWT Bearer client authentication events
      • Implement proper log levels and structured logging
      • Requirements: 6.3

    • 10.2 Add performance monitoring and metrics

      • Create metrics for JWT validation success/failure rates
      • Add performance metrics for JWT processing times
      • Implement monitoring for error categorization and tracking
      • Requirements: 7.5

  • 11. Update discovery endpoint and metadata

    • 11.1 Add JWT Bearer grant type to discovery response

      • Update /.well-known/openid_configuration to include JWT Bearer grant type
      • Add JWT Bearer grant type to grant_types_supported array
      • Ensure proper discovery metadata for client configuration
      • Requirements: 1.1, 4.1

    • 11.2 Update client authentication methods in discovery

      • Add JWT Bearer client authentication method to supported methods
      • Update token_endpoint_auth_methods_supported in discovery response
      • Ensure clients can discover JWT Bearer authentication support
      • Requirements: 2.1, 4.2

  • 12. Create documentation and examples

    • 12.1 Write JWT Bearer implementation documentation

      • Create configuration guide for JWT Bearer features
      • Add examples of JWT Bearer grant and authentication flows
      • Document security considerations and best practices
      • Requirements: 4.1, 4.2, 4.3, 4.4, 4.5

    • 12.2 Create JWT Bearer testing and validation examples

      • Provide sample JWT Bearer tokens for testing
      • Create example client implementations using JWT Bearer
      • Add troubleshooting guide for common JWT Bearer issues
      • _Requirements: 5.1, 5.2, 5.3,

Clone this wiki locally