https://www.keycloak.org/documentation
https://www.keycloak.org/docs/latest/server_admin/
https://www.keycloak.org/server/configuration-production
https://www.keycloak.org/server/reverseproxy
https://www.keycloak.org/server/hostname
https://www.keycloak.org/server/containers
https://www.keycloak.org/operator/
https://www.keycloak.org/server/all-config

Keycloak can be:
    OIDC / OAuth2 authorization server
    SAML identity provider
    identity broker for upstream IdP
    user federation gateway for LDAP / AD
    central place for realm / client / role / group / session policy

Keycloak is not:
    LDAP server
    Active Directory replacement
    HR master data system
    full-featured IGA / identity governance suite
    WAF / API gateway
    replacement for application authorization design
    universal SCIM provisioning platform out of the box

Authentication:
    who is the user
    login flow, MFA, passwordless, federation

Application SSO:
    OIDC or SAML integration
    session, token, logout, redirect URI

Provisioning:
    where users and groups come from
    LDAP / AD federation, import, JIT, custom sync, lifecycle offboarding

Authorization:
    app roles, groups, claims, resource permissions
    usually still needs local app-side authorization model

employees / service admins
    -> corporate entry point
        -> Keycloak realm
            -> identity source:
                external LDAP / AD user federation
                upstream OIDC / SAML IdP
                local emergency admin users
            -> policies:
                MFA
                password policy
                brute force protection
                token/session lifetime
            -> applications:
                internal web apps through OIDC
                legacy enterprise apps through SAML
                APIs through OAuth2 access token
                Grafana / GitLab / Argo CD / Jenkins / custom apps

production baseline:
    Keycloak 运行多个 replicas
    external PostgreSQL database
    external LDAP / AD if enterprise directory federation is required
    stable hostname, HTTPS, correct proxy headers
    no embedded dev database
    no start-dev in production
    realm config managed as code where possible
    secrets stored in Vault / K8S Secret / cloud secret manager
    logs, metrics, health checks enabled
    tested backup / restore / upgrade / rollback

Internet / office network
    -> WAF / ALB / Ingress / reverse proxy
        -> Keycloak HTTPS endpoint
            -> PostgreSQL
            -> LDAP / AD
            -> upstream IdP metadata / JWKS endpoint

browser to Keycloak:
    HTTPS required
    hostname fixed
    cookies secure

proxy to Keycloak:
    forward headers only from trusted proxy
    do not expose internal admin endpoint publicly if split is possible

Keycloak to database:
    TLS preferred
    DB credential is secret
    backup and PITR owned by platform team

Keycloak to LDAP / AD:
    LDAPS or StartTLS
    bind user least privilege
    group search carefully scoped

LDAP / Active Directory:
    stores users, groups, passwords, directory attributes
    remains the enterprise directory source

Keycloak:
    connects to LDAP / AD through User Federation
    validates login against LDAP / AD when configured
    maps LDAP users / groups / attributes into Keycloak model
    issues OIDC tokens or SAML assertions to applications

Active Directory / LDAP
    -> Keycloak User Federation
        -> OIDC / SAML
            -> internal apps / SaaS / APIs

use Keycloak local users when:
    small internal app
    no existing enterprise directory
    emergency admin / break-glass account

use LDAP / AD federation when:
    company already has employee directory
    offboarding must happen from central directory
    group membership comes from AD / LDAP
    password policy is owned by directory team

recommended:
    dev realm
    test realm
    prod realm

avoid:
    one realm per application
    one realm per team without governance
    mixing test users and prod users in same realm

realm baseline:
    display name and email templates configured
    brute force protection enabled
    password policy enabled
    MFA required for privileged groups
    SMTP configured for required actions and reset flows
    user profile / required attributes defined
    login theme and error page tested
    event logging enabled

client baseline:
    use confidential client for server-side web app
    use public client with PKCE for SPA/mobile
    disable implicit flow unless legacy hard requirement exists
    use exact redirect URIs, not broad wildcard
    keep web origins narrow
    rotate client secret
    add only required protocol mappers
    token audience should match the target API

client_id:
    order-web

access type:
    confidential

standard flow:
    enabled

valid redirect URIs:
    https://order.example.com/oauth2/callback

web origins:
    https://order.example.com

recommended mappers:
    email
    preferred_username
    groups
    client roles for order-api

