Week 30: Identity & Access Management with Keycloak

1. Realms, Clients & Roles

Week 23 covered OIDC in the abstract — an authorization server issuing tokens after login. Keycloak is a concrete, self-hostable implementation of that server, organized around three concepts you'll configure directly.

• Realm — an isolated space of users, roles and clients. Most orgs run one realm per product or per environment (dev/staging/prod), not one per team.
• Client — an application registered to use the realm. Your Angular app is a public client (no client secret — it can't keep one safe in browser-shipped code), configured with the PKCE flow rather than the implicit flow Keycloak's older docs sometimes still show.
• Roles — realm-level or client-level permissions (e.g. admin, editor) assigned to users, embedded directly in the access token's claims once issued.

That last point is what makes Section 3's route guards possible: roles aren't a separate API call away, they're already sitting in the token the app holds after login.

2. Bootstrapping Before the App Renders

Routing decisions (which route a guard allows) can depend on auth state that isn't known until Keycloak finishes its own initialization — checking for an existing session, handling a redirect back from the login page. That has to complete before Angular's router makes its first decision, which means it belongs in app initialization, not a component's constructor.

import { ApplicationConfig, provideAppInitializer, inject } from '@angular/core';
import Keycloak from 'keycloak-js';
import { KEYCLOAK_EVENT_SIGNAL, provideKeycloak, createInterceptorCondition } from 'keycloak-angular';

export const appConfig: ApplicationConfig = {
  providers: [
    provideKeycloak({
      config: {
        url: 'https://auth.example.com',
        realm: 'my-app',
        clientId: 'my-app-web',
      },
      initOptions: {
        onLoad: 'check-sso', // don't force login on every route --
                              // only routes behind a guard require it
        silentCheckSsoRedirectUri: window.location.origin + '/silent-check-sso.html',
      },
    }),
    // ...provideRouter, provideHttpClient, etc.
  ],
};

provideKeycloak() (from keycloak-angular) wires Keycloak's own initialization into Angular's bootstrap sequence via provideAppInitializer internally — the router won't activate its first route until Keycloak has finished checking for an existing session. onLoad: 'check-sso' is deliberate: it checks silently without forcing a login redirect for public routes, leaving the actual "require login" decision to the route guards in Section 3.

3. Role-Based Route Guards

A functional guard (Week 11) reading Keycloak's own state is a natural fit — no custom auth service needed for the common case.

import { inject } from '@angular/core';
import { CanActivateFn, Router } from '@angular/router';
import { Keycloak } from 'keycloak-angular';

export const requireRole = (role: string): CanActivateFn => () => {
  const keycloak = inject(Keycloak);
  const router = inject(Router);

  if (!keycloak.authenticated) {
    keycloak.login({ redirectUri: window.location.href });
    return false;
  }

  const hasRole = keycloak.hasRealmRole(role);
  return hasRole ? true : router.parseUrl('/forbidden');
};

{
  path: 'admin',
  loadChildren: () => import('./admin/admin.routes'),
  canActivate: [requireRole('admin')],
},

Returning router.parseUrl(...) instead of false (Week 11) gives an authenticated-but-unauthorized user a real "forbidden" page rather than a route that silently fails to navigate — a materially better experience for someone who's logged in correctly but simply lacks the role.

4. Attaching the Token

keycloak-angular ships a functional interceptor factory built on the same condition-matching pattern Week 14 used for scoping interceptors to specific requests.

import { provideHttpClient, withInterceptors } from '@angular/common/http';
import { includeBearerTokenInterceptor, createInterceptorCondition, INCLUDE_BEARER_TOKEN_INTERCEPTOR_CONFIG } from 'keycloak-angular';

const bearerCondition = createInterceptorCondition({
  urlPattern: /^https:\/\/api\.example\.com\/.*$/i,
});

export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(withInterceptors([includeBearerTokenInterceptor])),
    { provide: INCLUDE_BEARER_TOKEN_INTERCEPTOR_CONFIG, useValue: [bearerCondition] },
    // ...provideKeycloak from Section 2
  ],
};

Scoping the condition to your own API's URL pattern matters for the same reason Week 14 flagged for any auth interceptor — attaching your access token to requests going to a third-party domain (an analytics SDK, a payment provider) would leak it somewhere it has no business going.

5. Silent Refresh & Session Expiry

Access tokens are deliberately short-lived (often 5 minutes). Without refresh handling, a user mid-session hits a wall of 401s the moment it expires — Keycloak's refresh token exists specifically to renew it invisibly.

import { effect, inject } from '@angular/core';
import { KEYCLOAK_EVENT_SIGNAL, KeycloakEventType, typeEventArgs } from 'keycloak-angular';

const keycloakSignal = inject(KEYCLOAK_EVENT_SIGNAL);

effect(() => {
  const event = keycloakSignal();

  if (event.type === KeycloakEventType.TokenExpired) {
    // keycloak-angular attempts a silent refresh automatically here in
    // most configurations; this is where you'd add app-specific handling
  }

  if (event.type === KeycloakEventType.AuthLogout) {
    router.navigate(['/login']);
  }
});

KEYCLOAK_EVENT_SIGNAL is itself a signal — reacting to auth lifecycle events is exactly the same effect() pattern used everywhere else in the course, not a separate event-subscription API to learn. If a refresh genuinely fails (the refresh token itself expired — a real session timeout, not a routine renewal), route the user to login with their current location preserved, so they land back where they were rather than at a generic home page.

6. Running Keycloak Locally

Developing against a shared staging Keycloak instance is slow and makes test users a shared, fragile resource — a local instance with an exported realm config is worth the one-time setup cost.

services:
  keycloak:
    image: quay.io/keycloak/keycloak:latest
    command: start-dev --import-realm
    environment:
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: admin
    ports:
      - '8080:8080'
    volumes:
      - ./keycloak/my-app-realm.json:/opt/keycloak/data/import/my-app-realm.json

Export your realm's configuration (users, clients, roles) once from the admin console into my-app-realm.json and commit it — every teammate then gets an identical realm, with the same test users and roles, by running docker compose up, instead of manually recreating auth configuration by hand.

7. Hands-on Exercise

8. Knowledge Check

Four quick questions. Expand each to check your answer.