OIDC Login for Flarum

An enterprise-grade OpenID Connect (OIDC) authentication extension for Flarum.

This extension allows users to log in or register using any standard OIDC provider (Google, Keycloak, Auth0, Azure AD, GitLab, etc.). It features robust auto-discovery, custom attribute mapping, and fully customizable login buttons.

Features

• Universal OIDC Support: Works with any provider compliant with the OpenID Connect 1.0 standard.
• Auto-Discovery: Automatically fetches endpoints and keys (JWKS) from the provider's discovery URL (/.well-known/openid-configuration), with local caching for performance.
• High Security:
  • Supports RS256, HS256, ES256 signing algorithms.
  • New: Support for high-security RS512 and HS512 algorithms.
  • Validates ID Tokens strictly: signature, issuer, audience/azp, expiry and nonce.
  • Authorization Code flow with state, nonce and PKCE (S256).
  • UserInfo is only used to fill gaps and must describe the same sub as the ID Token.
  • Only emails the provider marks email_verified are trusted (see below).
• Customizable UI:
  • Edit button text, background colors, and text colors directly from the Admin panel.
  • Use FontAwesome icons (e.g., fab fa-google) or custom image URLs for button icons.
• Attribute Mapping: Map custom provider claims (e.g., given_name, upn, oid) to Flarum's username, email, and avatar fields.
• Stable user IDs: Accounts are linked by the ID Token's sub claim.

Compatibility

Composer picks the right version for your Flarum install automatically.

Installation

Install the extension via Composer:

composer require floxum/flarum-ext-oidc

Configuration

1. Enable: Go to your Flarum Admin Panel -> Extensions and enable "OIDC Login".
2. Settings: Click the settings icon (three dots) on the extension.
3. Add Provider:
   • Unique ID: A unique lowercase key (e.g., google, keycloak).
   • Discovery URL: The base URL of your Identity Provider (e.g., https://accounts.google.com). Do not include /.well-known/....
   • Client ID & Secret: Obtain these from your provider.
4. Styling:
   • Use the color pickers to match your brand.
   • Paste a FontAwesome class or an image URL for the icon.
5. Mapping (Optional):
   • If your provider uses non-standard keys (e.g., Azure AD uses upn instead of email), enter them in the Attribute Mapping section.

The callback URL shown for each provider (https://your-forum/auth/oidc?provider={id}) must be registered with the identity provider. It is always built from Flarum's configured url, not from the request's Host header.

Email trust

Flarum logs a trusted email straight into any existing account with the same address. To prevent account takeover through an identity provider that allows unverified addresses, the email is only trusted when the ID Token (or UserInfo) contains email_verified: true. Otherwise it is only suggested on the sign-up form and Flarum asks the user to confirm it.

Some providers (e.g. Azure AD / Entra ID) never send email_verified. For those, tick Trust email when the provider sends no email_verified claim if you are sure the provider only issues verified addresses.

Provider Examples

Troubleshooting

"White Screen" after Login

This typically occurs if Flarum cannot determine the User ID or if the popup window cannot communicate with the parent window.

• Solution: Check storage/logs/flarum.log for "OIDC Login Failed". The log will show the raw claims received from the provider, allowing you to see which field contains the ID (e.g., oid vs sub).

"Required options not defined: publicKey"

This extension automatically fetches the Public Key from your provider's JWKS endpoint.

• Solution: Ensure your server allows outbound connections to the provider's jwks_uri. The extension caches these keys to prevent repeated requests.

SSL/Network Errors

If you are testing locally or using self-signed certificates, the extension may fail to connect.

• Solution: Ensure your server allows outbound HTTPS requests. In src/AuthController.php, the Guzzle client is configured to be robust, but ensure your server's CA certificates are up to date.

Development & testing

docker-compose.yml starts Keycloak plus a Flarum 1 and a Flarum 2 forum with this extension linked in:

git worktree add .worktrees/v1 v1   # Flarum 1 needs the v1 branch build
docker compose up -d --build

The Keycloak client is flarum / flarum-client-secret, issuer http://localhost:18080/realms/flarum.

Playwright tests cover configuring a provider in the admin UI, sign-up, returning login and the security checks:

cd tests/e2e
npm install
npx playwright install chromium
npm test            # or: npm run test:v1 / npm run test:v2

License

MIT

Credits

This extension is developed and maintained by Floxum and Mamluk.