openid_client_advanced

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.