README

An easy-to-use OAuth2 client library for PHP. Simplify OAuth2 authentication flows with support for multiple providers and token storage.

✨ Features

• 🔐 OAuth2 Authorization Code Flow - Complete implementation
• 🏢 Multiple Providers - Built-in support for Microsoft, Google, and GitHub
• 🔄 Token Management - Secure token storage and retrieval
• 🔧 Extensible - Easy to add custom OAuth2 providers

📋 Table of Contents

• Supported PHP Versions
• Installation
• Quick Start
• Providers
• Token Storage
• Multi-Provider Management
• API Reference
• Examples

Supported PHP Versions

Build Status

🚀 Installation

Install via Composer:

composer require webfiori/oauth

Requirements

• PHP 8.1 or higher
• cURL extension

⚡ Quick Start

Basic OAuth2 Flow

<?php
require_once 'vendor/autoload.php';

use WebFiori\OAuth\OAuth2Client;
use WebFiori\OAuth\Providers\MicrosoftProvider;
use WebFiori\OAuth\Storage\FileTokenStorage;

// Configure your OAuth2 provider
$provider = new MicrosoftProvider(
    'your-client-id',
    'your-client-secret',
    'https://yourapp.com/callback'
);

// Set up token storage
$storage = new FileTokenStorage('/path/to/token/storage');

// Create OAuth2 client
$client = new OAuth2Client($provider, $storage);

// Step 1: Redirect user to authorization URL
if (!isset($_GET['code'])) {
    $authUrl = $client->getAuthorizationUrl(['openid', 'profile', 'email']);
    header('Location: ' . $authUrl);
    exit;
}

// Step 2: Exchange authorization code for tokens
try {
    $tokens = $client->exchangeCodeForToken($_GET['code'], $_GET['state'] ?? null);
    echo "Access token received: " . $tokens['access_token'];
    
} catch (Exception $e) {
    echo "OAuth error: " . $e->getMessage();
}

Microsoft Azure Integration

use WebFiori\OAuth\Providers\MicrosoftProvider;

// Configure for Microsoft Azure AD
$provider = new MicrosoftProvider(
    'your-azure-app-id',
    'your-azure-app-secret',
    'https://yourapp.com/auth/callback',
    'your-tenant-id' // Optional: specify tenant
);

$client = new OAuth2Client($provider, $storage);

// Request specific Microsoft Graph scopes
$authUrl = $client->getAuthorizationUrl([
    'openid',
    'profile', 
    'email',
    'https://graph.microsoft.com/User.Read',
    'https://graph.microsoft.com/Mail.Read'
]);

// After token exchange, use tokens to call Microsoft Graph API
$tokens = $client->exchangeCodeForToken($_GET['code']);
if ($tokens) {
    $graphData = callMicrosoftGraph($tokens['access_token']);
}

🏢 Providers

Microsoft Provider

use WebFiori\OAuth\Providers\MicrosoftProvider;

// Personal Microsoft accounts
$provider = new MicrosoftProvider(
    'client-id',
    'client-secret',
    'https://yourapp.com/callback',
    'common' // Allows both personal and work accounts
);

// Specific Azure AD tenant
$provider = new MicrosoftProvider(
    'client-id',
    'client-secret', 
    'https://yourapp.com/callback',
    'your-tenant-id'
);

// Work or school accounts only
$provider = new MicrosoftProvider(
    'client-id',
    'client-secret',
    'https://yourapp.com/callback',
    'organizations'
);

Google Provider

use WebFiori\OAuth\Providers\GoogleProvider;

$provider = new GoogleProvider(
    'google-client-id',
    'google-client-secret',
    'https://yourapp.com/callback'
);

$client = new OAuth2Client($provider, $storage);

// Request Google-specific scopes
$authUrl = $client->getAuthorizationUrl([
    'openid',
    'email',
    'profile',
    'https://www.googleapis.com/auth/drive.readonly'
]);

GitHub Provider

use WebFiori\OAuth\Providers\GitHubProvider;

$provider = new GitHubProvider(
    'github-client-id',
    'github-client-secret',
    'https://yourapp.com/callback'
);

$client = new OAuth2Client($provider, $storage);

// Request GitHub-specific scopes
$authUrl = $client->getAuthorizationUrl([
    'user:email',
    'read:user',
    'repo'
]);

Custom Provider

use WebFiori\OAuth\Providers\AbstractProvider;

class CustomProvider extends AbstractProvider {
    public function getAuthorizationUrl(): string {
        return 'https://auth.example.com/oauth/authorize';
    }
    
    public function getTokenUrl(): string {
        return 'https://auth.example.com/oauth/token';
    }
    
    public function getDefaultScopes(): array {
        return ['read', 'write'];
    }
    
    public function getUserInfoUrl(): string {
        return 'https://api.example.com/user';
    }
}

// Use custom provider
$provider = new CustomProvider('client-id', 'client-secret', 'callback-url');
$client = new OAuth2Client($provider, $storage);

OAuthManager - Multi-Provider Support

use WebFiori\OAuth\OAuthManager;
use WebFiori\OAuth\Providers\MicrosoftProvider;
use WebFiori\OAuth\Storage\FileTokenStorage;

// Create manager with shared storage
$storage = new FileTokenStorage('/secure/tokens');
$manager = new OAuthManager($storage);

// Register multiple providers
$manager->addProvider('microsoft', new MicrosoftProvider(
    'ms-client-id', 'ms-secret', 'https://app.com/callback'
));

$manager->addProvider('google', new GoogleProvider(
    'google-client-id', 'google-secret', 'https://app.com/callback'
));

