README

Socialite is an OAuth2 Authentication tool. It is inspired by laravel/socialite, You can easily use it in any PHP project.

Requirement

PHP >= 7.4

Installation

$ composer require "overtrue/socialite" -vvv

Usage

For Laravel 5: overtrue/laravel-socialite

authorize.php:

<?php

use Overtrue\Socialite\SocialiteManager;

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

$socialite = new SocialiteManager($config);

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

return redirect($url);

callback.php:

<?php

use Overtrue\Socialite\SocialiteManager;

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

$socialite = new SocialiteManager($config);

$code = request()->query('code');

$user = $socialite->create('github')->userFromCode($code);

$user->getId();        // 1472352
$user->getNickname();  // "overtrue"
$user->getUsername();  // "overtrue"
$user->getName();      // "安正超"
$user->getEmail();     // "anzhengchao@gmail.com"
...

Configuration

Now we support the following sites:

Alipay, Dingtalk, facebook, github, google, linkedin, outlook, weibo, taobao, qq, wechat, douyin, baidu, feishu, and douban.

Each create uses the same configuration keys: client_id, client_secret, redirect.

Example:

...
  'weibo' => [
    'client_id'     => 'your-app-id',
    'client_secret' => 'your-app-secret',
    'redirect'      => 'http://localhost/socialite/callback.php',
  ],
...

Custom app name

You can use any name you like as the name of the application, such as foo, and set provider using provider key：

$config = [
    'foo' => [
        'provider' => 'github',  // <-- 
        'client_id' => 'your-app-id',
        'client_secret' => 'your-app-secret',
        'redirect' => 'http://localhost/socialite/callback.php',
    ],
       
    // another github app
    'bar' => [
        'provider' => 'github',  // <-- 
        'client_id' => 'your-app-id',
        'client_secret' => 'your-app-secret',
        'redirect' => 'http://localhost/socialite/callback.php',
    ],
    //...
];

Extends custom provider

You can create application from you custom provider easily，you have to ways to do this:

Using custom creator:

$config = [
    'foo' => [
        'provider' => 'myprovider',  // <-- 
        'client_id' => 'your-app-id',
        'client_secret' => 'your-app-secret',
        'redirect' => 'http://localhost/socialite/callback.php',
    ],
];

$socialite = new SocialiteManager($config);
   
$socialite->extend('myprovider', function(array $config) {
    return new MyCustomProvider($config);
});

$app = $socialite->create('foo');

Using provider:

👋🏻 Your custom provider class must be implements of Overtrue\Socialite\Contracts\ProviderInterface.

class MyCustomProvider implements \Overtrue\Socialite\Contracts\ProviderInterface 
{
    //...
}

then set provider with the class name:

$config = [
    'foo' => [
        'provider' => MyCustomProvider::class,  // <-- class name
        'client_id' => 'your-app-id',
        'client_secret' => 'your-app-secret',
        'redirect' => 'http://localhost/socialite/callback.php',
    ],
];

$socialite = new SocialiteManager($config);
$app = $socialite->create('foo');

Alipay

If you want to use alipay create, you need set config like below.

...
  'alipay' => [
    // the key, pointed by the key value of this array, can also be named as 'app_id' like the official documentation.
    'client_id' => 'your-app-id', 
 
    // Please refer to the official documentation, in the official management background configuration RSA2.
    // Note: This is your own private key.
    // Note: Do not allow the private key content to have extra characters.
    // Recommendation: For security, you can read directly from the file. But here as long as the value, please remember to remove the head and tail of the decoration.
    'rsa_private_key' => 'your-rsa-private-key',

    // Be sure to set this value and make sure that it is the same address value as set in the official admin system.
    // the key, pointed by the key value of this array, can also be named as 'redirect_url' like the official documentation.
    'redirect' => 'http://localhost/socialite/callback.php',
  ],
...

Only RSA2 personal private keys are supported, so stay tuned if you want to log in with a certificate.

DingTalk

Follow the documentation and configure it in the development panel.

Note: We only support QR code access to third-part websites. i.e exchange for user information(opendid, unionid and nickname)

...
'dingtalk' => [
    // or 'app_id'
    'client_id' => 'your app id',

    // or 'app_secret' 
    'client_secret' => 'your app secret',

    // or 'redirect_url'
    'redirect' => 'redirect URL'
],
...

Douyin

Note： using the Douyin create that if you get user information directly using access token, set up the openid first. the openid can be obtained by code when access is obtained, so call userFromCode() automatically configured for you openid, if call userFromToken() first call withOpenId()

$user = $socialite->create('douyin')->userFromCode('here is auth code');

$user = $socialite->create('douyin')->withOpenId('openId')->userFromToken('here is a access token');

Baidu

You can choose the form you want display by using withDisplay().

create$authUrl = $socialite->driver('baidu')->withDisplay('mobile')->redirect();

popup mode is the default setting with display. basic is the default with scopes.

Taobao

You can choose the form you want display by using withView().

$authUrl = $socialite->create('taobao')->withView('wap')->redirect();

web mode is the default setting with display. user_info is the default with scopes.

WeChat

We support Open Platform Third-party Platform webpage authorizations on behalf of Official Account.

You just need input your config like below config. Official Accounts authorizations only doesn't need.

