# keycloak/keycloak-js architecture

> Architecture diagram of the GitHub repository keycloak/keycloak-js, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/keycloak/keycloak-js
- Repository: https://github.com/keycloak/keycloak-js

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Browser Boundary
    subgraph "Browser"
        App["Web App UI"]:::browser
        Adapter["Keycloak JS Adapter<br/>(core)"]:::browser
        AuthZ["Keycloak AuthZ Plugin"]:::browser
        Storage["Browser Storage<br/>(tokens)"]:::storage
        Iframe["Silent-SSO Iframe"]:::browser
    end

    %% Keycloak Realm Boundary
    subgraph "Keycloak Realm"
        AuthEP["Authorization Endpoint<br/>(GET /auth)"]:::server
        TokenEP["Token Endpoint<br/>(POST /token)"]:::server
        LogoutEP["Logout Endpoint"]:::server
        EntEP["Entitlement Endpoint"]:::server
    end

    %% Test Harness
    subgraph "Test Harness"
        TA_AppTS["app.ts"]:::test
        TA_Index["index.html"]:::test
        TA_Silent["silent-check-sso.html"]:::test
        PlayW["Playwright Tests"]:::test
    end

    %% Documentation & CI/CD
    Doc["Documentation"]:::doc
    CI["CI/CD Workflows"]:::ci

    %% Primary Flows
    App -->|loads| Adapter
    Adapter -->|initializes| AuthZ
    Adapter -->|"redirect GET /auth"| AuthEP
    AuthEP -->|"redirect with code/fragment"| App
    App -->|invokes Adapter| Adapter
    Adapter -->|"POST /token"| TokenEP
    TokenEP -->|"access & refresh tokens"| Adapter
    Adapter -->|stores tokens| Storage

    %% Secondary Flows
    Adapter -.->|uses| Iframe
    Iframe -->|"POST /token (hidden)"| TokenEP
    Adapter -.->|request entitlements| EntEP
    EntEP -.->|permissions/policies| Adapter

    %% Test Connections
    PlayW --> TA_AppTS
    TA_AppTS --> TA_Index
    TA_Index --> TA_Silent

    %% Misc
    Doc --> App
    CI --> Adapter

    %% Click Events
    click Adapter "https://github.com/keycloak/keycloak-js/blob/main/lib/keycloak.js"
    click AuthZ "https://github.com/keycloak/keycloak-js/blob/main/lib/keycloak-authz.js"
    click TA_AppTS "https://github.com/keycloak/keycloak-js/blob/main/test/app/app.ts"
    click TA_Index "https://github.com/keycloak/keycloak-js/blob/main/test/app/public/index.html"
    click TA_Silent "https://github.com/keycloak/keycloak-js/blob/main/test/app/public/silent-check-sso.html"
    click PlayW "https://github.com/keycloak/keycloak-js/blob/main/test/playwright.config.ts"
    click Doc "https://github.com/keycloak/keycloak-js/blob/main/docs/guides/securing-apps/javascript-adapter.adoc"
    click CI "https://github.com/keycloak/keycloak-js/blob/main/.github/workflows/main.yml"

    %% Styles
    classDef browser fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef storage fill:#DFFFD0,stroke:#228B22,color:#228B22
    classDef server fill:#FFE0B2,stroke:#d2691e,color:#d2691e
    classDef test fill:#E8E8E8,stroke:#666,color:#333
    classDef doc fill:#F0E0FF,stroke:#800080,color:#800080
    classDef ci fill:#FFF0F0,stroke:#FF4500,color:#FF4500
```
