OpenID Connect Username Sanitizer

Sanitises OpenID Connect SSO username-candidate claims (preferred_username and name) before they're used to generate a Drupal username, so a character an identity provider sends that Drupal's own username validation rejects can't silently block account creation.

Features

The OpenID Connect module builds a new user's Drupal username from the SSO preferred_username or name claim, in preference to their email address. Neither OpenID Connect nor its Windows AAD sub-module checks that value against Drupal's own username rules first. When the claim contains a character outside Drupal's allowed username set - or is simply too long - account creation fails outright, and the resulting error log doesn't record what the actual claim value was:

Failed to create user account for [email protected]: The username contains an illegal character.

A real-world example: an identity provider that prefixes organisation-type accounts' display names, e.g. "[Acme Ltd] Jane Doe", will produce this error for every such account - the square brackets are outside Drupal's allowed username character set.

This is a known, previously-reported problem:

• OpenID connect doesn't validate usernames (#3294141) - the same symptom: an identity-provider-supplied name containing an illegal character breaks account creation. A patch was submitted stripping invalid characters using the same validation logic this module uses. Closed as a duplicate of #3252021.
• OpenId Connect don't check username when exceeded (#3252021) - the issue #3294141 was merged into, covering both the illegal-character case and the case where the claim exceeds Drupal's 60-character username limit. Since OpenID Connect 3.0.0-alpha7, account creation validates the username/email and throws an exception with a logged error if either is invalid, rather than attempting to create an invalid account - which is the error shown above.
• No way to alter userinfo before getting 'name' property (#3021049) - covers the same class of problem specifically for the Windows AAD sub-module's displayName/name claim handling, and confirms hook_openid_connect_userinfo_alter() (the hook this module uses) as the intended place for a site to intercept and fix a claim like this before it's used.

This module addresses both linked problems - illegal characters and excessive length - in one place, using that hook:

• Strips any character Drupal's username validation would reject from both the preferred_username and name claims, whichever one OpenID Connect ends up using.
• Truncates the result with headroom for OpenID Connect's own duplicate-username suffix (so a collision doesn't push the username back over the limit).
• If nothing usable survives sanitisation, removes the claim entirely rather than leaving an empty value, so OpenID Connect falls through to its own safe fallback.
• Logs a debug-level message whenever it changes a claim, recording the before and after values, rate-limited via Drupal's core flood control so a persistently misconfigured identity provider can't flood your logs.

Post-Installation

Installing the module enables sanitisation immediately, with no further setup required.

A settings page is available at Administration » Configuration » System » OpenID Connect Username Sanitizer, with a single checkbox to enable or disable the module's behaviour. Requires the administer site configuration permission. Disable it to fall back to OpenID Connect's original, unmodified behaviour - for example, if you'd rather usernames simply fail to be created than be silently altered, and prefer to fix the identity provider's claim format at the source instead.

If you enable debug logging in your site's logging configuration, watch the openid_connect_username_sanitizer log channel to see exactly what was changed on any given login. Because this log records the raw claim value before and after sanitisation, restrict access to your site's logs (the access site reports permission) as you would for any other log that may contain personal data from your identity provider.

Additional Requirements

None declared. This module deliberately has no dependency on OpenID Connect: its hook implementation is simply never called on a site that doesn't have OpenID Connect enabled, so it's safe to install alongside any other module set. It does nothing at all unless OpenID Connect is also installed and an SSO login returns a preferred_username or name claim.

Similar projects

No dedicated contrib module solving this specific problem was found. The closest prior art is the patches submitted directly against OpenID Connect's own issue queue (linked under Features above), which proposed similar character-stripping logic but were not merged into the module itself - the merged fix instead validates and rejects an invalid username with a logged error, which is the behaviour this module works alongside, rather than replaces.