Implementing a Provider Client

💡 TIP You may create new provider clients by copying the layout of an existing package. See the first party and third party provider clients for good examples.

⚠️ Attention! When choosing a name for your package, please don’t use the league vendor prefix or the League vendor namespace, as this implies 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 your package works with league/oauth2-client.

For example, if your GitHub username is santa, and you are implementing the giftpay OAuth 2.0 client library, a good name for your Composer package would be santa/oauth2-giftpay.

If you are working with an OAuth 2.0 service provider not supported out-of-the-box or by an existing package, you may implement your own. To do so, extend League\OAuth2\Client\Provider\AbstractProvider and implement the required abstract methods:

public function getBaseAuthorizationUrl();
public function getBaseAccessTokenUrl(array $params);
public function getResourceOwnerDetailsUrl(AccessToken $token);
protected function getDefaultScopes();
protected function checkResponse(ResponseInterface $response, $data);
protected function createResourceOwner(array $response, AccessToken $token);

Each of these abstract methods has a comment block defining their expectations and typical behavior. Once you have extended this class, you may follow the basic usage example using your new provider client class.

If you wish to use your provider client class to make authenticated requests to the provider, you will also need to define how you provide the token to the service. If this is done via headers, you should override this method:

protected function getAuthorizationHeaders($token = null);

This package includes a trait for implementing Bearer authorization. To use the trait, include it in your provider client class with a use statement:

use League\OAuth2\Client\Provider\AbstractProvider;
use League\OAuth2\Client\Tool\BearerAuthorizationTrait;

class SomeProvider extends AbstractProvider
{
    use BearerAuthorizationTrait;

    /** ... **/
}

Resource Owner Identifiers in Access Token Responses

In services where the resource owner is a person, the resource owner is sometimes referred to as an end-user.

We have abstracted away as much of the resource owner details as possible, since these are not part of the OAuth 2.0 specification and are very specific to each service provider. This provides greater flexibility to each provider, allowing them to handle the implementation details for resource owners.

As such, the AbstractProvider does not specify an access token resource owner identifier. Since OAuth 2.0 does not define the resource owner identifier, the AbstractProvider cannot understand what to do with a resource owner identifier if it receives one. The provider client class is responsible for setting the name of this identifier, using the ACCESS_TOKEN_RESOURCE_OWNER_ID constant. The name is different for each provider, so check your provider’s documentation.

/**
 * Name of the resource owner identifier field that is
 * present in the access token response (if applicable)
 */
const ACCESS_TOKEN_RESOURCE_OWNER_ID = null;

After setting ACCESS_TOKEN_RESOURCE_OWNER_ID on your provider client class, the AccessToken returned from AbstractProvider::getAccessToken() will have its $resourceOwnerId property set, which you may retrieve by calling AccessToken::getResourceOwnerId().

Next, implement the AbstractProvider::createResourceOwner() method. This method accepts as parameters a response array and an AccessToken object. You may use this information to request resource owner details from your service, returning an object that implements League\OAuth2\Client\Provider\ResourceOwnerInterface. AbstractProvider::getResourceOwner() returns this object.

Make It Available

If you find a package for a certain provider useful, chances are someone else will too! Make your package available by putting it on Packagist and GitHub. After it’s available, submit a pull request to the oauth2-client repository, adding your provider client to the provider client list.

Make It Official

If you want to transfer your provider client to the thephpleague GitHub organization and add it to the list of officially-supported provider clients, please open a pull request on the thephpleague/oauth2-client package. Before new provider clients will be accepted, they must have 100% unit test code coverage and follow the conventions and code style used in the other official PHP League OAuth 2.0 Client provider clients.