socialite
4.11.2
Socialite is an OAuth2 authentication tool. It is inspired by laravel/socialite and you can easily use it in any PHP project. English document
The tool now supports the following platforms: Facebook, Github, Google, Linkedin, Outlook, QQ, TAPD, Alipay, Taobao, Baidu, DingTalk, Weibo, WeChat, Douyin, Feishu, Lark, Douban, Enterprise WeChat, Tencent Cloud, Line, Gitee, Coding.
If you like my projects and want to support me, click here ❤️
PHP >= 8.0.2
composer require " overtrue/socialite " -vvvUsers only need to create corresponding configuration variables, then use tools to create authentication applications for each platform, and easily obtain the platform's access_token and user-related information. For details on the tool implementation logic, please refer to the OAuth2 documents of each major platform.
Using the tool is roughly divided into the following steps:
A more convenient integration package created for Laravel users: overtrue/laravel-socialite
authorize.php : Let the user jump to platform authentication
<?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 (); // "[email protected]"
. . . It works out of the box by setting the same key-value pairs for each platform: client_id , client_secret , redirect .
Example:
$ config = [
' weibo ' => [
' client_id ' => ' your-app-id ' ,
' client_secret ' => ' your-app-secret ' ,
' redirect ' => ' http://localhost/socialite/callback.php ' ,
],
' facebook ' => [
' client_id ' => ' your-app-id ' ,
' client_secret ' => ' your-app-secret ' ,
' redirect ' => ' http://localhost/socialite/callback.php ' ,
],
]; You can name each platform with any name you like, such as foo . After using the alias method, you need to set an additional provider key in the configuration, so as to tell the toolkit how to correctly find the program you want:
$ config = [
// 为 github 应用起别名为 foo
' foo ' => [
' provider ' => ' github ' , // <-- provider name
' client_id ' => ' your-app-id ' ,
' client_secret ' => ' your-app-secret ' ,
' redirect ' => ' http://localhost/socialite/callback.php ' ,
],
// 另外一个名字叫做 bar 的 github 应用
' bar ' => [
' provider ' => ' github ' , // <-- provider name
' client_id ' => ' your-app-id ' ,
' client_secret ' => ' your-app-secret ' ,
' redirect ' => ' http://localhost/socialite/callback.php ' ,
],
//...
];
$ socialite = new SocialiteManager ( $ config );
$ appFoo = $ socialite -> create ( ' foo ' );
$ appBar = $ socialite -> create ( ' bar ' );You can easily create applications from custom service providers by following these two points:
Use custom creator
As shown in the following code, the service provider name is defined for the foo application, but the tool itself does not support it yet, so the creator extend() is used to create an instance of the service provider in the form of a closure function.
$ 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 ' );Important
? Your custom service provider class must implement the OvertrueSocialiteContractsProviderInterface interface
class MyCustomProvider implements Overtrue Socialite Contracts ProviderInterface
{
//...
} Next, set the class name for provider so that tools can find the class and instantiate it:
$ config = [
' foo ' => [
' provider ' => MyCustomProvider::class, // <-- 类名
' client_id ' => ' your-app-id ' ,
' client_secret ' => ' your-app-secret ' ,
' redirect ' => ' http://localhost/socialite/callback.php ' ,
],
];
$ socialite = new SocialiteManager ( $ config );
$ app = $ socialite -> create ( ' foo ' );Different platforms have different configuration methods. In order to ensure the normal operation of the tool, please make sure that the configuration of the platform you are using is set as expected.
Please configure as follows
$ config = [
' alipay ' => [
// 这个键名还能像官方文档那样叫做 'app_id'
' client_id ' => ' your-app-id ' ,
// 请根据官方文档，在官方管理后台配置 RSA2
// 注意： 这是你自己的私钥
// 注意： 不允许私钥内容有其他字符
// 建议： 为了保证安全，你可以将文本信息从磁盘文件中读取，而不是在这里明文
' rsa_private_key ' => ' your-rsa-private-key ' ,
// 确保这里的值与你在服务后台绑定的地址值一致
// 这个键名还能像官方文档那样叫做 'redirect_url'
' redirect ' => ' http://localhost/socialite/callback.php ' ,
// 沙箱模式接入地址见 https://opendocs.alipay.com/open/220/105337#%E5%85%B3%E4%BA%8E%E6%B2%99%E7%AE%B1
' sandbox ' => false ,
]
. . .
];
$ socialite = new SocialiteManager ( $ config );
$ user = $ socialite -> create ( ' alipay ' )-> userFromCode ( ' here is auth code ' );
// 详见文档后面 "User interface"
$ user -> getId (); // 1472352
$ user -> getNickname (); // "overtrue"
$ user -> getUsername (); // "overtrue"
$ user -> getName (); // "安正超"
. . .This tool currently only supports RSA2 personal private key authentication method.
As the documentation shows
Note: This tool only supports QR code to connect to third-party websites to obtain user information (opeid, unionid and nickname)
$ config = [
' dingtalk ' => [
// or 'app_id'
' client_id ' => ' your app id ' ,
// or 'app_secret'
' client_secret ' => ' your app secret ' ,
// or 'redirect_url'
' redirect ' => ' redirect URL '
]
];
$ socialite = new SocialiteManager ( $ config );
$ user = $ socialite -> create ( ' dingtalk ' )-> userFromCode ( ' here is auth code ' );
// 详见文档后面 "User interface"
$ user -> getId (); // 1472352
$ user -> getNickname (); // "overtrue"
$ user -> getUsername (); // "overtrue"
$ user -> getName (); // "安正超"
. . .Note: When using the Douyin service, if you want to directly use access_token to obtain user information, please set openid first. Call
withOpenId()first and thenuserFromToken()
$ config = [
' douyin ' => [
' client_id ' => ' your app id ' ,
' client_secret ' => ' your app secret ' ,
' redirect ' => ' redirect URL '
]
];
$ socialite = new SocialiteManager ( $ config );
$ user = $ socialite -> create ( ' douyin ' )-> userFromCode ( ' here is auth code ' );
$ user = $ socialite -> create ( ' douyin ' )-> withOpenId ( ' openId ' )-> userFromToken ( ' here is the access token ' );Note: When using the
头条service, if you want to directly use access_token to obtain user information, please set openid first. CallwithOpenId()first and thenuserFromToken()
$ config = [
' toutiao ' => [
' client_id ' => ' your app id ' ,
' client_secret ' => ' your app secret ' ,
' redirect ' => ' redirect URL '
]
];
$ socialite = new SocialiteManager ( $ config );
$ user = $ socialite -> create ( ' toutiao ' )-> userFromCode ( ' here is auth code ' );
$ user = $ socialite -> create ( ' toutiao ' )-> withOpenId ( ' openId ' )-> userFromToken ( ' here is the access token ' );Note: When using the
西瓜service, if you want to directly use access_token to obtain user information, please set openid first. CallwithOpenId()first and thenuserFromToken()
$ config = [
' xigua ' => [
' client_id ' => ' your app id ' ,
' client_secret ' => ' your app secret ' ,
' redirect ' => ' redirect URL '
]
];
$ socialite = new SocialiteManager ( $ config );
$ user = $ socialite -> create ( ' xigua ' )-> userFromCode ( ' here is auth code ' );
$ user = $ socialite -> create ( ' xigua ' )-> withOpenId ( ' openId ' )-> userFromToken ( ' here is the access token ' ); There is no difference in other configurations. In terms of usage, you can easily choose the mode of redirecting the login page through withDisplay()
$ authUrl = $ socialite -> create ( ' baidu ' )-> withDisplay ( ' mobile ' )-> redirect (); popup mode is the default usage mode within the tool. basic is the default scope value used.
You can use internal application mode by configuring app_ticket in some simple ways
$ config = [
' feishu ' => [
// or 'app_id'
' client_id ' => ' your app id ' ,
// or 'app_secret'
' client_secret ' => ' your app secret ' ,
// or 'redirect_url'
' redirect ' => ' redirect URL ' ,
// 如果你想使用使用内部应用的方式获取 app_access_token
// 对这个键设置了 'internal' 值那么你已经开启了内部应用模式
' app_mode ' => ' internal '
]
];
$ socialite = new SocialiteManager ( $ config );
$ feishuDriver = $ socialite -> create ( ' feishu ' );
$ feishuDriver -> withInternalAppMode ()-> userFromCode ( ' here is code ' );
$ feishuDriver -> withDefaultMode ()-> withAppTicket ( ' app_ticket ' )-> userFromCode ( ' here is code ' );You can use internal application mode by configuring app_ticket in some simple ways
$ config = [
' lark ' => [
// or 'app_id'
' client_id ' => ' your app id ' ,
// or 'app_secret'
' client_secret ' => ' your app secret ' ,
// or 'redirect_url'
' redirect ' => ' redirect URL ' ,
// 如果你想使用使用内部应用的方式获取 app_access_token
// 对这个键设置了 'internal' 值那么你已经开启了内部应用模式
' app_mode ' => ' internal '
]
];
$ socialite = new SocialiteManager ( $ config );
$ larkDriver = $ socialite -> create ( ' lark ' );
$ larkDriver -> withInternalAppMode ()-> userFromCode ( ' here is code ' );
$ larkDriver -> withDefaultMode ()-> withAppTicket ( ' app_ticket ' )-> userFromCode ( ' here is code ' ); Other configurations are the same as on other platforms, you can select the type of redirect page you want to display by using withView()
$ authUrl = $ socialite -> create ( ' taobao ' )-> withView ( ' wap ' )-> redirect (); The web mode is the default display mode used by the tool, user_info is the default scope value.
We support open platforms to authorize third-party platform web pages on behalf of public accounts.
You just need to enter your configuration like below. Official accounts do not require authorization.
. . .
[
' wechat ' =>
[
' client_id ' => ' client_id ' ,
' client_secret ' => ' client_secret ' ,
' redirect ' => ' redirect-url ' ,
// 开放平台 - 第三方平台所需
' 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 ' ,
]
]
],
... You need to additionally configure team_url as your team domain name, for example:
$ config = [
' coding ' => [
' team_url ' => ' https://{your-team}.coding.net ' ,
' client_id ' => ' your app id ' ,
' client_secret ' => ' your app secret ' ,
' redirect ' => ' redirect URL ' ,
]
]; You may need to set the responseType. You can use the withResponseType function to set it. The default is code and it can also be set to id_token or code & id_token
https://developer.paypal.com/docs/log-in-with-paypal/integrate/generate-button/
$ config = [
' paypal ' => [
' client_id ' => ' AT****************** ' ,
' client_secret ' => ' EK************** ' ,
' sandbox ' => false ,
' redirect_url ' => " nativexo://paypalpay " ,
],
]; You can also use scopes() method to set "scopes" on the request before redirecting the user. This method will overwrite all existing scopes:
$ response = $ socialite -> create ( ' github ' )
-> scopes ([ ' scope1 ' , ' scope2 ' ])-> redirect (); You can also set ' redirect_uri ' dynamically, you can use the following method to change the redirect_uri URL:
$ url = ' your callback url. ' ;
$ socialite -> redirect ( $ url );
// or
$ socialite -> withRedirectUrl ( $ url )-> redirect ();Your application can prevent cross-site request forgery (CSFR) attacks by using a status parameter to ensure that the response belongs to the same user who initiated the request. CSFR attacks occur when a malicious attacker tricks a user into performing unwanted actions that only the user has permission to perform on a trusted web application, all without involving or warning the user.
Here's a minimalist example of how providing state can make your application more secure. In this example, we use the session ID as the state parameter, but you can use any logic you want to create a value for the state.
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 );stateOnce the user authorizes your app, the user will be redirected back to your app's redirect_uri. The OAuth server returns the status parameters unchanged. Check that the status provided in the redirect_uri matches the status generated by the application:
<?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 View more documentation on state parameters
To include any optional parameters in the request, call the with() method passing an associative array of the values you want to set:
$ response = $ socialite -> create ( ' google ' )
-> with ([ ' hd ' => ' example.com ' ])-> redirect (); $ user = $ socialite -> create ( ' github ' )-> userFromCode ( $ code );{
"id" : 1472352 ,
"nickname" : " overtrue " ,
"name" : "安正超" ,
"email" : " [email protected] " ,
"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 get the user attribute as an array key like this:
$ user [ ' id ' ]; // 1472352
$ user [ ' nickname ' ]; // "overtrue"
$ user [ ' name ' ]; // "安正超"
$ user [ ' email ' ]; // "[email protected]"
. . . Or use the method of the User object:
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 ();
$user->getRaw() method returns an array .
The $user->getTokenResponse() method will return an array containing the response returned from the API when acquiring the token.
Note: This method only returns a valid array when you use
userFromCode(), otherwise it will return null becauseuserFromToken()does not have an HTTP response of token.
$ accessToken = ' xxxxxxxxxxx ' ;
$ user = $ socialite -> userFromToken ( $ accessToken );Wondering how to build a PHP extension package from scratch?
Please pay attention to my practical course, where I will share some extension development experience - "PHP Extension Pack Practical Tutorial - From Getting Started to Release"
MIT
