11 KiB
OAuth 2.0 Client
This package makes it stupidly simple to integrate your application with OAuth 2.0 identity providers.
Everyone is used to seeing those "Connect with Facebook/Google/etc" buttons around the Internet and social network integration is an important feature of most web-apps these days. Many of these sites use an Authentication and Authorization standard called OAuth 2.0.
It will work with any OAuth 2.0 provider (be it an OAuth 2.0 Server for your own API or Facebook) and provides support for popular systems out of the box. This package abstracts out some of the subtle but important differences between various providers, handles access tokens and refresh tokens, and allows you easy access to profile information on these other sites.
This package is compliant with PSR-1, PSR-2 and PSR-4. If you notice compliance oversights, please send a patch via pull request.
Requirements
The following versions of PHP are supported.
- PHP 5.4
- PHP 5.5
- PHP 5.6
- HHVM
Usage
Authorization Code Flow
$provider = new League\OAuth2\Client\Provider\<ProviderName>([
'clientId' => 'XXXXXXXX',
'clientSecret' => 'XXXXXXXX',
'redirectUri' => 'https://your-registered-redirect-uri/',
'scopes' => ['email', '...', '...'],
]);
if (!isset($_GET['code'])) {
// If we don't have an authorization code then get one
$authUrl = $provider->getAuthorizationUrl();
$_SESSION['oauth2state'] = $provider->state;
header('Location: '.$authUrl);
exit;
// Check given state against previously stored one to mitigate CSRF attack
} elseif (empty($_GET['state']) || ($_GET['state'] !== $_SESSION['oauth2state'])) {
unset($_SESSION['oauth2state']);
exit('Invalid state');
} else {
// Try to get an access token (using the authorization code grant)
$token = $provider->getAccessToken('authorization_code', [
'code' => $_GET['code']
]);
// Optional: Now you have a token you can look up a users profile data
try {
// We got an access token, let's now get the user's details
$userDetails = $provider->getUserDetails($token);
// Use these details to create a new profile
printf('Hello %s!', $userDetails->firstName);
} catch (Exception $e) {
// Failed to get user details
exit('Oh dear...');
}
// Use this to interact with an API on the users behalf
echo $token->accessToken;
// Use this to get a new access token if the old one expires
echo $token->refreshToken;
// Number of seconds until the access token will expire, and need refreshing
echo $token->expires;
}
Refreshing a Token
$provider = new League\OAuth2\Client\Provider\<ProviderName>([
'clientId' => 'XXXXXXXX',
'clientSecret' => 'XXXXXXXX',
'redirectUri' => 'https://your-registered-redirect-uri/',
]);
$grant = new \League\OAuth2\Client\Grant\RefreshToken();
$token = $provider->getAccessToken($grant, ['refresh_token' => $refreshToken]);
Providers
All providers must extend AbstractProvider, and implement the declared abstract methods.
The following providers are available:
Official providers
These are as many OAuth 2 services as we plan to support officially. Maintaining a wide selection of providers damages our ability to make this package the best it can be, especially as we progress towards v1.0.
Gateway | Composer Package | Maintainer |
---|---|---|
league/oauth2-facebook | Sammy Kaye Powers | |
Github | league/oauth2-github | Steven Maguire |
league/oauth2-google | Woody Gilk | |
league/oauth2-instagram | Steven Maguire | |
league/oauth2-linkedin | Steven Maguire |
Third party providers
If you would like to support other providers, please make them available as a Composer package, then link to them below.
These providers allow integration with other providers not supported by oauth2-client
. They may require an older version
so please help them out with a pull request if you notice this.
Gateway | Composer Package | Maintainer |
---|---|---|
Battle.net | depotwarehouse/oauth2-bnet | Troy Pavlek |
Dropbox | pixelfear/oauth2-dropbox | Jason Varga |
Eventbrite | stevenmaguire/oauth2-eventbrite | Steven Maguire |
FreeAgent | cloudmanaged/oauth2-freeagent | Israel Sotomayor |
Google Nest | grumpydictator/nest-oauth2-provider | James Cole |
Mail.ru | aego/oauth2-mailru | Alexey |
Meetup | howlowck/meetup-oauth2-provider | Hao Luo |
Microsoft | stevenmaguire/oauth2-microsoft | Steven Maguire |
Naver | deminoth/oauth2-naver | SangYeob Bono Yu |
Odnoklassniki | aego/oauth2-odnoklassniki | Alexey |
Square | wheniwork/oauth2-square | Woody Gilk |
Twitch.tv | depotwarehouse/oauth2-twitch | Troy Pavlek |
Uber | stevenmaguire/oauth2-uber | Steven Maguire |
Vkontakte | j4k/oauth2-vkontakte | Jack W |
Yandex | aego/oauth2-yandex | Alexey |
ZenPayroll | wheniwork/oauth2-zenpayroll | Woody Gilk |
Build your own providers
New providers can be created by cloning the layout of an existing package. When choosing a name for your package, please don’t use the league
vendor prefix, as this implies that it is officially supported.
You should use your own username as the vendor prefix, and prepend oauth2-
to the package name to make it clear that your package works with OAuth2 Client. For example, if your GitHub username was santa, and you were implementing the giftpay OAuth2 library, a good name for your composer package would be santa/oauth2-giftpay
.
Implementing your own provider
If you are working with an oauth2 service not supported out-of-the-box or by an existing package, it is quite simple to implement your own. Simply extend League\OAuth2\Client\Provider\AbstractProvider
and implement the required abstract methods:
abstract public function urlAuthorize();
abstract public function urlAccessToken();
abstract public function urlUserDetails(\League\OAuth2\Client\Token\AccessToken $token);
abstract public function userDetails($response, \League\OAuth2\Client\Token\AccessToken $token);
Each of these abstract methods contain a docblock defining their expectations and typical behaviour. Once you have
extended this class, you can simply follow the example above using your new Provider
.
Custom account identifiers in access token responses
Some OAuth2 Server implementations include a field in their access token response defining some identifier
for the user account that just requested the access token. In many cases this field, if present, is called "uid", but
some providers define custom identifiers in their response. If your provider uses a nonstandard name for the "uid" field,
when extending the AbstractProvider, in your new class, define a property public $uidKey
and set it equal to whatever
your provider uses as its key. For example, Battle.net uses accountId
as the key for the identifier field, so in that
provider you would add a property:
public $uidKey = 'accountId';
Make your gateway official
If you want to transfer your provider to the thephpleague
GitHub organization and add it to the list of officially supported providers, please open a pull request on the thephpleague/oauth2-client package. Before new providers will be accepted, they must have 100% unit test code coverage, and follow the conventions and code style used in other OAuth2 Client providers.
Client Packages
Some developers use this library as a base for their own PHP API wrappers, and that seems like a really great idea. It might make it slightly tricky to integrate their provider with an existing generic "OAuth 2.0 All the Things" login system, but it does make working with them easier.
Install
Via Composer
$ composer require league/oauth2-client
Testing
$ ./vendor/bin/phpunit
Contributing
Please see CONTRIBUTING for details.
Credits
License
The MIT License (MIT). Please see License File for more information.