Skip to main content

Keycloak Tutorials

Task-oriented guides for open-source Keycloak. Every tutorial here runs on a plain quay.io/keycloak/keycloak container — nothing on this page requires a Phase Two account.

The official Keycloak documentation is thorough and we link to it constantly. What it is not is task-oriented: it is organized around the software's features and it tells you what each option does, rarely what to set it to, in what order, or what breaks when you get it wrong. These tutorials are the other half.

What each tutorial gives you​

  • A copy-pasteable start. A docker run that gets you a working Keycloak in 30 seconds.
  • Both ways to do it. The admin console clicks and the equivalent kcadm.sh, because one is how you learn it and the other is how you ship it.
  • A way to check it worked. A concrete verification step, not "you should now see…".
  • The failure modes. The three or four ways it actually goes wrong, and how to tell which one you hit.
  • A version. Every tutorial states the Keycloak version it was tested against.

Learning paths​

New to Keycloak — start here, in order:

  1. Run Keycloak locally in 5 minutes
  2. Your first realm, client, and user
  3. Get a Keycloak token and read every claim

Securing an application — get a token, then learn to trust it:

  1. Get a Keycloak token and read every claim
  2. Validating Keycloak tokens in any backend
  3. Spring Boot Keycloak authentication

More framework-by-framework guides are next. (Coming soon.)

Deciding who may do what — the four ways Keycloak models permissions, and what each one puts in the token:

  1. Keycloak roles, composite roles, and groups
  2. Spring Boot Keycloak authentication
  3. Keycloak fine-grained admin permissions V2

Client scopes, protocol mappers and fine-grained authorization build on the first one. (Coming soon.)

Adding a second factor, or dropping the password — turn MFA on for everyone, not just the people who opt in, then go passwordless:

  1. Set up TOTP multi-factor authentication
  2. Passkeys and WebAuthn in Keycloak
  3. Build a custom Keycloak authentication flow

Step-up authentication and magic links are next. (Coming soon.)

Working with tokens — what a JWT is, how to read one, and how to handle them safely:

  1. Get a Keycloak token and read every claim
  2. Decoding a JWT — header, payload, and signature
  3. JWT security best practices
  4. Benefits and drawbacks of JWTs
  5. Keycloak session and token timeouts, explained

Paste a token into our free JWT decoder while you read.

Storing data on a user — what Keycloak will and will not keep on an account, and why a custom attribute goes missing:

  1. Your first realm, client, and user
  2. Keycloak managed vs unmanaged attributes
  3. Get a Keycloak token and read every claim

Validators, progressive profiling and the registration form build on the second one. (Coming soon.)

Provisioning users from an identity provider — SSO gets people in; provisioning keeps the account list honest:

  1. SCIM explained: what it is and when you need it
  2. Keycloak SCIM API: enable it and connect a client
  3. Keycloak SCIM filtering, pagination, and search

Mapping attributes to SCIM schemas and extensions is next. (Coming soon.)

Automating the user lifecycle — joiners, movers and leavers without a script on a cron:

  1. Keycloak Workflows: what they are and your first one
  2. Automate user onboarding with a Keycloak workflow
  3. Automate Keycloak offboarding and deprovisioning

Inactivity policies build on the same engine. (Coming soon.)

Designing for multiple tenants — one customer per realm, per group, or per organization:

  1. Your first realm, client, and user
  2. Keycloak multi-tenancy: realms, groups, or organizations?
  3. Keycloak SCIM API: enable it and connect a client

Client scopes and fine-grained authorization build on the same track. (Coming soon.)

Delegating realm administration — give someone admin rights over part of a realm without giving them the realm:

  1. Your first realm, client, and user
  2. Keycloak fine-grained admin permissions V2

Realm keys, auditing and the kcadm cookbook build on that one. (Coming soon.)

Running Keycloak in production — sizing, backups, upgrades, observability. (Coming soon.)

A note on scope​

These tutorials cover Keycloak itself. Where a capability is not in core Keycloak — magic links, per-organization SCIM endpoints, multi-tenant organizations in older versions — we say so plainly and point at the open-source extension, rather than pretending the gap isn't there.

Something missing or wrong? The edit link on every page goes to the repository.