[6.x] OAuth / Socialite

[riasvdv]

OAuth providers are defined in GeneralConfig::oauthProviders(), keyed by a handle like google or github. Each provider needs a driver, which can be a registered Socialite driver name or a Socialite-compatible provider class. Craft uses its own redirect and callback routes, but the callback URL you register with the provider should be Craft’s stable site callback, such as http://example.com/oauth/google/callback.

By default, Craft resolves the external identity from SocialiteUser::getId(), tries to match an existing Craft user via an existing sso_identities link or the provider email, and can create a new user if createsUsers allows it. New users can be assigned groups, optionally activated immediately, and the resulting login goes through normal Craft access checks while skipping the 2FA prompt. If you need custom behavior, you can swap in resolver/populator/renderer classes for identity matching, user matching, user population, group assignment, and button rendering.

Configured OAuth buttons appear automatically on the login page.

<?php

use App\Auth\OAuth\BrandButtonRenderer;
use App\Auth\OAuth\CustomGroupResolver;
use App\Auth\OAuth\CustomIdentityResolver;
use App\Auth\OAuth\CustomUserPopulator;
use App\Auth\OAuth\CustomUserResolver;
use CraftCms\Cms\Config\GeneralConfig;

return GeneralConfig::create()
    ->oauthProviders([
        'google' => [
            'driver' => 'google',
            'name' => 'Google',
            'label' => 'Continue with Google',
            'clientId' => env('GOOGLE_CLIENT_ID'),
            'clientSecret' => env('GOOGLE_CLIENT_SECRET'),
            'scopes' => ['openid', 'profile', 'email'],
            'groups' => ['members', 'editors'],
            'createsUsers' => true,
            'activatesUsers' => true,
            'identityResolver' => CustomIdentityResolver::class,
            'userResolver' => CustomUserResolver::class,
            'userPopulator' => CustomUserPopulator::class,
            'groupResolver' => CustomGroupResolver::class,
            'buttonRenderer' => BrandButtonRenderer::class,
        ],

        // Shorthand form when only the Socialite driver is needed.
        'github',
    ]);

[Copilot]

Pull request overview

Introduces a first-party OAuth login flow (via Laravel Socialite) integrated with Craft’s existing authentication rules, user creation/linking, and login UI (CP + site), gated to Pro+ editions.

Changes:

• Add OAuth manager/service + controller + routes to support redirect/callback flows and identity linking.
• Extend configuration (GeneralConfig::oauthProviders) and template rendering to show OAuth login buttons.
• Add supporting utilities (group resolution), edition capability flag, and comprehensive tests.

Reviewed changes

Copilot reviewed 45 out of 47 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
composer.json	Adds laravel/socialite dependency.
composer.lock	Locks Socialite and transitive packages.
testbench.yaml	Registers Socialite provider for testbench.
yii2-adapter/testbench.yaml	Registers Socialite provider for adapter testbench.
yii2-adapter/composer.lock	Locks adapter dependencies including Socialite.
src/Auth/OAuth/OAuth.php	Core OAuth manager: provider normalization, button rendering, identity linking, Socialite driver building.
src/Auth/OAuth/Actions/*	Default strategy implementations (identity/user/group/button).
src/Auth/OAuth/Contracts/*	Strategy extension points for customization.
src/Auth/OAuth/Data/*	DTOs for providers and button rendering.
src/Auth/OAuth/Events/ResolvingOAuthUserLink.php	Event hook for custom user linking.
src/Auth/OAuth/Exceptions/ProviderConfigurationException.php	Exception type for invalid provider configs.
src/Http/Controllers/Auth/OAuthController.php	Redirect + callback endpoints and login finalization behavior.
routes/web.php	Adds OAuth redirect/callback routes gated by Pro edition.
src/Config/GeneralConfig.php	Adds oauthProviders config + docs + setter.
src/User/UserGroups.php	Adds resolveGroup() to normalize group references (id/uid/handle).
src/User/Elements/User.php	Switches SSO identity check to OAuth service + Pro gating.
src/Edition.php	Adds supportsOAuth() capability flag.
yii2-adapter/legacy/web/twig/variables/CraftVariable.php	Exposes craft.oauth to Twig.
src/Http/Controllers/Auth/AuthenticationController.php	Extracts shared finalizeLogin() and tweaks CP view lookup.
src/Http/Controllers/Auth/LoginController.php	Uses finalizeLogin() to centralize 2FA branching.
resources/templates/login.twig	Passes initial login error into shared login partial.
resources/templates/_special/login.twig	Renders initial error + swaps old SSO provider rendering for OAuth buttons.
docs/oauth.md	New end-user/dev documentation for OAuth feature.
tests/Unit/EditionTest.php	Tests OAuth support by edition.
tests/TestClasses/OAuth/*	Test doubles for providers and customization strategies.
tests/Feature/Auth/OAuth/*	Feature tests for OAuth manager + default strategies.
tests/Feature/Http/Controllers/Auth/OAuthControllerTest.php	Feature tests for redirect/callback flows, account creation/linking/groups, customization.
tests/Feature/Http/Controllers/Auth/LoginControllerTest.php	Ensures flashed CP login errors render.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.