README

A comprehensive OAuth 2.1 compliance module ecosystem that provides centralized coordination and assessment of OAuth 2.1 implementation across Drupal's OAuth ecosystem. This ecosystem consists of 6 interconnected modules implementing multiple OAuth RFCs.

Overview

The Simple OAuth 2.1 module ecosystem serves as a comprehensive OAuth 2.1 compliance solution through an umbrella coordination module and 5 specialized sub-modules. It provides a real-time compliance dashboard, implements 6 OAuth RFCs, and offers complete OAuth 2.1 functionality including device flows, dynamic client registration, and enhanced security features.

OAuth 2.1 Compliance

OAuth 2.1 represents the next evolution of the OAuth 2.0 standard, consolidating security best practices and eliminating deprecated flows. This module coordinates compliance with:

Mandatory PKCE: Proof Key for Code Exchange for all authorization code flows
Enhanced Security: Elimination of deprecated implicit grant flow
Native App Security: RFC 8252 compliance for mobile and desktop applications
Server Metadata: RFC 8414 automatic discovery capabilities

OAuth RFC Implementation Matrix

This module ecosystem provides complete compliance with 6 OAuth RFCs:

RFC	Standard	Module	Implementation
RFC 7591	Dynamic Client Registration	`simple_oauth_client_registration`	Full CRUD operations, metadata support
RFC 7636	PKCE	`simple_oauth_pkce`	S256/plain methods, enforcement levels
RFC 8252	OAuth for Native Apps	`simple_oauth_native_apps`	WebView detection, custom schemes, loopback
RFC 8414	Authorization Server Metadata	`simple_oauth_server_metadata`	Full metadata endpoint, capability advertisement
RFC 8628	Device Authorization Grant	`simple_oauth_device_flow`	Device codes, user verification, polling
RFC 9728	Protected Resource Metadata	`simple_oauth_server_metadata`	Resource discovery metadata

Complete API Endpoints

Server Discovery:

/.well-known/oauth-authorization-server - Authorization server metadata (RFC 8414)
/.well-known/oauth-protected-resource - Protected resource metadata (RFC 9728)
/.well-known/openid-configuration - OpenID Connect discovery

Dynamic Client Registration:

/oauth/register (POST) - Client registration
/oauth/register/{client_id} (GET/PUT/DELETE) - Client management

Device Authorization Flow:

/oauth/device_authorization (POST) - Device authorization requests
/oauth/device (GET/POST) - User verification interface

Features

Compliance Dashboard

Access the comprehensive compliance dashboard at: Administration → Configuration → People → Simple OAuth → OAuth 2.1 Dashboard

The dashboard provides:

Overall Compliance Status: Visual assessment with clear compliance indicators
Score Breakdown: Detailed scoring across three categories:
- Core Requirements (Mandatory): Essential OAuth 2.1 compliance features
- Server Metadata (Required): RFC 8414 discovery and metadata
- Best Practices (Recommended): Additional security enhancements
Critical Issues: Identification of mandatory requirements that block compliance
Actionable Recommendations: Direct links to configuration pages for missing features
Real-time Assessment: Dynamic compliance monitoring with cache management

Intelligent Module Detection

The module supports flexible deployment patterns:

Submodule Installation: Integrated submodules within the simple_oauth_21 package
Standalone Modules: Individual contrib modules (simple_oauth_pkce, etc.)
Mixed Environments: Combination of submodules and standalone installations
Graceful Degradation: Partial compliance assessment when modules are missing

Module Architecture

Dependency Hierarchy

The Simple OAuth 2.1 ecosystem follows a clear dependency hierarchy:

