Skip to content

Configuration

All options live in config/bhry98-keycloak.php (publish it with php artisan keycloak:install). Each option has a comment in the file. This page explains what they do.

Guards

A guard is a named Keycloak realm + client pair. Everything in the package takes an optional guard name: Keycloak::oidc('api'), keycloak.api:api, Keycloak::users('web'), /auth/keycloak/login/web.

'default_guard' => env('KEYCLOAK_DEFAULT_GUARD', 'web'),

'guard' => [
    'web' => [
        'client_id' => env('KC_WEB_CLIENT_ID', env('KEYCLOAK_CLIENT_ID')),
        'client_secret' => env('KC_WEB_CLIENT_SECRET', env('KEYCLOAK_CLIENT_SECRET')),
        'realm' => env('KC_WEB_REALM', env('KEYCLOAK_REALM')),
        'redirect' => env('KC_WEB_REDIRECT_URI', env('KEYCLOAK_REDIRECT_URI')),
        'scopes' => ['openid', 'email', 'profile'],
    ],
    'api' => [ /* ... */ 'audience' => env('KC_API_AUDIENCE') ],
    'admin' => [ /* service account for the Admin API */ ],

    // Add as many as you need: one per frontend, tenant realm, partner...
    'partner-portal' => [
        'base_url' => 'https://sso.partner.test', // another Keycloak server
        'realm' => 'partners',
        'client_id' => 'portal',
        'client_secret' => env('PARTNER_SECRET'),
    ],
],
Key Description
base_url Keycloak server URL. Defaults to the top-level base_url.
realm, client_id, client_secret Realm and client credentials. Use an empty secret for public clients.
redirect Callback URL for the browser login of this guard.
scopes Scopes requested at login.
audience String, comma-separated string, or array. When set, API tokens must name one of these in aud or azp.
issuer Extra trusted issuer(s) for this guard (see Docker & Kubernetes).
auth_guard The Laravel guard the browser login logs into (default: your default guard).
redirect_after_logout Where Keycloak sends the browser after logout.
provisioning true / false to override provisioning.enabled for this guard.
role_clients Clients whose roles count for hasRole() (default: the guard's client_id + the token's azp).

Unknown guard names fall back to the top-level realm / client_id / client_secret.

Admin API

'admin' => [
    'guard' => env('KEYCLOAK_ADMIN_GUARD', 'admin'), // whose credentials obtain the admin token
    'token_expiry_margin' => 30,                      // refresh admin / service tokens 30s early
],

The admin token is obtained once with client credentials and cached until shortly before it expires. A 401 from the Admin API refreshes it and retries the request once.

Token validation

'token' => [
    'leeway' => 30,                     // clock-skew tolerance (seconds)
    'allowed_algs' => ['RS256', 'RS384', 'RS512', 'PS256', 'PS384', 'PS512', 'ES256', 'ES384', 'ES512', 'EdDSA'],
    'allowed_types' => ['Bearer'],      // rejects refresh and ID tokens used as access tokens
    'verify_issuer' => true,
    'issuer' => env('KEYCLOAK_ISSUER'), // public issuer when it differs from base_url
    'jwks_ttl' => 86400,                // realm public keys cache (seconds)
    'jwks_refresh_cooldown' => 30,      // min seconds between key re-downloads on unknown kid
    'introspection_cache_ttl' => 30,    // cache of introspection / UMA answers
],

Do not add none or HS* to allowed_algs

Keycloak signs access tokens with asymmetric keys. Allowing symmetric algorithms opens the door to algorithm-confusion attacks.

Web SSO

'web' => [
    'pkce' => true,                 // PKCE (S256) on the authorization code flow
    'validation' => 'local',        // "local" (expiry check, no network) or "introspect" (cached)
    'refresh_tokens' => true,       // silently refresh with the refresh token
    'refresh_margin' => 15,         // refresh this many seconds before expiry
    'home' => '/',                  // redirect after login when there is no intended URL
],

See Web SSO → Session validation for the trade-offs.

User provisioning

'users_model' => \Bhry98\KeycloakAuth\Models\KCUserModel::class,

'provisioning' => [
    'enabled' => env('KEYCLOAK_PROVISIONING', true),
    'sync_ttl' => 300,  // skip the DB write while the claims are unchanged
    'attributes' => [   // column => claim (dot notation, or a closure)
        'keycloak_id' => 'sub',
        'email' => 'email',
        'username' => 'preferred_username',
        'first_name' => 'given_name',
        'last_name' => 'family_name',
        'name' => 'name',
        'avatar' => 'picture',
        'locale' => 'locale',
        'email_verified' => 'email_verified',
        // 'department' => 'attributes.department',
        // 'tenant_id' => fn ($token) => Tenant::idFor($token->claim('tenant')),
    ],
],

Use your own model by pointing users_model at it. It must have the columns you map and the keycloak_id column. Add the HasKeycloakRoles trait to it to get role helpers.

Closures in config

A closure in attributes stops php artisan config:cache from working. Use a custom resolver (Keycloak::resolveUserUsing()) instead if you cache your config.

Roles

'roles' => [
    'clients' => null, // e.g. ['my-app', 'billing']; null = guard client_id + token azp
],

Infrastructure

'cache' => [
    'store' => env('KEYCLOAK_CACHE_STORE'), // null = default store; Redis recommended in production
    'prefix' => 'bhry98_keycloak',
],

'http' => [
    'timeout' => 10,
    'connect_timeout' => 5,
    'retries' => 2,         // connection errors only, never on 4xx/5xx answers
    'retry_delay' => 100,   // ms
    'verify' => env('KEYCLOAK_VERIFY_SSL', true),
],

'routes' => [
    'enabled' => true,
    'prefix' => 'auth/keycloak',
    'middleware' => ['web'],
    'name' => 'keycloak.',
],

'migrations' => ['auto_load' => true],
'gates' => true, // keycloak-role / keycloak-scope gates and the @keycloakRole directive

Environment variables

Variable Default Purpose
KEYCLOAK_BASE_URL – Keycloak server URL
KEYCLOAK_REALM – Default realm
KEYCLOAK_CLIENT_ID / KEYCLOAK_CLIENT_SECRET – Default client
KEYCLOAK_REDIRECT_URI /auth/keycloak/callback Default login callback
KEYCLOAK_RED_AFTER_LOGOUT APP_URL Post-logout redirect
KEYCLOAK_DEFAULT_GUARD web Guard used when none is given
KC_{WEB,API,ADMIN}_{CLIENT_ID,CLIENT_SECRET,REALM,REDIRECT_URI} defaults above Per-guard overrides
KC_API_AUDIENCE – Required audience for API tokens
KEYCLOAK_ADMIN_GUARD admin Credentials used for the Admin API
KEYCLOAK_ISSUER – Public issuer URL
KEYCLOAK_VERIFY_ISSUER true Check iss
KEYCLOAK_TOKEN_LEEWAY 30 Clock skew (seconds)
KEYCLOAK_JWKS_TTL 86400 Realm keys cache (seconds)
KEYCLOAK_PKCE true PKCE on browser login
KEYCLOAK_WEB_VALIDATION local local or introspect
KEYCLOAK_HOME / Redirect after login
KEYCLOAK_PROVISIONING true Sync users to the database
KEYCLOAK_CACHE_STORE default Cache store
KEYCLOAK_VERIFY_SSL true TLS verification