overtrue/socialite for PHP OAuth2 Authentication

PHP applications that need social login without Laravel

overtrue/socialite addresses a narrow but common requirement: connecting a PHP application to OAuth2 identity providers without requiring the Laravel framework. Its stated inspiration is laravel/socialite, while the package is intended for use in any PHP project. The README lists support for Apple, Facebook, GitHub, Google, LinkedIn, Outlook, QQ, TAPD, Alipay, Taobao, Baidu, DingTalk, Weibo, WeChat, Douyin, Feishu, Lark, Douban, Enterprise WeChat, Tencent Cloud, Line, Gitee, Coding, and Twitter.

The package does not create provider applications, decide whether a user is authorized, or replace an account system. The documented flow starts with configuring a platform, creating an application in that platform, redirecting the user to the provider, receiving a callback code, and exchanging that code for an access token and user information. That separation makes the package useful for an application that already owns its users, sessions, and authorization rules. It is less suitable when the requirement is password authentication, local account registration, or a complete user profile service.

The README gives Laravel users a separate integration, overtrue/laravel-socialite. That distinction matters because the core package works through PHP objects such as SocialiteManager rather than requiring Laravel's application container, routing, configuration, or response layer.

SocialiteManager configuration and provider selection

The main entry point is SocialiteManager. It receives an array of provider configurations, and create() selects an application by its configuration key. Most providers use the same three settings: client_id, client_secret, and redirect_uri. The README also states that redirect and redirect_url remain compatible legacy key names.

A configuration key can be an alias rather than the provider name. In that case, the provider key tells SocialiteManager which built-in implementation to use, while the outer key identifies that particular application. The documented example registers two GitHub applications as foo and bar, each with provider set to github. This permits multiple configurations for the same service, such as separate application credentials or distinct environments, without requiring separate manager instances.

Provider selection also supports custom providers. A closure can be registered with extend(), receiving the provider configuration and returning a custom object. Alternatively, the provider value can be a class name. The README requires a custom class to implement Overtrue\Socialite\Contracts\ProviderInterface. This extension point is useful when a supported authentication service is not built in, but it also means the adapter owns the OAuth2 protocol details and error handling for that provider.

The package therefore separates configuration identity from provider implementation, but it does not hide provider differences. The selected provider still determines which credentials, scopes, token endpoints, user fields, and platform rules apply.

Redirect, callback code, and access token flow

The documented authorization sequence has two application-facing operations. First, the application creates a provider and calls redirect(), which returns the URL to which the user should be sent. The provider controls the platform-specific authorization request. After the platform redirects back to the configured URI, the application reads the code query parameter and passes it to userFromCode().

The callback example reads the code with request()->query('code'), then calls userFromCode($code). The returned object exposes user accessors including getId(), getNickname(), getUsername(), getName(), and getEmail(). These calls return platform data as interpreted by the provider. The README does not claim that every provider supplies every field, so an application should treat optional profile attributes as provider-dependent.

The code exchange is server-side. The callback endpoint needs the client secret configured on the server, and the resulting user object can then be used to associate the external identity with an application account. Socialite does not document session creation, CSRF handling, account linking, token persistence, or revocation in the README. Those responsibilities remain with the host application.

A provider may also expose a token-based path. The Douyin notes specifically say that direct access-token user retrieval requires openid, and that withOpenId() must be called before userFromToken(). This illustrates why the generic flow should not be treated as identical for every provider.

Installing Socialite and completing a GitHub callback

The README requires PHP 8.0.2 or later and documents Composer as the installation method. Install the package with the following command. The command should complete through Composer and place overtrue/socialite in the project's dependencies.

composer require "overtrue/socialite" -vvv

For a first GitHub flow, configure the client ID, client secret, and callback URI. These values come from the GitHub application, and the callback URI must match the registered redirect target. The example uses a localhost callback for a local setup.

<?php

use Overtrue\Socialite\SocialiteManager;

$config = [
    'github' => [
        'client_id'     => 'your-app-id',
        'client_secret' => 'your-app-secret',
        'redirect_uri' => 'http://localhost/socialite/callback.php',
    ],
];

$socialite = new SocialiteManager($config);
$url = $socialite->create('github')->redirect();

return redirect($url);

The callback receives the authorization code and exchanges it for the provider user object. The application can then read the documented fields and decide how to create or link its local account.

<?php

