integrate laravel with identity solutuions like Keycloak

RajeshKumar1

How to integrate laravel with identity solutuions like Keycloak

How to Integrate Laravel with Identity Solutions like Keycloak

Keycloak can be integrated with Laravel for secure authentication (SSO) using open standards like OpenID Connect (OIDC), OAuth2, or SAML. The approach depends on your app architecture (web, API, SPA).

1. Integrate via OAuth2/OpenID Connect

Recommended for standard web login flows and APIs.

Install a Package: Use a library such as socialiteproviders/keycloak or the laravel-keycloak-guard.[1][2][3]

Install via Composer:

      composer require socialiteproviders/keycloak

      composer require robsontenorio/laravel-keycloak-guard

Configure Environment Variables:

    KEYCLOAK_CLIENT_ID="your-client-id"
    KEYCLOAK_CLIENT_SECRET="your-client-secret"
    KEYCLOAK_REDIRECT_URI="http://localhost/auth/keycloak/callback"
    KEYCLOAK_BASE_URL="http://your-keycloak-server/"
    KEYCLOAK_REALM="yourrealm"

Update Laravel Configs:

Add details to 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_BASE_URL'),
        'realms' => env('KEYCLOAK_REALM'),
      ],

Configure guards and providers as needed, especially if using OIDC for SSO or JWT for APIs.[4][2]

Protect Routes:
Use the relevant middleware:

    Route::middleware('keycloak')->group(function () {
      // Protected routes
    });

Frontend API Use-Case (JWT):
- Users authenticate with Keycloak directly and get a JWT.
- Frontend sends this JWT with requests to your Laravel API.
- Laravel validates JWT with the chosen package (laravel-keycloak-guard) for each request.[2]

2. Integrate via SAML

Recommended if your organization requires SAML-based SSO.

Use a package like 24Slides/laravel-saml2, or a commercial plugin from MiniOrange.[5][6][7]
Configure Keycloak as a SAML IdP and your Laravel app as a SAML SP.
Exchange metadata between Keycloak and Laravel.
Set up routes and middleware for SAML login/logout, adjust user creation logic as needed.[6][7]

3. Direct Keycloak API Integration

For custom user management, registration flows, etc.

Use Guzzle or a similar HTTP client for REST API integration.[8]
Example: registration or user info via Keycloak admin REST API by creating a Laravel service class.

Example Package Workflows

Web login via OIDC
- User visits protected route.
- Redirected to Keycloak for login.
- Keycloak redirects back with an authorization code.
- Laravel exchanges code for token and authenticates user.
API authentication via JWT
- SPA/mobile app authenticates with Keycloak.
- Passes JWT in API requests.
- Laravel validates JWT signature, claims, expiration.[2]

Useful Packages

socialiteproviders/keycloak – OIDC login for Laravel web apps.[9][3]
robsontenorio/laravel-keycloak-guard – Keycloak JWT for APIs.[1][2]
24Slides/laravel-saml2 – SAML SSO with Keycloak as IdP.[5]
miniorange/laravel-saml – Commercial SAML integration.[7][6]

References for Step-by-Step Guides

Summary:

Choose the protocol (OIDC/OAuth2 or SAML) and matching package.
Configure Keycloak and your Laravel app (env vars, config.php, guards).
Use provided middleware to protect routes.
Validate JWT or SAML assertions on each request.

This approach enables secure, standards-based SSO for Laravel apps with Keycloak, scalable for both web and API use cases, with implementation details available from the listed packages and guides.[9][3][7][4][2]

[1] https://github.com/robsontenorio/laravel-keycloak-guard
[2] https://laravel-news.com/package/robsontenorio-laravel-keycloak-guard
[3] https://laravel-news.com/package/socialiteproviders-keycloak
[4] https://www.maccsy.com/en/how-to/keycloak-laravel-guide/
[5] https://github.com/24Slides/laravel-saml2/issues/98
[6] https://plugins.miniorange.com/step-by-step-guide-for-laravel-saml
[7] https://plugins.miniorange.com/saml-single-sign-on-sso-for-laravel-using-keycloak-as-idp
[8] https://infofusion.in/keycloak-registration-integration-with-your-laravel-application-via-api/
[9] https://qiita.com/YosukeKentuckyFriedChicken/items/b2694e31d3fe5b18d93f
[10] https://www.youtube.com/watch?v=vQ9bLAjfz14
[11] https://laracasts.com/discuss/channels/general-discussion/laravel-jetstream-keycloak
[12] https://www.linkedin.com/pulse/keycloak-spring-boot-oauth-20-openid-connect-oidc-young-gyu-kim-e444c
[13] https://plugins.miniorange.com/laravel-oauth-openid-connect-single-sign-on-sso-using-keycloak
[14] https://www.reddit.com/r/laravel/comments/yrdmh8/guide_to_adding_saml_single_signon_sso_to_a/
[15] https://gitlab-docs.creationline.com/ee/administration/auth/oidc.html
[16] http://demo.te.net.id:8001/yayong/howto/-/blob/main/SSO/SSO%20SAML%20Keycloak%20Laravel%20-%20Miniorange.md
[17] https://www.drupal.org/docs/extending-drupal/contributed-modules/contributed-module-documentation/oauth-openid-connect-login-oauth2-client-sso-login/configure-keycloak-as-oauth-openid-connect-provider-for-drupal-login
[18] https://github.com/monicahq/monica/discussions/7490
[19] https://stackoverflow.com/questions/73517728/how-can-i-integrate-keycloak-sso-with-php-application

