Feature: System-Level OIDC Authentication & Dynamic Provider Support ( #874 )

[Sipioteo]

Summary

This PR introduces a robust, dynamic OpenID Connect (OIDC) authentication layer at the system environment level. It allows instance administrators to configure one or multiple OIDC providers (e.g., Google, Microsoft, Zitadel) purely via environment variables without needing to alter core code.

This implementation follows a "No Auto-Provisioning" rule: it maps external identities to existing local accounts. This enhances security for closed environments while streamlining access for registered users.

Provider Compatibility & Testing

The implementation is designed to be strictly compliant with the OIDC standard.

• Tested: I have thoroughly tested this in a private environment using a Zitadel instance, and it works seamlessly.
• Compatibility: It natively supports any standard-compliant provider, including Google and Microsoft.
• Known Exception (Apple): Please note that Apple uses P12 keys for OIDC, which deviates from the standard used by other providers. For Apple Sign-In, I recommend using an external IdP (like Zitadel) as a bridge: integrate Apple there and then connect this application to the IdP via standard OIDC.

---

Detailed Changes

1. Dynamic Environment Configuration

Administrators can now define active providers and their configurations dynamically in the .env file.

• Provider Registration: The backend dynamically parses the AUTH_PROVIDERS list and registers the corresponding Socialite drivers on boot.
• Automatic Callbacks: The redirect_uri is automatically generated based on the application's base URL, reducing configuration errors. https://events.example.com/api/auth/{providerName}/callback

Example Configuration (.env):

AUTH_PROVIDERS="zitadel,google"
AUTH_DISABLE_DEFAULT="true"

# Custom OIDC Provider (e.g., Zitadel)
AUTH_zitadel_DRIVER="openid"
AUTH_zitadel_CLIENT_ID="123456789"
AUTH_zitadel_CLIENT_SECRET="secret"
AUTH_zitadel_ISSUER_URL="https://auth.example.com"
AUTH_zitadel_IDENTIFIER_KEY="email"
AUTH_zitadel_SCOPE="openid email profile"
AUTH_zitadel_LOGO_URL="https://example.com/logo.svg"


# Google OIDC Provider ( Don't need the logo url, i have implemented a "major company logo identification" function )
AUTH_google_DRIVER="openid"
AUTH_google_CLIENT_ID="123456789"
AUTH_google_CLIENT_SECRET="secret"
AUTH_google_ISSUER_URL="https://accounts.google.com"
AUTH_google_IDENTIFIER_KEY="email"
AUTH_google_SCOPE="openid email profile"

2. Strict Authentication Flow & Mapping

The callback logic securely handles the OIDC payload:

• Identity Mapping: The system uses a configurable AUTH_{provider}_IDENTIFIER_KEY to extract the ID. The database lookup is hardcoded to match this value against the local email column.
• No Auto-Signup: If the email matches an existing user, they are logged in. If the user does not exist, the authentication is rejected.
• Trusting the Provider: If a matching local account is unverified, it is automatically marked as verified, trusting the OIDC provider as the source of truth.

3. UI Toggles & Smart Icons

The Login interface adapts to the active state:

• Form Toggling: If AUTH_DISABLE_DEFAULT="true" is set, standard login/signup forms are hidden, showing only OIDC buttons.
• Smart Icons: The UI detects common providers (Google, Microsoft) and applies brand icons. Custom providers can use AUTH_{provider}_LOGO_URL or fall back to a generic icon.
• Admin Backdoor: Adding ?show_login=1 to the URL overrides the disable rule, allowing admin recovery if needed.

---

Checklist

• I have read the contributing guidelines.
• My code is of good quality and follows the coding standards of the project.
• I have tested my changes, and they work as expected.

Resolutions

This PR resolves #874

Tutorial

I have added a more comprehensive tutorial into this file OIDC_ENV_TUTORIAL.md

[Sipioteo]

env AUTH_DISABLE_DEFAULT="false"

---

env AUTH_DISABLE_DEFAULT="true"

---

Google implementation without url icon

---

?show_login=1

[Sipioteo]

Sorry for the aggressive reformatting, my linter is a bit aggressive 😅😅

[Sipioteo]

Hi @daveearley ! 👋 Just a quick update regarding my recent submissions.

To give you some context, I had to go ahead and implement these specific features because my non-profit organization needs them for our internal management.

I have already successfully merged the last three PRs I published on my end, and everything is fully functional together. You can review the working code with all those changes combined right here:
https://github.com/Sipioteo/Hi.Events/tree/main/mensa

If it makes things easier for you, I’d be happy to open a single, global PR that includes all three updates so you can merge everything in one go.

Just let me know what works best for your workflow!

[linjoe2]

wow! amazing! would be great to have this built in, my orga will also be very happy with sso!

[daveearley]

Great work, thank you! I'll test this soon.