PHPackages                             minsu/laravel-oidc-auth - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Authentication & Authorization](/categories/authentication)
4. /
5. minsu/laravel-oidc-auth

ActiveLibrary[Authentication & Authorization](/categories/authentication)

minsu/laravel-oidc-auth
=======================

Laravel package for OIDC (OpenID Connect) authentication with Keycloak-compatible IAM servers

v1.0.0(4mo ago)01MITPHPPHP ^8.2

Since Jan 9Pushed 4mo agoCompare

[ Source](https://github.com/MinSU-ICT-Unit/minsu-laravel-oidc-auth)[ Packagist](https://packagist.org/packages/minsu/laravel-oidc-auth)[ RSS](/packages/minsu-laravel-oidc-auth/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (8)Versions (2)Used By (0)

Laravel OIDC Auth Package
=========================

[](#laravel-oidc-auth-package)

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
--------

[](#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
------------

[](#installation)

### Via Composer

[](#via-composer)

```
composer require minsu/laravel-oidc-auth
```

### Publish Configuration

[](#publish-configuration)

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

### Publish Migrations

[](#publish-migrations)

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

Configuration
-------------

[](#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
-----

[](#usage)

### Routes

[](#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

[](#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

[](#login-button)

In your frontend, create a login button:

```
Sign In
```

Or in Vue with Inertia:

```
Sign In
```

### Registration

[](#registration)

To get the registration URL:

```
use Minsu\LaravelOidcAuth\Services\OidcService;

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

### Using the Service

[](#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

[](#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
-------------

[](#customization)

### Custom User Model

[](#custom-user-model)

Change the user model in config:

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

### Custom Routes

[](#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

[](#custom-oidc-sub-field)

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

```
OIDC_SUB_FIELD=external_id
```

Requirements
------------

[](#requirements)

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

Security Considerations
-----------------------

[](#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
---------------

[](#troubleshooting)

### "PKCE is required for this client"

[](#pkce-is-required-for-this-client)

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

### "Invalid state parameter"

[](#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

[](#token-validation-fails)

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

License
-------

[](#license)

MIT

Contributing
------------

[](#contributing)

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

Support
-------

[](#support)

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

###  Health Score

35

—

LowBetter than 80% of packages

Maintenance78

Regular maintenance activity

Popularity1

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity46

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

121d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/0756dec6d23b77d351fc41b9651831cbb321716927d57c3c98ac2ac13629fd3f?d=identicon)[osapdinjayvee](/maintainers/osapdinjayvee)

---

Top Contributors

[![jayveeosapdin-ux](https://avatars.githubusercontent.com/u/238366831?v=4)](https://github.com/jayveeosapdin-ux "jayveeosapdin-ux (1 commits)")

---

Tags

laravelAuthenticationoauth2OpenID Connectkeycloakoidciam

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/minsu-laravel-oidc-auth/health.svg)

```
[![Health](https://phpackages.com/badges/minsu-laravel-oidc-auth/health.svg)](https://phpackages.com/packages/minsu-laravel-oidc-auth)
```

###  Alternatives

[tymon/jwt-auth

JSON Web Token Authentication for Laravel and Lumen

11.5k49.1M347](/packages/tymon-jwt-auth)[php-open-source-saver/jwt-auth

JSON Web Token Authentication for Laravel and Lumen

8359.8M53](/packages/php-open-source-saver-jwt-auth)[laragear/two-factor

On-premises 2FA Authentication for out-of-the-box.

339785.3k8](/packages/laragear-two-factor)[alajusticia/laravel-logins

Session management in Laravel apps, user notifications on new access, support for multiple separate remember tokens, IP geolocation, User-Agent parser

2011.0k](/packages/alajusticia-laravel-logins)[api-platform/laravel

API Platform support for Laravel

59126.4k6](/packages/api-platform-laravel)[kovah/laravel-socialite-oidc

OpenID Connect OAuth2 Provider for Laravel Socialite

2073.7k](/packages/kovah-laravel-socialite-oidc)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)