RajeshKumar1

Great question. There are two clean ways to integrate Laravel with Keycloak, depending on your app shape:

A. Web login (server-rendered Laravel or Inertia) → OIDC Authorization Code + PKCE
B. API backend (separate SPA/mobile frontend) → Bearer-only API that validates Keycloak JWTs

Below is a battle-tested, step-by-step for both.

A) Web login with Authorization Code + PKCE (recommended)

1) Create a client in Keycloak

Realm → Clients → Create
- Client type: OpenID Connect
- Authentication: Off (public client)
- Standard flow (authorization code): On
- Valid redirect URIs: https://yourapp.com/auth/callback (+ local dev)
- Web origins: your app origin(s)
  PKCE is built into OIDC code flow; Keycloak supports it out of the box. (Keycloak)

2) Add a Laravel OIDC client
Easiest path is Socialite + SocialiteProviders/Keycloak:

composer require laravel/socialite socialiteproviders/keycloak

config/services.php:

'keycloak' => [
  'client_id'     => env('KEYCLOAK_CLIENT_ID'),
  'client_secret' => env('KEYCLOAK_CLIENT_SECRET'), // for confidential clients; omit for public
  'redirect'      => env('KEYCLOAK_REDIRECT_URI'),
  'base_url'      => env('KEYCLOAK_BASE_URL'), // e.g. https://sso.example.com/realms/myrealm
],

Routes:

Route::get('/auth/redirect', fn() => Socialite::driver('keycloak')->redirect());
Route::get('/auth/callback', function () {
    $oidcUser = Socialite::driver('keycloak')->user(); // ID token + profile
    // map to local user, create/update, then login()
    // ...
    return redirect('/dashboard');
});

Follow the provider’s short docs for Laravel 10/11 event wiring. (socialiteproviders.com, GitHub)

3) Roles/claims mapping
In Keycloak, add Role mappers so tokens contain realm_access.roles or client roles; read them in Laravel to set abilities/policies. (Keycloak)

4) Logout (SSO sign-out)
Redirect users to Keycloak’s end_session_endpoint (from the realm’s OIDC discovery doc) so sessions end centrally. (Keycloak)

Why this flow? It is the OIDC standard, supports PKCE, and is the recommended modern path as vendor-specific adapters were deprecated in favor of standard OIDC. (Keycloak, GitHub)

B) Bearer-only Laravel API (JWT validation)

Use this when your SPA/mobile gets tokens directly from Keycloak and calls your Laravel API with Authorization: Bearer <token>.

1) Create a Bearer-only client in Keycloak

Client type: OIDC
Standard flow: Off
Service accounts: Off
Direct access grants: Off (for pure bearer-only)
The API will only validate incoming tokens. (Keycloak)

2) Validate JWTs in Laravel
Option 1 — Package guard:

composer require robsontenorio/laravel-keycloak-guard

config/auth.php (add a guard that uses the package driver), then protect routes with that guard/middleware. The package reads Keycloak’s realm JWKS and validates RS256 signatures. (GitHub, Laravel News)

Option 2 — Manual JWT validation: fetch JWKS from

https://<host>/realms/<realm>/.well-known/openid-configuration
# → "jwks_uri", typically /realms/<realm>/protocol/openid-connect/certs

Cache keys and verify iss, aud, exp, and signature. (Keycloak, Cloud-IAM Documentation)

3) Authorize by roles/scopes
Read realm_access.roles or resource_access[client].roles from the token and gate routes/policies accordingly. (Keycloak)

C) Offload login at the edge (optional but nice for EKS/Ingress)

If you’d rather keep Laravel “dumb” about OIDC, put oauth2-proxy (or a similar reverse proxy) in front of it with the Keycloak OIDC provider. It handles the whole OIDC/PKCE dance and passes user info in headers (e.g., X-Auth-Request-User). Great with NGINX/Ingress. (OAuth2 Proxy, GitHub, lf-onap.atlassian.net)

Quick checklists

Keycloak

Realm, users/groups/roles
Client (public or confidential) with redirect URIs & web origins
(Optional) Mappers → add roles, email, name claims
JWKS reachable for token verification (Keycloak)

Laravel

Web flow: Socialite + Keycloak provider; handle callback; persist/link users; CSRF/session hardening. (socialiteproviders.com, GitHub)
API flow: Keycloak guard or custom JWT validation against realm JWKS; 401/403 handling; role gates/policies. (GitHub, Cloud-IAM Documentation)
Logout: call Keycloak end_session_endpoint. (Keycloak)

If you tell me which you’re building (SSR Laravel vs SPA+API, plus Laravel version), I’ll drop in exact auth.php, middleware, and example controller/policy code tailored to your project.