How keycloak/keycloak-js works
Project type and purpose
• Type: Open-source JavaScript client library (adapter) for browser-based applications
• Purpose: Secure single-page or multi-page web apps by integrating with a Keycloak Identity and Access Management (IAM) server. Offers both authentication (login/logout, token management) and optional authorization (Keycloak Authorization Services).
File structure
• Top-level folders:
– lib/
• keycloak.js (core browser adapter)
• keycloak-authz.js (authorization plugin)
– docs/ (Asciidoc guides, examples)
– test/ (sample app, Playwright tests, test harness)
– .github/ (CI/CD, actions, workflows)
• Config files:
– package.json / tsconfig.json (build)
– .github/workflows/*.yml (CI for releases and tests)
• Patterns: UMD-style library modules, ESM/TypeScript definitions, test-driven via sample app + Playwright.
Readme insights
• Confirms this is the “Keycloak JavaScript adapter” for browser use.
• Links to external Keycloak server and documentation.
• No built-in backend—everything runs in the browser.
Main components
a. Browser-side Web Application
– Your HTML/JS UI (could be React, Angular, raw HTML + script)
– Loads the Keycloak JS library (keycloak.js + optional keycloak-authz.js)
b. Keycloak JS Adapter (Client SDK)
– Core module: initialization, configuration, login redirect, token renewal via iframe or direct grant
– AuthZ plugin: request permissions, evaluate entitlements
c. Keycloak Server (External IAM Service)
– Endpoints:
• /auth/realms/{realm}/protocol/openid-connect/auth (Authorization endpoint)
• /token (Token endpoint)
• /logout (Logout endpoint)
• /authz/entitlement/{resource_server} (Entitlement endpoint for authZ)
d. Browser storage / session
– Token storage (in-memory, localStorage, sessionStorage as configured)
– Silent SSO iframe for token renewal
Relationships & interactions
1. Web App → loads → Keycloak JS Adapter
2. Adapter → Redirects user → Keycloak Server (login)
3. Keycloak Server → Redirects back → Web App (with code or fragment token)
4. Adapter → Exchanges code or reads fragment → Token endpoint → receives access/refresh tokens
5. Adapter ↔ Browser storage (stores tokens, session state)
6. Adapter → Silent‐SSO iframe → Token endpoint (hidden) → renews tokens
7. (Optional) Adapter + AuthZ plugin → Entitlement endpoint → receives permissions/policies
Architectural patterns and design principles
• Adapter pattern: abstracts OIDC/OAuth flows into a simple JS API (init, login, logout, token management)
• Observer/event pattern: emits events (onReady, onAuthSuccess, onAuthError) to the host app
• Single Responsibility: core adapter vs. authorization plugin separated into two modules
• UMD / module compatibility: runs in any JS environment (UMD build, ESM, TypeScript definitions)
Relevant technologies/frameworks
• JavaScript / TypeScript (d.ts files)
• UMD build scripts (via npm)
• Playwright (end-to-end tests)
• Asciidoctor / .mjs guide scripts (documentation)
Detail level
• Do not over-compartmentalize—keep it to ~5–7 components for clarity.
• You capture all essential flows: initialization, authentication, token storage, token renewal, optional authorization.
• If needed, add a small inset showing the test app and Playwright harness to illustrate how the library is validated.