OAuth2 Token Driver (Enterprise)

Introduction

Note: This driver is only available with Kipchak Enterprise.

The OAuth2 Token Driver is an enterprise Kipchak driver that requests OAuth 2.0 client credentials tokens and caches them until expiry. It is built for multi-tenant or multi-service setups where you need multiple token profiles.

Key features include:

• Multi-Connection Support: Define multiple auth servers and client credentials.
• Token Caching: Reuses tokens until expiry using Kipchak's filecache driver.
• Flexible Payloads: Add provider-specific fields via params.
• Convenience Access: Fetch the full token response or just the access token.

Installation

To install this driver, you need to access the Enterprise Composer repository at https://php.pkgs.1x.ax.

If you have an enterprise license, please contact your account representative for access.

composer require kipchak/driver-oauth2-token

Initialise the Driver

Add the following line to your drivers/drivers.php file:

\Kipchak\Driver\OAuth2Token\OAuth2Token::initialise($container);

Configuration

Create a config file named kipchak.oauth2-token.php in your project's config directory.

Connection Settings

Define connections in the connections array. Each key (e.g., default, billing) is a connection name.

• token_url: OAuth 2.0 token endpoint.
• client_id: OAuth 2.0 client ID.
• client_secret: OAuth 2.0 client secret.
• scope: Optional space-delimited scopes.
• params: Optional extra form fields (e.g., audience, resource).
• cache.enabled: Enable or disable caching per connection.
• cache.connection: Filecache connection name (default: default).
• cache.key: Optional custom cache key. Defaults to oauth2-default.token.{connection_name}.
• cache.safety_buffer: Seconds subtracted from expires_in to refresh before expiry.

Example Configuration

<?php

use function Kipchak\Core\env;

return [
    'connections' => [
        'default' => [
            'token_url' => env('OAUTH2_TOKEN_URL', 'https://auth.example.com/oauth2/token'),
            'client_id' => env('OAUTH2_CLIENT_ID', 'client-id'),
            'client_secret' => env('OAUTH2_CLIENT_SECRET', 'client-secret'),
            'scope' => env('OAUTH2_SCOPE', 'read write'),
            'params' => [
                // 'audience' => env('OAUTH2_AUDIENCE', 'https://api.example.com')
            ],
            'cache' => [
                'enabled' => true,
                'connection' => 'default',
                // Defaults to oauth2-default.token.{connection_name} when omitted.
                'key' => 'oauth2-default.token.default',
                // Subtracted (in seconds) from expires_in to refresh before expiry.
                'safety_buffer' => 30,
            ],
        ],
    ]
];

Usage

Code Example

<?php

use Kipchak\Driver\OAuth2Token\OAuth2Token;

$tokenClient = OAuth2Token::get('default');
$token = $tokenClient->getToken(); // Full response array
$accessToken = $tokenClient->getAccessToken(); // Convenience string

Notes

• The driver caches tokens only when expires_in is present in the token response.
• Ensure the Filecache driver is initialised in your application when caching is enabled.

Source

The source code for this driver is hosted internally.