...
[
    'wechat' =>
        [
            'client_id' => 'client_id',
            'client_secret' => 'client_secret',
            'redirect' => 'redirect-url',

            // Open Platform - Third-party Platform Need
            'component' => [
                // or 'app_id', 'component_app_id' as key
                'id' => 'component-app-id',
                // or 'app_token', 'access_token', 'component_access_token' as key
                'token' => 'component-access-token',
            ]
        ]
],
...

Scope

Before redirecting the user, you may also set "scopes" on the request using the scope method. This method will overwrite all existing scopes:

$response = $socialite->create('github')
                ->scopes(['scope1', 'scope2'])->redirect();

Redirect URL

You may also want to dynamically set redirect_uri，you can use the following methods to change the redirect_uri URL:

$url = 'your callback url.';

$socialite->redirect($url);
// or
$socialite->withRedirectUrl($url)->redirect();

State

Your app can use a state parameter for making sure the response belongs to a request initiated by the same user, therefore preventing cross-site request forgery (CSFR) attacks. A CSFR attack occurs when a malicious attacker tricks the user into performing unwanted actions that only the user is authorized to perform on a trusted web application, and all will be done without involving or alerting the user.

Here's the simplest example of how providing the state can make your app more secure. in this example, we use the session ID as the state parameter, but you can use whatever logic you want to create value for the state.

Redirect with `state` parameter

<?php
session_start();
 
$config = [
    //...
];

// Assign to state the hashing of the session ID
$state = hash('sha256', session_id());

$socialite = new SocialiteManager($config);

$url = $socialite->create('github')->withState($state)->redirect();

return redirect($url);

Validate the callback `state`

Once the user has authorized your app, the user will be redirected back to your app's redirect_uri. The OAuth server will return the state parameter unchanged. Check if the state provided in the redirect_uri matches the state generated by your app:

<?php
session_start();
 
$state = request()->query('state');
$code = request()->query('code');
 
// Check the state received with current session id
if ($state != hash('sha256', session_id())) {
    exit('State does not match!');
}
$user = $socialite->create('github')->userFromCode($code);

// authorized

Additional parameters

To include any optional parameters in the request, call the with method with an associative array:

$response = $socialite->create('google')
                    ->with(['hd' => 'example.com'])->redirect();

User interface

Standard user api:

$user = $socialite->create('github')->userFromCode($code);

{
  "id": 1472352,
  "nickname": "overtrue",
  "name": "安正超",
  "email": "anzhengchao@gmail.com",
  "avatar": "https://avatars.githubusercontent.com/u/1472352?v=3",
  "raw": {
    "login": "overtrue",
    "id": 1472352,
    "avatar_url": "https://avatars.githubusercontent.com/u/1472352?v=3",
    "gravatar_id": "",
    "url": "https://api.github.com/users/overtrue",
    "html_url": "https://github.com/overtrue",
    ...
  },
  "token_response": {
    "access_token": "5b1dc56d64fffbd052359f032716cc4e0a1cb9a0",
    "token_type": "bearer",
    "scope": "user:email"
  }
}

You can fetch the user attribute as a array keys like these:

$user['id'];        // 1472352
$user['nickname'];  // "overtrue"
$user['name'];      // "安正超"
$user['email'];     // "anzhengchao@gmail.com"
...

Or using the method:

mixed   $user->getId();
?string $user->getNickname();
?string $user->getName();
?string $user->getEmail();
?string $user->getAvatar();
?string $user->getRaw();
?string $user->getAccessToken(); 
?string $user->getRefreshToken();
?int    $user->getExpiresIn();
?array  $user->getTokenResponse();

Get raw response from OAuth API

The $user->getRaw() method will return an array of the API raw response.

Get the token response when you use userFromCode()

The $user->getTokenResponse() method will return an array of the get token(access token) API response.

Note: This method only return a valid array when you use userFromCode(), else will return null because use userFromToken() have no token response.

Get user with access token

$accessToken = 'xxxxxxxxxxx';
$user = $socialite->userFromToken($accessToken);

Enjoy it! ❤️

Reference

PHP 扩展包开发

想知道如何从零开始构建 PHP 扩展包？

请关注我的实战课程，我会在此课程中分享一些扩展开发经验 —— 《PHP 扩展包实战教程 - 从入门到发布》

License

MIT

helingfeng / socialite

Maintainers

Details

README

Requirement

Installation

Usage

Configuration

Custom app name

Extends custom provider

Alipay

DingTalk

Douyin

Baidu

Taobao

WeChat

Scope

Redirect URL

State

Redirect with `state` parameter

Validate the callback `state`

Additional parameters

User interface

Standard user api:

Get raw response from OAuth API

Get the token response when you use userFromCode()

Get user with access token

Reference

PHP 扩展包开发

License

helingfeng / socialite

Maintainers

Details

README

Requirement

Installation

Usage

Configuration

Custom app name

Extends custom provider

Alipay

DingTalk

Douyin

Baidu

Taobao

WeChat

Scope

Redirect URL

State

Redirect with state parameter

Validate the callback state

Additional parameters

User interface

Standard user api:

Get raw response from OAuth API

Get the token response when you use userFromCode()

Get user with access token

Reference

PHP 扩展包开发

License

Redirect with `state` parameter

Validate the callback `state`