README

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 and UserInfo responses strictly.
• 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.
• Smart ID Detection: Robustly handles different user ID formats (sub, id, oid, user_id) to prevent login failures with providers like Azure AD.

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.

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.

License

MIT

Credits

This extension is developed and maintained by Floxum and Mamluk.