README

OAuth 2.0 and OpenID Connect client library for PHP.

Installation

Install with composer :

composer require b2pweb/parroauth2-client

Simple usage

For a simple usage, using Authorization Server Metadata RFC 8414 or OpenID Connection discovery, you can see example directory.

Password authentication

Authenticate to a provider using password grant type (cf: RFC 6749#4.3).

This example simply configure the OAuth 2.0 client, and call the token endpoint of the provider with owner's credentials (i.e. username and password).

Standard authentication flow

Implements the client-side authentication using authorization_code grant type (cf: RFC 6749#4.1) which is the recommended authorization flow.

• First the session storage is configured
• Then the provider and the client are loaded
• Register extensions
  • JwtAccessToken to enable local introspection of the access token
  • Pkce to enable PKCE RFC 7636 to mitigate authorization code interception attack
  • IdTokenValidator (only for OpenID) to enable verification of the ID Token
  • TokenStorage store the access token into session, and provide it into oauth endpoints
  • RequiredScopeValidator assert given scopes are provided in the access token.
• Perform the authentication process if the token is not present or expired, by using AuthorizationCodeFlow
• Once authenticated, perform userinfo and introspection
• Also implements the logout action, using revocation endpoint and redirect to the OP for stop the session

Access token check on server side

Check the access token passed as Authorization: Bearer header using local introspection.

Advanced usage

Configure provider manually

If the authentication provider do not implement the auto-discovery, or you want to configure manually, you can use the ProviderBuilder :

$loader = new \Parroauth2\Client\Provider\ProviderLoader();

// Configure and create the provider
$provider = $loader->builder('http://my-op.example.com')
    ->openid() // Enable openid connection on the endpoint

    // Configure endpoints
    ->tokenEndPoint('/token')
    ->authorizationEndPoint('/auth')
    ->introspectionEndPoint('/introspect')
    
    // Configure public key for local introspection
    ->addKeyFile('./keys/provider.pub')
    
    ->create()
;

// Create the client
$client = $provider->client((new \Parroauth2\Client\ClientConfig('client_id'))->setSecret('secret'));

Lazy provider

In some case, you should delay the loading of the provider, and only load it when it's necessary. This is necessary when use a dependency injection container which inject the client or the provider into a service.

In this context you can use ProviderLoader::lazy(), which allows loading provider only when calling OP endpoints.

Design consideration

EndPoints

End points are immutable, any call to setters will return a new instance of the endpoint.

So the following code is invalid :

/** @var $client \Parroauth2\Client\ClientInterface */
$token = $client->endPoints()->token();
$token->refresh('MyRefreshToken'); // This instruction has no effect : the return value is ignored

$token->call(); // This call will fail : no token has been provided

To save a state, like provide a token, you should use Extensions with an EndPointTransformerInterface, or inject parameters manually at each endpoint calls.

Extensions

Extension consist of a class with single method configure() which takes the client as parameter. They permit modifying or configuring any mutable elements of client like :

• Change client configuration
• Register or replace an end point
• Register an EndPointTransformerInterface

To simply apply an endpoint transformer, you can inherit AbstractEndPointTransformerExtension, implement the desired endpoint transformation method, and use CallableEndPointInterface::onResponse() to intercept responses.

Note: because endpoints are immutable, the endpoint transformer must return the configured instance of the endpoint