README.md

Ely.by Provider for OAuth 2.0 Client

This package provides Ely.by OAuth 2.0 support for the PHP League's OAuth 2.0 Client.

Installation

To install, use composer:

composer require ely/oauth2-client

Usage

Usage is the same as The League's OAuth client, using \Ely\OAuth2\Client\Provider as the provider. You can find more information in League repository README.

You can get your own clientId and clientSecret at Ely.by Account OAuth2 registration page.

<?php
$provider = new \Ely\OAuth2\Client\Provider([
    'clientId'     => '{elyby-client-id}',
    'clientSecret' => '{elyby-client-secret}',
    'redirectUri'  => 'http://example.com/callback-uri',
]);

We suggest to put this provider object into service locator for access it at any time or mock for testing. In code below we think, that $provider contains our provider object.

Authorization Code Flow

First of all, you must generate redirect user to route, which will set state session value and redirect user to Ely.by authorization page. This can be done by such code, placed into controller:

<?php
$authUrl = $provider->getAuthorizationUrl();
$_SESSION['oauth2state'] = $provider->getState();
header('Location: ' . $authUrl);
exit();

Note, that getAuthorizationUrl() takes as argument array of overriding parameters. For example, if you want request additional scopes and change app description, then you must pass scope and description keys with needed values:

<?php
$authUrl = $provider->getAuthorizationUrl([
    'scope' => ['account_info', 'account_email'],
    'description' => 'My super application!',
]);

After user finish authentication and authorization on Ely.by Account site, he will be redirected back, on redirectUri, that you specified in Provider configuration. Inside redirectUri handler you must check for errors and state matches. If all checks passed normal, then try to exchange received auth_code to access_token. This can be done by code like below:

<?php
if (isset($_GET['error'])) {
    echo 'Oh no! The error ' . $_GET['error'] . ' with message ' . $_GET['message'];
} elseif (!isset($_GET['state']) || $_GET['state'] !== $_SESSION['oauth2state']) {
    unset($_SESSION['oauth2state']);
    echo 'Invalid state value.';
} else {
    // Try to get an access token (using the authorization code grant)
    $token = $provider->getAccessToken(new \League\OAuth2\Client\Grant\AuthorizationCode(), [
        'code' => $_GET['code'],
    ]);

    // Optional: Now you have a token you can look up a users account data
    try {
        // We got an access token, let's now get the user's details
        $account = $provider->getResourceOwner($token);

        // Use these details to create a new profile
        printf('Hello %s!', $account->getUsername());
    } catch (\Ely\OAuth2\Client\Exception\IdentityProviderException $e) {
        // Failed to get user details
        echo 'Cannot get user account identity. The error is ' . $e->getMessage();
    }

    // Use this to interact with an API on the users behalf
    echo $token->getToken();
}

Refreshing a Token

Refresh tokens are only provided to applications which request offline access. You can specify offline access by setting the scope option on authorization url generating:

<?php
$authUrl = $provider->getAuthorizationUrl([
    'scope' => ['account_info', 'account_email', 'offline_access'],
]);

It is important to note that the refresh token is only returned on the first request after this it will be null. You should securely store the refresh token when it is returned:

<?php
$token = $provider->getAccessToken('authorization_code', [
    'code' => $code
]);

// persist the token in a database
$refreshToken = $token->getRefreshToken();

Now you have everything you need to refresh an access token using a refresh token:

<?php
$token = $provider->getAccessToken(new League\OAuth2\Client\Grant\RefreshToken(), [
    'refresh_token' => $refreshToken,
]);

Testing

$ ./vendor/bin/phpunit

Contributing

Please see CONTRIBUTING for details.

Credits

This package was designed and developed within the Ely.by project team. We also thank all the contributors for their help.

License

The MIT License (MIT). Please see License File for more information.