simple_oauth_21 (umbrella)
├── simple_oauth (core OAuth)
├── drupal:system (core)
└── Sub-modules:
    ├── simple_oauth_device_flow
    │   ├── simple_oauth_21
    │   ├── simple_oauth
    │   └── consumers
    ├── simple_oauth_pkce
    │   ├── simple_oauth_21
    │   └── simple_oauth
    ├── simple_oauth_native_apps
    │   ├── simple_oauth_21
    │   └── simple_oauth
    ├── simple_oauth_client_registration
    │   ├── simple_oauth_21
    │   ├── simple_oauth
    │   ├── consumers
    │   └── serialization
    └── simple_oauth_server_metadata
        ├── simple_oauth_21
        └── simple_oauth

Cross-Module Integration

Compliance Service Integration: All modules integrate with the main compliance service for real-time assessment
Configuration Coordination: Umbrella module provides centralized configuration navigation
Service Discovery: Server metadata module advertises capabilities from other modules
Enhanced Detection: Intelligent module detection supports both sub-module and standalone installations

Module Ecosystem (6 Modules)

The Simple OAuth 2.1 ecosystem consists of 1 umbrella module and 5 specialized sub-modules:

1. simple_oauth_21 (Main Module)

Purpose: Umbrella coordination module and compliance dashboard

OAuth 2.1 compliance assessment engine with real-time monitoring
Comprehensive compliance dashboard with scoring and recommendations
Centralized configuration navigation for all sub-modules
Intelligent module detection (supports both sub-modules and standalone installations)
Admin Route: /admin/config/people/simple_oauth/oauth-21

2. simple_oauth_device_flow

RFC Implementation: RFC 8628 OAuth 2.0 Device Authorization Grant

Complete device authorization flow for TVs, IoT devices, and CLI applications
Device code generation and user verification interface
Configurable polling intervals and code lifetimes
User-friendly verification workflow with accessibility features
Admin Route: /admin/config/people/simple_oauth/oauth-21/device-flow
Dependencies: simple_oauth_21, simple_oauth, consumers

3. simple_oauth_pkce

RFC Implementation: RFC 7636 PKCE (Proof Key for Code Exchange)

Mandatory OAuth 2.1 PKCE enforcement with configurable levels
S256 and plain challenge method support
Authorization code interception protection
Integration with compliance dashboard for real-time validation
Admin Route: /admin/config/people/simple_oauth/oauth-21/pkce
Dependencies: simple_oauth_21, simple_oauth

4. simple_oauth_native_apps

RFC Implementation: RFC 8252 OAuth for Native Apps

WebView detection and blocking for enhanced security
Custom URI schemes and loopback redirect support
Enhanced PKCE requirements specifically for native applications
Exact redirect URI matching for improved security
Client configuration enhancement for native app settings
Admin Route: /admin/config/people/simple_oauth/oauth-21/native-apps
Dependencies: simple_oauth_21, simple_oauth

5. simple_oauth_server_metadata

RFC Implementations: RFC 8414 (Authorization Server Metadata), RFC 9728 (Protected Resource Metadata)

Automatic server capability discovery and advertisement
Complete metadata endpoints for client auto-configuration
OpenID Connect discovery support
Extended metadata fields and custom capability advertisement
Admin Route: /admin/config/people/simple_oauth/oauth-21/server-metadata
Dependencies: simple_oauth_21, simple_oauth

6. simple_oauth_client_registration

RFC Implementation: RFC 7591 Dynamic Client Registration

Full dynamic client lifecycle management (CRUD operations)
RFC 7591 compliant client metadata support
Automatic client configuration and credential generation
Bulk operations and credential rotation support
Dependencies: simple_oauth_21, simple_oauth, consumers, serialization

Installation

Prerequisites

Drupal: 10.2+ or 11.x
PHP: 8.1+ (recommended 8.3+)
Required Modules: simple_oauth (will be installed automatically)
Optional Modules: consumers (for device flow and client registration), serialization (for client registration API)

Installation via Composer

composer require e0ipso/simple_oauth_21

Enable Modules

Enable the umbrella module and desired sub-modules:

# Enable all modules for complete OAuth 2.1 compliance
drush pm:enable simple_oauth_21 simple_oauth_device_flow simple_oauth_pkce simple_oauth_native_apps simple_oauth_server_metadata simple_oauth_client_registration