// Get clients by provider name
$msClient = $manager->getClient('microsoft');
$googleClient = $manager->getClient('google');

// Check if provider exists
if ($manager->hasProvider('github')) {
    $githubClient = $manager->getClient('github');
}

// Get all registered providers
$providerNames = $manager->getProviderNames(); // ['microsoft', 'google']

// Remove a provider
$manager->removeProvider('google');

Custom Provider

use WebFiori\OAuth\Providers\AbstractProvider;

class CustomProvider extends AbstractProvider {
    public function getAuthorizationUrl(): string {
        return 'https://auth.example.com/oauth/authorize';
    }
    
    public function getTokenUrl(): string {
        return 'https://auth.example.com/oauth/token';
    }
    
    public function getScopes(): array {
        return ['read', 'write', 'admin'];
    }
}

// Use custom provider
$provider = new CustomProvider('client-id', 'client-secret', 'callback-url');
$client = new OAuth2Client($provider, $storage);

🔄 Token Management

Automatic Token Management

use WebFiori\OAuth\TokenManager;

$tokenManager = new TokenManager($storage);

// Store tokens with automatic expiration calculation
$tokenManager->storeTokens([
    'access_token' => 'token_value',
    'refresh_token' => 'refresh_value',
    'expires_in' => 3600 // Automatically calculates expires_at
]);

// Get valid tokens (automatically refreshes if needed)
$validTokens = $tokenManager->getValidTokens($provider);

// Check token status
if ($tokenManager->hasValidTokens()) {
    // Use tokens for API calls
    $accessToken = $tokenManager->getAccessToken();
} else {
    // Redirect to authorization
    $authUrl = $client->getAuthorizationUrl($scopes);
    header('Location: ' . $authUrl);
}

Token Validation

use WebFiori\OAuth\Exceptions\InvalidTokenException;

try {
    // Validate token format and expiration
    $tokenManager->validateToken($tokens);
    
    // Use validated tokens
    $apiResponse = makeApiCall($tokens['access_token']);
    
} catch (InvalidTokenException $e) {
    // Token is invalid or expired
    echo "Token error: " . $e->getMessage();
    
    // Attempt refresh or re-authorization
    if (isset($tokens['refresh_token'])) {
        $newTokens = $client->refreshToken($tokens['refresh_token']);
    } else {
        // Redirect to authorization
        header('Location: ' . $client->getAuthorizationUrl($scopes));
    }
}

📚 API Reference

OAuth2Client

The main client for OAuth2 operations.

Constructor:

public function __construct(Provider $provider, ?TokenStorage $storage = null, ?callable $tokenRequestFactory = null)

Methods:

Provider Classes

MicrosoftProvider:

public function __construct(
    string $clientId,
    string $clientSecret, 
    string $redirectUri,
    string $tenantId = 'common'
)

GoogleProvider:

public function __construct(
    string $clientId,
    string $clientSecret,
    string $redirectUri
)

GitHubProvider:

public function __construct(
    string $clientId,
    string $clientSecret,
    string $redirectUri
)

Provider Methods:

OAuthManager

Multi-provider OAuth2 manager.

Constructor:

public function __construct(?TokenStorage $storage = null)

Methods:

TokenStorage Interface

TokenManager

Token management utility.

Constructor:

public function __construct(TokenStorage $storage)

Methods:

Exceptions

📄 Examples

Complete Microsoft OAuth2 Flow

<?php
require_once 'vendor/autoload.php';

use WebFiori\OAuth\OAuth2Client;
use WebFiori\OAuth\Providers\MicrosoftProvider;
use WebFiori\OAuth\Storage\FileTokenStorage;

session_start();

// Configuration
$provider = new MicrosoftProvider(
    'your-client-id',
    'your-client-secret',
    'https://yourapp.com/callback',
    'common'
);

$storage = new FileTokenStorage();
$client = new OAuth2Client($provider, $storage);

if (!isset($_GET['code'])) {
    // Step 1: Redirect to authorization
    $authUrl = $client->getAuthorizationUrl([
        'openid', 'profile', 'email', 'offline_access'
    ]);
    
    header('Location: ' . $authUrl);
    exit;
} else {
    // Step 2: Handle callback
    try {
        $tokens = $client->exchangeCodeForToken($_GET['code'], $_GET['state'] ?? null);
        
        // Use access token to call Microsoft Graph
        $ch = curl_init('https://graph.microsoft.com/v1.0/me');
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HTTPHEADER => [
                'Authorization: Bearer ' . $tokens['access_token'],
                'Content-Type: application/json'
            ]
        ]);
        
        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);
        
        if ($httpCode === 200) {
            $userData = json_decode($response, true);
            echo "Welcome, " . $userData['displayName'] . "!";
        }
        
    } catch (Exception $e) {
        echo "Error: " . $e->getMessage();
    }
}

Token Refresh Example

<?php
use WebFiori\OAuth\OAuth2Client;
use WebFiori\OAuth\TokenManager;

$tokenManager = new TokenManager($storage);
$tokens = $tokenManager->retrieve('user_tokens');

if ($tokens && isset($tokens['expires_at']) && time() >= $tokens['expires_at']) {
    // Token expired, refresh it
    if (isset($tokens['refresh_token'])) {
        try {
            $newTokens = $client->refreshToken($tokens['refresh_token']);
            $tokenManager->store('user_tokens', $newTokens);
            echo "Token refreshed successfully";
        } catch (Exception $e) {
            echo "Failed to refresh token: " . $e->getMessage();
        }
    }
}

📄 License

This library is licensed under the MIT License. See the LICENSE file for details.

📞 Support

• 🐛 Issue Tracker