README

A Laravel package that provides seamless integration with Keycloak for authentication using SocialiteProviders. This package enables Laravel applications to authenticate users via a self-hosted Keycloak server with minimal configuration.

Features

Easy integration with self-hosted Keycloak servers
Automatic user creation and synchronization
Configurable authentication routes
Middleware for protecting routes
Support for multiple Laravel versions (9.x, 10.x, 11.x, 12.x)
Built on top of Laravel Socialite and SocialiteProviders

Installation

Install the package via Composer:

composer require mohsen-mhm/laravel-keycloak-auth

Publish the configuration file:

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

Add the Keycloak configuration to your config/services.php:

'keycloak' => [
    'client_id' => env('KEYCLOAK_CLIENT_ID'),
    'client_secret' => env('KEYCLOAK_CLIENT_SECRET'),
    'redirect' => env('KEYCLOAK_REDIRECT_URI'),
    'base_url' => env('KEYCLOAK_SERVER_URL'),
    'realms' => env('KEYCLOAK_REALM'),
],

Environment Configuration

Add the following environment variables to your .env file:

KEYCLOAK_SERVER_URL=http://localhost:8080
KEYCLOAK_REALM=your-realm
KEYCLOAK_CLIENT_ID=your-client-id
KEYCLOAK_CLIENT_SECRET=your-client-secret
KEYCLOAK_AUTO_CREATE_USERS=true
KEYCLOAK_VERIFY_SSL=true

Database Migration

Add a keycloak_id column to your users table:

Schema::table('users', function (Blueprint $table) {
    $table->string('keycloak_id')->nullable()->unique();
});

Usage

Basic Authentication

Redirect users to Keycloak for authentication:

// In your controller
return redirect()->route('keycloak.login');

Or create a login link in your view:

<a href="{{ route('keycloak.login') }}">Login with Keycloak</a>

Protecting Routes

Use the provided middleware to protect your routes:

// In your routes/web.php
Route::middleware(['keycloak.auth'])->group(function () {
    Route::get('/dashboard', [DashboardController::class, 'index']);
    Route::get('/profile', [ProfileController::class, 'show']);
});

Logout

Logout from both Laravel and Keycloak:

// In your controller
return redirect()->route('keycloak.logout');

Or create a logout link:

<form method="POST" action="{{ route('keycloak.logout') }}">
    @csrf
    <button type="submit">Logout</button>
</form>

Using the Service

You can also use the KeycloakAuthService directly:

use MohsenMhm\LaravelKeycloakAuth\Services\KeycloakAuthService;

class YourController extends Controller
{
    public function __construct(private KeycloakAuthService $keycloakAuth)
    {
    }

    public function checkKeycloakStatus()
    {
        if ($this->keycloakAuth->isKeycloakAvailable()) {
            return 'Keycloak is available';
        }
        
        return 'Keycloak is not available';
    }
}

Configuration

The package configuration file (config/keycloak-auth.php) allows you to customize:

Keycloak server settings (URL, realm, client credentials)
Authentication routes
User model and field mapping
Redirect URLs after login/logout
Auto user creation settings

Keycloak Setup

Create a new client in your Keycloak realm
Set the client type to "OpenID Connect"
Enable "Client authentication"
Add your Laravel app's callback URL: http://your-app.com/auth/keycloak/callback
Configure the client scopes as needed

Requirements

PHP 8.2 or higher
Laravel 9.x, 10.x, 11.x, or 12.x
A running Keycloak server

Security Considerations

Always use HTTPS in production
Keep your Keycloak client secret secure
Regularly update the package and its dependencies
Configure proper CORS settings in Keycloak

Contributing

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

License

This package is open-sourced software licensed under the MIT license.

Support

If you encounter any issues or have questions, please create an issue on the GitHub repository.

mohsen-mhm / laravel-keycloak-auth

Maintainers

Details