Oidc

Oidc adds lightweight OAuth 2.0 and OpenID Connect login to ProcessWire: social sign-in, company SSO, callback handling, auto-registration, silent mode and hookable identity flow.

It is made for sites that need external authentication without a full account-management suite: client portals, intranets, member areas, editorial tools, SaaS dashboards and private ProcessWire projects.

Repository: github.com/mxmsmnv/Oidc Author: Maxim Semenov Website: smnv.org Email: maxim@smnv.org

If this project helps your work, consider supporting future development: GitHub Sponsors or smnv.org/sponsor.

What Oidc Does

• Adds OAuth 2.0 / OpenID Connect login buttons to ProcessWire templates.
• Supports Google, GitHub, LinkedIn, Microsoft, Yandex and Yahoo out of the box.
• Supports custom OIDC providers through discovery URLs.
• Works with Okta, Auth0, Keycloak, authentik, Azure AD, Dex and similar providers.
• Handles OAuth callbacks automatically on frontend pages.
• Requires and verifies OIDC id_token claims with nonce, issuer, audience, expiry, subject and strict RS256/JWKS checks.
• Supplements validated ID-token claims from UserInfo when required profile fields are absent.
• Links local users by stable provider identity (issuer + subject) instead of email-only matching.
• Auto-registers new ProcessWire users or lets hooks take over registration.
• Blocks superuser OIDC login by default and supports role allow-lists.
• Preserves return URLs through the login flow.
• Includes silent mode for SSO-only sites and intranets.
• Provides hook points for identity resolution, login, registration and provider definitions.

Provider Setup

Oidc includes a provider table in the module settings. Fill the Client ID and Client Secret for any built-in provider to enable it.

For deployments where secrets must remain outside the ProcessWire database, provide credentials from a private, untracked configuration file and require runtime credentials:

$config->oidcRequireRuntimeCredentials = true;
$config->oidcProviders = [
    'company' => [
        'client_id' => getenv('OIDC_CLIENT_ID'),
        'client_secret' => getenv('OIDC_CLIENT_SECRET'),
        'discovery_url' => 'https://id.example.com',
        'label' => 'Company ID',
    ],
];
$config->oidcAllowedIssuers = ['https://id.example.com'];

Never commit the runtime file or secret. Discovery issuers must be explicitly allow-listed. Discovered authorization, token, UserInfo and JWKS endpoints must share the issuer origin unless their origins are explicitly listed in $config->oidcAllowedEndpointOrigins.

For standard OpenID Connect providers, configure one custom provider with:

• provider ID;
• display name;
• client ID;
• client secret;
• discovery URL.

The module reads the provider's /.well-known/openid-configuration document and uses the discovered authorization, token, UserInfo and JWKS endpoints.

Public Integration

Oidc is an autoload module. Any frontend page where ?oidc=<provider> appears in the URL is handled automatically before template output.

Render login buttons anywhere in a template:

$oidc = $modules->get('Oidc');
echo $oidc->renderButtons();

The page that renders the buttons is also the callback page. Register the exact generated redirect URI, including ?oidc=<provider-id>, in each provider's OAuth application settings.

Installation

1. Copy the Oidc folder into /site/modules/.
2. In ProcessWire Admin, refresh modules.
3. Install Oidc.
4. Open the module settings and configure the callback URL.
5. Add one or more providers and render the login buttons in your template.

Documentation

See DOCUMENTATION.md for setup, configuration, provider notes, hooks and template integration examples.

See CHANGELOG.md for the release notes.

Run the dependency-free security test suite with php tests/run.php.

Author

Maxim Semenov smnv.org maxim@smnv.org

License

MIT