README

Laravel package for Keycloak token management - store, refresh, introspect, and manage OAuth tokens. Supports both User tokens (Authorization Code Flow) and Client tokens (Client Credentials Flow).

Installation

composer require jinom/keycloak-sdk

Publish the config file:

php artisan vendor:publish --tag="keycloak-config"

Configuration

Add these environment variables to your .env:

KEYCLOAK_BASE_URL=https://your-keycloak-server.com
KEYCLOAK_REALM=your-realm
KEYCLOAK_CLIENT_ID=your-client-id
KEYCLOAK_CLIENT_SECRET=your-client-secret

# Service Account (Client Credentials) - Optional
# Falls back to KEYCLOAK_CLIENT_ID/SECRET if not set
KEYCLOAK_SERVICE_ACCOUNT_ENABLED=true
KEYCLOAK_SERVICE_CLIENT_ID=your-service-client-id
KEYCLOAK_SERVICE_CLIENT_SECRET=your-service-client-secret

# Token Cache - Optional
KEYCLOAK_TOKEN_CACHE_PREFIX=keycloak_tokens
KEYCLOAK_TOKEN_CACHE_TTL=2592000
KEYCLOAK_TOKEN_BUFFER_SECONDS=30
KEYCLOAK_CLIENT_TOKEN_TTL=300

Usage

User Token (Authorization Code Flow)

For operations on behalf of a user:

use Jinom\Keycloak\Facades\KeycloakSdk;

// Store tokens after OAuth callback
KeycloakSdk::storeTokens($userId, [
    'access_token' => $token,
    'refresh_token' => $refreshToken,
    'expires_in' => 300,
]);

// Get a valid token (auto-refreshes if expired)
$token = KeycloakSdk::getValidToken($userId);

// Check if user has valid tokens
if (KeycloakSdk::hasValidTokens($userId)) {
    // User is authenticated
}

// Get all token data
$tokenData = KeycloakSdk::getTokenData($userId);

// Introspect a token
$introspection = KeycloakSdk::introspectToken($token);

// Clear tokens (e.g., on logout)
KeycloakSdk::clearTokens($userId);

Client Token (Client Credentials Flow)

For service-to-service communication without user context:

use Jinom\Keycloak\Facades\KeycloakSdk;

// Get client token for system operations
$clientToken = KeycloakSdk::getClientToken();

// Use for API calls
Http::withToken($clientToken)->get('https://api.example.com/users');

Using Dependency Injection

use Jinom\Keycloak\Contracts\TokenManagerInterface;

class MyController extends Controller
{
    public function __construct(
        private TokenManagerInterface $tokenManager
    ) {}

    public function userAction(int $userId)
    {
        // User token
        $token = $this->tokenManager->getValidToken($userId);
    }

    public function systemAction()
    {
        // Client token
        $token = $this->tokenManager->getClientToken();
    }
}

When to Use Which Token?

API Reference

Keycloak Setup for Client Credentials

1. Go to Keycloak Admin Console
2. Select your realm
3. Go to Clients → Select your client
4. Enable Service Account Enabled under Settings
5. Add required Service Account Roles under Service Account Roles tab

License

MIT