OIDC: Add configurable username mapping via oidc.username_claim_order

[angelbarrera92]

Add support for deriving Headscale usernames from configurable OIDC claims, addressing IdPs (like Google) that omit the standard preferred_username claim.

• have read the CONTRIBUTING.md file
• raised a GitHub issue or discussed it on the projects chat beforehand
• added unit tests
• added integration tests
• updated documentation if needed
• updated CHANGELOG.md

Fixes #3002

Summary

This PR adds a configurable way to derive the Headscale username from OIDC claims. It addresses IdPs (like Google) that do not emit preferred_username, enabling predictable, valid usernames without manual remediation.

Changes

• Config: Introduce oidc.username_claim_order (array) that defines a priority list of claims to try.
  • Supported values: preferred_username, email_localpart, email, name, sub.
  • Default (when unset): [preferred_username, email_localpart, email, name, sub].
• Username derivation helper: picks the first non-empty, syntactically valid candidate using existing ValidateUsername rules.
• OIDC flow: applies the mapping before creating/updating the user record so Username() resolves reliably.
• Documentation: added configuration reference and OIDC guide notes (including Google example).
• Tests: unit tests covering the derivation and common fallback cases.

Example Configuration

oidc:
  issuer: "https://accounts.google.com"
  client_id: "..."
  client_secret: "..."
  # Prefer preferred_username, otherwise use email local-part, then email
  username_claim_order:
    - preferred_username
    - email_localpart
    - email

Notes

• Candidates are tried in order and must pass ValidateUsername.
• If the list is omitted, the default order is used.
• Default behavior preserves existing installs where preferred_username is present.
• No database migrations required.
• Username syntax is validated; all email verification and authorization constraints remain unchanged.