README

A Laravel package for OpenID Connect (OIDC) authentication with Keycloak-compatible IAM servers. This package provides a complete OIDC authentication solution with PKCE support, token management, and user synchronization.

Features

• ✅ OIDC Authentication Flow: Full authorization code flow with PKCE
• ✅ User Management: Automatic user creation and synchronization
• ✅ Token Management: Access token, refresh token, and ID token handling
• ✅ PKCE Support: Enhanced security for public clients
• ✅ Keycloak Compatible: Works with Keycloak and Keycloak-compatible IAM servers
• ✅ Configurable: Highly configurable for different use cases
• ✅ Session Management: Secure session handling with CSRF protection
• ✅ Registration Flow: Support for user registration via IAM
• ✅ Token Validation Middleware: Validate JWT tokens for API routes

Installation

Via Composer

composer require minsu/laravel-oidc-auth

Publish Configuration

php artisan vendor:publish --tag=oidc-auth-config

Publish Migrations

php artisan vendor:publish --tag=oidc-auth-migrations
php artisan migrate

Configuration

Add the following to your .env file:

# OIDC Configuration
OIDC_BASE_URL=http://your-iam-server.com
OIDC_REALM=master
OIDC_CLIENT_ID=your-client-id
OIDC_CLIENT_SECRET=your-client-secret  # Optional for public clients
OIDC_REDIRECT_URI=/oidc/callback
OIDC_POST_LOGOUT_REDIRECT_URI=/
OIDC_SCOPE=openid profile email

# Optional Configuration
OIDC_VALIDATE_ISSUER=true
OIDC_VALIDATE_AUDIENCE=true
OIDC_CACHE_DISCOVERY=true
OIDC_CACHE_DISCOVERY_TTL=3600

# Package Configuration
OIDC_ENABLE_ROUTES=true
OIDC_ROUTE_PREFIX=oidc
OIDC_MIDDLEWARE=web
OIDC_USER_MODEL=App\Models\User
OIDC_REDIRECT_AFTER_LOGIN=dashboard
OIDC_REDIRECT_AFTER_LOGOUT=/
OIDC_SUB_FIELD=oidc_sub

Usage

Routes

The package automatically registers the following routes if OIDC_ENABLE_ROUTES=true:

• GET /oidc - Redirects to IAM authorization endpoint
• GET /oidc/callback - Handles OIDC callback
• POST /oidc/logout - Handles logout
• GET /oidc/refresh - Refreshes access token

User Model

Ensure your User model has the oidc_sub field (or configured field name) in the $fillable array:

protected $fillable = [
    'name',
    'email',
    'password',
    'oidc_sub',
];

And make the password field nullable (handled by migrations):

// In your User model, password can be nullable for OIDC-only users

Login Button

In your frontend, create a login button:

<a href="/oidc">Sign In</a>

Or in Vue with Inertia:

<Link href="/oidc">Sign In</Link>

Registration

To get the registration URL:

use Minsu\LaravelOidcAuth\Services\OidcService;

$oidcService = app(OidcService::class);
$registrationUrl = $oidcService->getRegistrationUrl();

Using the Service

use Minsu\LaravelOidcAuth\Services\OidcService;

$oidcService = app(OidcService::class);

// Get authorization URL
$authUrl = $oidcService->getAuthorizationUrl();

// Exchange code for tokens (usually handled by controller)
$tokens = $oidcService->exchangeCodeForToken($code, $codeVerifier);

// Get user info
$userInfo = $oidcService->getUserInfo($accessToken);

// Refresh token
$tokens = $oidcService->refreshToken($refreshToken);

// Get logout URL
$logoutUrl = $oidcService->getLogoutUrl($idToken);

Token Validation Middleware

For API routes that need JWT token validation:

use Minsu\LaravelOidcAuth\Http\Middleware\ValidateOidcToken;

Route::middleware([ValidateOidcToken::class])->group(function () {
    Route::get('/api/protected', function (Request $request) {
        $oidcUser = $request->attributes->get('oidc_user');
        $oidcUserId = $request->attributes->get('oidc_user_id');
        // Use the user info...
    });
});

Customization

Custom User Model

Change the user model in config:

// config/oidc-auth.php
'user_model' => \App\Models\CustomUser::class,

Custom Routes

Disable package routes and define your own:

OIDC_ENABLE_ROUTES=false

Then define routes in your routes/web.php:

use Minsu\LaravelOidcAuth\Http\Controllers\Auth\OidcController;

Route::prefix('auth/oidc')->group(function () {
    Route::get('/', [OidcController::class, 'redirect'])->name('auth.oidc');
    Route::get('/callback', [OidcController::class, 'callback'])->name('auth.oidc.callback');
    Route::post('/logout', [OidcController::class, 'logout'])->name('auth.oidc.logout');
});

Custom OIDC Sub Field

If you want to use a different field name for the OIDC subject:

OIDC_SUB_FIELD=external_id

Requirements

• PHP 8.2+
• Laravel 11.0+ or 12.0+
• Firebase JWT library (included in composer.json)

Security Considerations

1. PKCE: Always enabled by default for enhanced security
2. CSRF Protection: State parameter validation for all OAuth flows
3. Session Security: Session regeneration on login
4. Token Storage: Tokens stored in session (not cookies by default)
5. HTTPS: Always use HTTPS in production

Troubleshooting

"PKCE is required for this client"

Ensure PKCE is enabled (default) and your IAM server supports it.

"Invalid state parameter"

This usually indicates a session issue. The package uses both session and cache for state storage to handle cross-domain redirects.

Token Validation Fails

Ensure your IAM server's JWKS endpoint is accessible and the token issuer matches your configuration.

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions, please open an issue on GitHub.