# Or enable selectively based on your needs
drush pm:enable simple_oauth_21 simple_oauth_pkce simple_oauth_server_metadata

Post-Installation

# Clear caches to ensure proper module integration
drush cache:rebuild

# Access the compliance dashboard
# Navigate to: /admin/config/people/simple_oauth/oauth-21

Configuration

Basic Setup

Install Dependencies: Ensure simple_oauth and optional dependencies are installed
Access Dashboard: Navigate to /admin/config/people/simple_oauth/oauth-21
Review Compliance: Check overall compliance status and address critical issues
Configure Sub-modules: Use dashboard links to configure individual sub-modules
Verify Integration: Test OAuth endpoints and compliance assessment

Compliance Levels

Fully Compliant: All mandatory and required features enabled

PKCE with S256 challenge method
Implicit grant disabled
Server metadata endpoint active
All critical security features enabled

Mostly Compliant: Core requirements met with minor recommendations

Essential OAuth 2.1 features active
Some recommended features may be missing

Partially Compliant: Basic functionality with compliance gaps

Some mandatory features missing
Security vulnerabilities may exist

Non-Compliant: Critical OAuth 2.1 requirements missing

PKCE not enabled or improperly configured
Deprecated flows still active
Security requirements not met

Permissions

administer simple_oauth entities: Required to access the compliance dashboard and configuration
access simple_oauth_21 compliance dashboard: View-only access to compliance status
Individual sub-modules may have additional permission requirements:
- Device flow: May require permissions for device verification interface
- Client registration: API access permissions for dynamic registration
- Server metadata: Public endpoint access (no special permissions needed)

OAuth 2.1 Implementation Guide

Step-by-step Configuration

Step 1: Core Requirements

Enable simple_oauth_pkce module
Configure PKCE enforcement to "mandatory"
Enable S256 challenge method
Disable plain challenge method (production)
Verify implicit grant is disabled

Step 2: Server Metadata (Recommended)

Enable simple_oauth_server_metadata module
Configure optional endpoints (revocation, introspection)
Add service documentation URLs
Test /.well-known/oauth-authorization-server endpoint

Step 3: Native App Security (If Applicable)

Enable simple_oauth_native_apps module
Configure WebView detection policy
Enable custom URI schemes
Enable loopback redirects
Enable exact redirect URI matching

Step 4: Device Flow (If Applicable)

Enable simple_oauth_device_flow module
Configure device code lifetime and polling intervals
Test device authorization workflow
Configure user verification interface

Step 5: Dynamic Client Registration (Optional)

Enable simple_oauth_client_registration module
Configure registration endpoint permissions
Test /oauth/register endpoint functionality
Configure client metadata requirements

Step 6: Verification

Access compliance dashboard at /admin/config/people/simple_oauth/oauth-21
Verify "Fully Compliant" status with green indicators
Address any remaining recommendations from the dashboard
Test OAuth flows with real clients
Verify all enabled endpoints are responding correctly:
- /.well-known/oauth-authorization-server
- /oauth/device_authorization (if device flow enabled)
- /oauth/register (if client registration enabled)

Security Features

OAuth 2.1 Security Enhancements

This module ecosystem implements comprehensive OAuth 2.1 security features:

Mandatory PKCE (RFC 7636)

S256 Challenge Method: SHA256-based challenge for authorization code protection
Enforced by Default: PKCE is mandatory for all authorization code flows
Authorization Code Interception Protection: Prevents code theft attacks

Native App Security (RFC 8252)

WebView Detection: Blocks embedded browser usage for improved security
Custom URI Schemes: Support for app-specific redirect URIs
Loopback Redirects: Secure local redirects for desktop applications
Enhanced PKCE: Additional PKCE requirements for native applications

Deprecated Flow Prevention

Implicit Grant Disabled: OAuth 2.1 eliminates insecure implicit flow
Legacy Flow Migration: Guidance for transitioning from deprecated flows

Dynamic Security Features