use Overtrue\Socialite\SocialiteManager;

$config = [
    'github' => [
        'client_id' => 'your-app-id',
        'client_secret' => 'your-app-secret',
        'redirect_uri' => 'http://localhost/socialite/callback.php',
    ],
];

$socialite = new SocialiteManager($config);
$code = request()->query('code');
$user = $socialite->create('github')->userFromCode($code);

After a successful exchange, the documented user object supports calls such as getId(), getNickname(), getUsername(), getName(), and getEmail(). The README does not specify the behavior for missing codes, denied authorization, expired codes, or unavailable provider endpoints.

Provider-specific configuration constraints

Provider support does not mean every provider follows the same configuration or authentication rules. Alipay accepts client_id, although the README notes that app_id is also used by the platform documentation. It requires an rsa_private_key for RSA2 personal private-key authentication, and the README states that this is currently the only supported authentication method. The Alipay configuration also exposes sandbox, which controls whether the sandbox address is used.

The Alipay example warns against including extra characters in the private key and recommends reading the key from a file rather than placing it directly in configuration. That is a direct configuration constraint. It does not specify a key-loading API or an environment variable, so the host application must decide how to load the file securely.

DingTalk has a narrower documented use case. The README says the package supports QR code connection to a third-party website to obtain user information such as opeid, unionid, and nickname. That is not the same as a general DingTalk account-linking interface.

Douyin requires extra sequencing when retrieving a user from an access token. Call withOpenId() before userFromToken(). These examples show why adoption decisions should be made provider by provider. A provider appearing in the supported list is not evidence that all OAuth flows or all identity fields are equivalent.

Operational limits, maintenance, and upgrade work

The repository is not archived, and the last push was on 2026-10-04. Recent listed releases are 4.15.0 on 2026-08-28, 4.14.2 on 2026-05-29, and 4.14.1 on 2026-05-28. The package therefore has recent repository activity, but that status does not guarantee compatibility with every provider or callback behavior.

The main operational cost is configuration maintenance. OAuth providers can change application setup, scopes, endpoints, callback expectations, and required profile fields. Socialite's provider-specific adapters may therefore need attention after a platform change. The repository includes src/, tests/, composer.json, phpstan.neon.dist, and phpunit.xml, so the package includes source, configuration, static-analysis settings, and test configuration. The README does not describe a compatibility matrix, supported provider versions, deployment model, or rollback procedure.

The package is licensed under MIT. That identifier tells you the repository declares an MIT license, but the integration team should read the LICENSE file itself for the applicable notice and distribution conditions. The README does not provide legal guidance, and it does not state which third-party credentials or provider terms affect an application.

A separate limitation is operational scope. Socialite handles OAuth2 integration, but the example application does not show secure secret management, session management, local account linking, token refresh, provider logout, or protection against replayed callback codes. Those controls belong in the surrounding application unless separate code or documentation is supplied.

Socialite compared with Laravel Socialite and direct OAuth clients

The closest documented alternative is overtrue/laravel-socialite, which the README describes as a more convenient integration package for Laravel users. Socialite is the framework-independent PHP package, while the Laravel package is intended to sit inside Laravel's conventions. A Laravel application that already depends on Laravel may gain less from directly integrating the core package and more from the documented Laravel integration.

The other practical approach is to implement the provider's OAuth2 exchange directly with an HTTP client and application-specific user mapping. That avoids a provider manager abstraction, but it leaves the application responsible for authorization URLs, token requests, response handling, profile normalization, and provider-specific exceptions. Socialite supplies a common PHP interface around those tasks, which is useful when an application supports several named providers.

The trade-off is control. A direct client can follow the current provider documentation exactly and can shape every request and response. Socialite offers a smaller application-facing surface, but its provider behavior and supported field semantics remain tied to the package implementation. The README does not claim that Socialite replaces provider documentation, so direct implementation may be preferable for an unusual or rapidly changing OAuth service.

Editorial conclusion

Adopt overtrue/socialite when a PHP application needs provider-specific OAuth2 login outside Laravel and you can maintain each platform's registration and redirect settings. Do not choose it as a complete identity system, a credential store, or a substitute for a provider's current OAuth documentation. Verify the exact provider configuration, redirect URI, required user fields, and platform-specific restrictions first, then review the MIT LICENSE file before integrating the package.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. overtrue/socialite on GitHub
4. README
5. Releases