LDAP / AD federation:
    use read-only first unless write-back is explicitly required
    use LDAPS / StartTLS
    bind DN uses least privilege
    search base is scoped to employees / groups only
    import users only when needed
    sync schedule is documented
    group mapper tested with nested group behavior
    offboarding test is mandatory

identity brokering:
    define upstream IdP per enterprise source
    pin metadata / endpoints where possible
    validate signature and issuer
    map email / username / groups consistently
    decide first-login flow:
        auto-link trusted domains
        require review for unknown domain
        block duplicate email takeover

admin:
    do not use shared admin account
    create named admin users
    require MFA for admins
    split realm-admin from platform-admin
    keep emergency break-glass user with strong controls

network:
    expose only required frontend hostname
    protect admin console by network policy / VPN / separate hostname if possible
    trust proxy headers only from controlled proxy
    do not run plain HTTP on public edge

tokens:
    short access token lifetime
    refresh token lifetime aligned with company session policy
    offline token only for approved integrations
    rotate signing keys with rollout plan
    validate issuer, audience, expiry in every app/API

secrets:
    client secrets in secret manager
    DB password in secret manager
    LDAP bind password in secret manager
    never commit realm export with real secrets

availability:
    run multiple Keycloak replicas
    database must be HA
    cache / clustering behavior tested under rolling restart
    readiness probe prevents broken nodes from receiving traffic
    blue/green or canary upgrade for major changes

backup:
    PostgreSQL backup is the real backup
    realm export is useful for config review and migration, not enough alone
    test restore into isolated environment
    keep signing keys and secrets in recovery plan

upgrade:
    read release notes before version jump
    test realm import/export
    test login, refresh token, logout, SAML, LDAP sync
    keep DB snapshot before upgrade

login failure:
    check Keycloak events
    check reverse proxy headers and hostname
    check redirect URI mismatch
    check IdP metadata / certificate / JWKS
    check LDAP connectivity and bind auth

token rejected by app:
    check issuer
    check audience
    check clock skew
    check signing key rotation
    check mapper output

admin console unavailable:
    check pod/container status
    check database connection
    check proxy route
    check health endpoint
    check recent config or theme deployment

must watch:
    HTTP 5xx / 4xx rate
    login failure rate
    request latency p95/p99
    JVM memory and GC
    DB connection pool usage
    PostgreSQL latency / locks / connections
    LDAP / upstream IdP connectivity
    pod restarts / OOMKilled
    certificate expiry

traffic:
    requests by route / status
    login success/failure
    token endpoint rate

runtime:
    CPU / memory
    JVM heap / non-heap
    GC pause
    thread count

dependency:
    DB connections
    DB latency
    LDAP latency/error
    upstream IdP error

business:
    active sessions
    new users
    admin actions

docker run --name keycloak-demo --rm \
  -p 8080:8080 \
  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
  -e KC_BOOTSTRAP_ADMIN_PASSWORD=change_me_now \
  quay.io/keycloak/keycloak:latest \
  start-dev

http://localhost:8080/

curl -fsS https://sso.example.com/realms/master/.well-known/openid-configuration
curl -fsS https://sso.example.com/health/ready
curl -fsS https://sso.example.com/metrics

issuer:
    https://sso.example.com/realms/<realm>

authorization_endpoint:
    https://sso.example.com/realms/<realm>/protocol/openid-connect/auth

jwks_uri:
    https://sso.example.com/realms/<realm>/protocol/openid-connect/certs

phase 1:
    deploy dev realm
    integrate one low-risk internal app
    verify login / logout / token refresh

phase 2:
    connect LDAP / AD or upstream IdP
    map groups and claims
    enable admin MFA
    define client onboarding template

phase 3:
    migrate critical internal apps
    create monitoring dashboard and alerts
    test backup / restore
    test IdP outage and DB failover

phase 4:
    make Keycloak the default internal app SSO entry
    remove local app passwords where possible
    run quarterly access review with app owners

security ready:
    HTTPS and hostname are correct
    admin MFA enforced
    client secrets managed outside Git
    redirect URIs reviewed
    token validation standard documented for apps

operation ready:
    HA deployment tested
    DB backup restore tested
    monitoring and alerts enabled
    upgrade rehearsal done
    incident runbook exists

governance ready:
    owner for realm changes
    owner for client onboarding
    owner for LDAP / IdP mapping
    offboarding test completed
    break-glass process approved