Real-time Compliance Assessment: Continuous security posture monitoring
Configuration Validation: Automatic detection of security misconfigurations
Best Practice Enforcement: Automated enforcement of OAuth 2.1 security requirements

Security Best Practices

Always Enable PKCE: Ensure PKCE is configured to "mandatory" for production
Use S256 Challenge Method: Disable plain text challenge method in production
Configure Native App Settings: Enable WebView detection for mobile/desktop clients
Monitor Compliance Dashboard: Regularly review security recommendations
Keep Dependencies Updated: Maintain current versions of OAuth modules
Implement Proper Scopes: Use minimal necessary scopes for client applications

Documentation

Usage Examples

Testing Device Flow (RFC 8628)

# 1. Start device authorization
curl -X POST https://your-site.com/oauth/device_authorization \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=your_client_id&scope=basic"

# 2. User visits verification_uri and enters user_code
# 3. Poll for access token
curl -X POST https://your-site.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:device_code&device_code=returned_device_code&client_id=your_client_id"

Testing Dynamic Client Registration (RFC 7591)

# Register a new client
curl -X POST https://your-site.com/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My Application",
    "redirect_uris": ["https://myapp.com/callback"],
    "grant_types": ["authorization_code"],
    "response_types": ["code"]
  }'

# Retrieve client information
curl -X GET https://your-site.com/oauth/register/client_id_here \
  -H "Authorization: Bearer registration_access_token"

Testing Server Discovery (RFC 8414)

# Authorization server metadata
curl https://your-site.com/.well-known/oauth-authorization-server

# Protected resource metadata
curl https://your-site.com/.well-known/oauth-protected-resource

# OpenID Connect discovery
curl https://your-site.com/.well-known/openid-configuration

Additional Resources

API Documentation: Comprehensive API reference for all OAuth RFC compliance endpoints
Migration Guide: Step-by-step guide for upgrading existing installations
Module Help: In-context help for client registration features
Discovery Report: Complete technical analysis of module ecosystem functionality

Troubleshooting

Common Issues

Q: Dashboard shows "Non-Compliant" despite enabling sub-modules A:

Clear all caches: drush cache:rebuild
Verify module dependencies are met (check consumers and serialization modules)
Check module status: drush pm:list --status=enabled | grep oauth
Review module interdependencies in admin interface

Q: Device flow endpoints not working A:

Ensure consumers module is enabled: drush pm:enable consumers
Verify device flow configuration at /admin/config/people/simple_oauth/oauth-21/device-flow
Check that device authorization endpoint is accessible: curl -X POST /oauth/device_authorization

Q: Client registration API returning errors A:

Enable serialization module: drush pm:enable serialization
Verify client registration permissions
Test endpoint: curl -X POST /oauth/register -H "Content-Type: application/json"

Q: Server metadata endpoints not found A:

Clear routing cache: drush cache:rebuild
Verify server metadata module is enabled
Test discovery endpoints:
- curl /.well-known/oauth-authorization-server
- curl /.well-known/oauth-protected-resource

Q: PKCE validation failures A:

Check PKCE configuration at /admin/config/people/simple_oauth/oauth-21/pkce
Verify S256 challenge method is enabled
Ensure clients are sending proper PKCE parameters
Check native apps configuration if using mobile/desktop clients

Q: Performance issues with compliance checking A:

Verify that caching is enabled in Drupal configuration
Consider increasing cache lifetime for stable configurations
Monitor compliance service performance in webprofiler (if enabled)

Q: Module compatibility issues after updates A:

Update all OAuth-related modules: composer update 'e0ipso/*' 'drupal/simple_oauth'
Run database updates: drush updatedb
Clear all caches: drush cache:rebuild
Review module interdependency status in compliance dashboard

Debug Mode

Enable detailed logging by setting the log level to DEBUG for the 'simple_oauth_21' channel:

\Drupal::logger('simple_oauth_21')->debug('Debug message');

e0ipso / simple_oauth_21

Maintainers

Details