OIDC & service tokens¶
Keycloak::oidc($guard) gives you the OpenID Connect / OAuth 2 endpoints of a guard's realm and client.
Token-endpoint methods return Keycloak's JSON answer as an array (access_token, expires_in,
refresh_token, refresh_expires_in, id_token, token_type, scope, ...).
All calls share the package's HTTP settings (timeouts, retries on connection errors, TLS verification), and
Http::fake() works with them in tests.
Service-to-service calls¶
The most common backend need is calling another API as this service:
use Illuminate\Support\Facades\Http;
Http::withKeycloakToken()->get('https://orders.internal/api/orders'); // default guard
Http::withKeycloakToken('api')->post('https://billing.internal/api/invoices', $data);
Http::withKeycloakToken('api', 'billing:write')->post(/* ... */); // with a scope
$token = Keycloak::serviceToken('api'); // the raw string
The token is obtained with the client credentials grant (enable Service accounts on the client) and
cached until shortly before it expires (admin.token_expiry_margin). Every request, worker and server that
shares the cache reuses it.
To call another service as the current user, forward their token:
Token exchange¶
Trade the user's token for one issued to another client (RFC 8693). Token exchange must be enabled in Keycloak.
$tokens = Keycloak::oidc('api')->exchange($request->bearerToken(), audience: 'inventory-api');
Http::withToken($tokens['access_token'])->get('https://inventory.internal/api/stock');
Password grant¶
Useful for first-party mobile apps, CLIs and tests. Requires Direct access grants on the client.
use Bhry98\KeycloakAuth\Exceptions\OidcException;
Route::post('/api/login', function (Request $request) {
try {
return Keycloak::oidc('api')->password($request->input('username'), $request->input('password'));
} catch (OidcException $e) {
// $e->error() === 'invalid_grant', $e->errorDescription(), $e->status()
return response()->json(['message' => 'Invalid credentials'], 401);
}
});
Refresh¶
Client credentials, code exchange¶
Keycloak::oidc('api')->clientCredentials('scope-a scope-b'); // uncached, full answer
Keycloak::oidc('web')->code($code, $redirectUri, $codeVerifier); // custom frontends
Introspection¶
Ask Keycloak whether a token is still active, for example for high-risk operations where you don't want to wait for the token to expire:
$result = Keycloak::oidc('api')->introspect($jwt); // full RFC 7662 answer
$active = Keycloak::oidc('api')->isActive($jwt); // cached for token.introspection_cache_ttl
Userinfo¶
Logout and revocation¶
Keycloak::oidc('api')->logout($refreshToken); // end the Keycloak session (back-channel)
Keycloak::oidc('api')->revoke($refreshToken); // revoke a token
Keycloak::oidc('web')->logoutUrl($idToken, url('/')); // front-channel logout URL for browsers
Discovery¶
UMA permissions¶
See Authorization → UMA:
checkPermission() and permissions().
Errors¶
Every failure raises a Bhry98\KeycloakAuth\Exceptions\OidcException (a KeycloakException):