Keycloak Utils

oidc-spa is provider agnostic. You won’t find any Keycloak-only logic in the core package.

If you are using Keycloak, oidc-spa/keycloak exposes small utilities to leverage Keycloak-specific URLs and endpoints.

These utilities are pure (no side effects) and only need your issuerUri. createKeycloakUtils() is memoized, so it’s safe to call often.

Import

import { createKeycloakUtils, isKeycloak } from "oidc-spa/keycloak";

Optional runtime check: is this issuer Keycloak?

Useful when your app can run against multiple providers.

const oidc = await getOidc(); // or useOidc() or inject(Oidc)

if (!isKeycloak({ issuerUri: oidc.issuerUri })) {
    console.log("The authorization server is not a Keycloak instance");
    return;
}

Create the utils object

const keycloakUtils = createKeycloakUtils({ issuerUri: oidc.issuerUri });

Common use cases

Redirect to the registration page (instead of login)

oidc.login({
    doesCurrentHrefRequiresAuth: false,
    transformUrlBeforeRedirect: keycloakUtils.transformUrlBeforeRedirectForRegister
});

Link to the Keycloak Account Console

Users can update their profile, password, MFA, sessions, etc.

const accountUrl = keycloakUtils.getAccountUrl({
    clientId: oidc.clientId,
    validRedirectUri: oidc.validRedirectUri,
    locale: "en" // Optional
});

See: Redirecting to your IdP's account managment page

Fetch the Keycloak user profile (Keycloak-internal endpoint)

This is richer than the decoded ID token. Equivalent of keycloak-js .loadUserProfile().

const accessToken = await oidc.getAccessToken(); // or (await oidc.getTokens()).accessToken

const userProfile = await keycloakUtils.fetchUserProfile({ accessToken });

userProfile.id;
userProfile.username;
userProfile.attributes;

Fetch user info (OIDC userinfo endpoint)

Equivalent of keycloak-js .loadUserInfo().

const accessToken = await oidc.getAccessToken(); // or (await oidc.getTokens()).accessToken

const userInfo = await keycloakUtils.fetchUserInfo({ accessToken });
userInfo.sub;

The userInfo object is similarly shaped as what you get if you decode the payload of the access token (which you shouldn't do on the client, see: JWT Of the Access Token)

import { decodeJwt } from "oidc-spa/decode-jwt";
const decodedAccessToken = decodeJwt(accessToken);

Admin Console URLs

Only show these links to privileged users (for example realm-admin).

keycloakUtils.adminConsoleUrl; // Admin console for the current realm
keycloakUtils.adminConsoleUrl_master; // Admin console for the "master" realm

Parse the issuer URI

const { issuerUriParsed } = keycloakUtils;

// Example issuerUri:
// "https://auth.my-company.com/realms/myrealm"
issuerUriParsed.origin; // "https://auth.my-company.com"
issuerUriParsed.realm; // "myrealm"
issuerUriParsed.kcHttpRelativePath; // undefined or "/auth" if the issuer uri was "https://auth.my-company.com/auth/realms/myrealm"