openid_client_advanced

AI Development Declaration

This module was written by AI agents. The module maintainer reviews and takes full responsibility for all the work done by AI.

About the module

The OpenID Client Advanced module provides an OAuth 2.0/OIDC client plugin working with the OpenID Connect module which accepts file or environment variable as the secret source, supports PKCE (S256), ID token signature validation, and nonce-based replay protection.

Requirements

• Drupal core 10 or 11
• PHP 8.3 or higher
• drupal/openid_connect ^3.0
• firebase/php-jwt ^7.01 (installed automatically when using Composer)

Installation

1. Add the module to your project (composer require drupal/openid_client_advanced) or place it in modules/contrib.
2. Enable the module (drush en openid_client_advanced or via Extend).
3. Clear caches if prompted.

Configuring a client

1. Navigate to Configuration → People → OpenID Connect (/admin/config/people/openid-connect).
2. Add or edit a client and choose OAuth 2.0 Advanced.
3. Enter the Client ID and select the Client Secret Source:
   • Plain Text: Enter the secret directly.
   • Environment Variable: Enter the variable name containing the secret.
   • File in Secrets Directory: Enter the filename (basename only) in the configured secrets directory.
4. Decide how endpoints are set:
   • Check Auto discover endpoints and provide an Issuer URL to pull endpoints from /.well-known/openid-configuration, or
   • Leave it unchecked and manually enter Authorization, Token, UserInfo, and End Session endpoints.
5. Set Scopes (space-separated, e.g. openid email).
6. Optionally enable Use PKCE (Proof Key for Code Exchange) to send code_challenge (S256) on authorization and code_verifier on token exchange. If PKCE is enabled and the verifier is unavailable in session at callback time, authentication is rejected and logged with a trace ID.
7. Save the client.

Security features

• Use PKCE (S256): Enable PKCE to send code_challenge and code_challenge_method=S256 during authorization, then code_verifier during token exchange. If no verifier is available at token exchange time, login fails and a trace ID is logged and shown to the user.
• Validate ID token signature: Enable verification and provide RSA/ECDSA public keys as PEM (blank-line separated) or a JWKS JSON document. Optionally restrict Allowed signature algorithms (e.g. RS256 RS512). Failures log to openid_connect_advanced.
• Send nonce parameter: Include a nonce in authorization requests; the nonce is stored in the session and must match the nonce claim in the ID token or the login is rejected and logged.
• Error tracing ID: When authentication failures occur (e.g. signature validation failure, nonce mismatch, missing PKCE verifier), a unique trace ID is generated and displayed to users for support correlation.

Testing

• Execute unit tests from the Drupal root: phpunit --testsuite openid_client_advanced (or the equivalent command for your test runner).
• Tests cover PKCE and nonce handling, signature validation, and JWKS parsing behaviour.