README

This library extends the League OAuth2 Client library to provide OpenID Connect Discovery support for providers that expose a .well-known configuration endpoint.

Installation

To install in an existing (or new) Oauth2 Client Provider library:

Use composer:

composer require cloudcogsio/oauth2-openid-connect-discovery

Change the client to extend \Cloudcogs\OAuth2\Client\OpenIDConnect\AbstractOIDCProvider instead of \League\OAuth2\Client\Provider\AbstractProvider
Remove the following methods

~~getResourceOwnerDetailsUrl~~ ~~getBaseAuthorizationUrl~~ ~~getBaseAccessTokenUrl~~

Existing OAuth2 Client

class MyCustomClient extends \League\OAuth2\Client\Provider\AbstractProvider
{
    public function getResourceOwnerDetailsUrl(AccessToken $token)
    {
        ...
    }

    public function getBaseAuthorizationUrl()
    {
        ...
    }

    public function getBaseAccessTokenUrl(array $params)
    {
        ...
    }
}

Updated OAuth2 Client with OpenID Connect Discovery Support

class MyCustomClient extends \Cloudcogs\OAuth2\Client\OpenIDConnect\AbstractOIDCProvider
{
    ...
}

The existing client can now make use of the OIDC mechanisms implemented by this library.

See https://oauth2-client.thephpleague.com/providers/implementing for more information on implementing a new Client Provider.

Usage

Usage is the same as The League's OAuth client. Configuration options changes are required.

URL options can be removed

~~'urlAuthorize'~~ ~~'urlAccessToken'~~ ~~'urlResourceOwnerDetails'~~

Existing configuration

$provider = new MyCustomClient([
   'clientId'                => 'XXXXXX',    // The client ID assigned to you by the provider
   'clientSecret'            => 'XXXXXX',    // The client password assigned to you by the provider
   'redirectUri'             => 'https://my.example.com/your-redirect-url/',
   'urlAuthorize'            => 'https://service.example.com/authorize',
   'urlAccessToken'          => 'https://service.example.com/token',
   'urlResourceOwnerDetails' => 'https://service.example.com/resource'
]);

New configuration

$provider = new MyCustomClient([
    'clientId'                => 'XXXXXX',    // The client ID assigned to you by the provider
    'clientSecret'            => 'XXXXXX',    // The client password assigned to you by the provider
    'redirectUri'             => 'https://my.example.com/your-redirect-url/',
    'well_known_endpoint'     => 'https://identity.provider.com/.well-known/openid-configuration',
    'publickey_cache_provider'=> '',
]);

well_known_endpoint - The URL of the .well-known/openid-configuration endpoint of the IDP.
publickey_cache_provider - An empty string OR An instance of a \Laminas\Cache\Storage\Adapter\* storage adapter. See https://github.com/laminas/laminas-cache

Additional Notes and Usage

Your client provider instance will now have added functionality such as token introspection (if supported by your IDP) and the ability to obtain further configuration details from the provider.

Configuration data is accessed by proxying to the Discovery object from the client provider.

// Get the discovered configurations from the provider instance
$discovered = $provider->Discovery();

// Access standard OpenID Connect configuration via supported methods
$issuer = $discovered->getIssuer();
$supported_grants = $discovered->getGrantTypesSupported();
$authorization_endpoint = $discovered->getAuthorizationEndpoint();

// Or overloading for provider specific configuration
$custom_config = $discovered->custom_config;

// Cast to string to obtain the raw JSON discovery response
// All available properties for overloading can be seen in the JSON object.
$json_string = (string) $discovered;

IDP Public Key(s)

During endpoint discovery, the IDP public key(s) are retrieved and cached locally. This is needed to decode the access token (if required).

Caching of Public Keys

Caching of JWKs are handled by an instance of a \Laminas\Cache\Storage\Adapter\* storage adapter. If none is provided, \Laminas\Cache\Storage\Adapter\FileSystem is used.

You can provide your own instance of a \Laminas\Cache\Storage\Adapter\* to handle storage of the public keys.

Example

$storageAdapter = new \Laminas\Cache\Storage\Adapter\MongoDB($mdbOptions);

$provider = new MyCustomClient([
    'clientId'                => 'XXXXXX',    // The client ID assigned to you by the provider
    'clientSecret'            => 'XXXXXX',    // The client password assigned to you by the provider
    'redirectUri'             => 'https://my.example.com/your-redirect-url/',
    'well_known_endpoint'     => 'https://identity.provider.com/.well-known/openid-configuration',
    'publickey_cache_provider'=> $storageAdapter,
]);

Token Introspection

The AccessToken issued by the IDP can be decoded locally to obtain additional information.

// Decode the access token
$access_token = $AccessToken->getToken();
$data = $provider->introspectToken($access_token);

Token Introspection via the IDP (optional)

All tokens issued by the IDP (accessToken, refreshToken etc.) can be introspected using the token introspection endpoint if one is made available by the IDP.

// Decode the refresh token
$refresh_token = $AccessToken->getRefreshToken();
$data = $provider->introspectToken($refresh_token);

License

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

cloudcogsio / oauth2-openid-connect-discovery

Maintainers

Details