Skip to content

Latest commit

 

History

History
248 lines (178 loc) · 9.87 KB

README.md

File metadata and controls

248 lines (178 loc) · 9.87 KB
Raw

OAuth 2.0 Client

Join the chat at https://gitter.im/thephpleague/oauth2-client

Build Status Coverage Status Latest Stable Version Total Downloads Latest Unstable Version License

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
  • PHP 7.0
  • HHVM

Usage

Authorization Code Flow

Note: This example code requires the Google+ API to be enabled in your developer console

$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;

    // Unix timestamp of when the token will expire, and need refreshing
    echo $token->expires;
}

Refreshing a Token

Once and as long as your application is authorized, you then only need to refresh an expired access token. To do so, simply reuse this refresh token from your data store to request a refresh.

$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]);

Built-In Providers

This package currently has built-in support for:

  • Eventbrite
  • Facebook
  • Github
  • Google
  • Instagram
  • LinkedIn
  • Microsoft

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.

Managing LinkedIn Scopes

The LinkedIn provider included in this package does not include scopes by default. When creating your LinkedIn provider, you can specify the scopes your application may authorize.

$provider = new League\OAuth2\Client\Provider\LinkedIn([
    'clientId'          => '{linkedin-client-id}',
    'clientSecret'      => '{linkedin-client-secret}',
    'redirectUri'       => 'https://example.com/callback-url',
    'scopes'            => ['r_basicprofile r_emailaddress'],
]);

It is important to note, each scope must be space delimited and contained within one string.

At the time of authoring this documentation, the following scopes are available.

  • r_basicprofile
  • r_emailaddress
  • rw_company_admin
  • w_share

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.

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';

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.