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
  4. Use kcadm.sh: the Keycloak admin CLI

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

Registering an application — which kind of client it needs, and what the server does when you pick wrong:

  1. Your first realm, client, and user
  2. Keycloak client types: public, confidential, bearer-only
  3. Keycloak audience: get the aud claim right — the claim that decides which APIs will accept the token
  4. Validating Keycloak tokens in any backend
  5. Keycloak service accounts and the client credentials grant — when the client is the caller and there is no user at all

Protocol mappers covers every other claim the same objects emit. Client scopes build on them too. (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. Keycloak protocol mappers: a complete field guide — how any of that reaches the token
  3. Spring Boot Keycloak authentication
  4. Keycloak fine-grained admin permissions V2

Client scopes and fine-grained authorization build on the same objects. (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 protocol mappers: a complete field guide — how a claim gets into a token in the first place
  6. 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
  4. What personal data Keycloak stores, and how to erase it

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

What each tenant model puts in the token is protocol mappers. 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
  3. Use kcadm.sh: the Keycloak admin CLI — how to grant that scoped role, and everything else, from a script

Realm keys and auditing build on the same track. (Coming soon.)

Authorizing AI agents and MCP servers — the tokens an agent presents, and what your server has to check before trusting one:

  1. Get a Keycloak token and read every claim
  2. Validating Keycloak tokens in any backend
  3. Secure an MCP server with Keycloak

Token exchange and agent delegation build on the same audience rules. (Coming soon.)

Extending Keycloak with your own code — when the configuration runs out, a provider jar is the next step:

  1. Run Keycloak locally in 5 minutes
  2. Build a custom Keycloak authentication flow — how far you get without writing any code
  3. Your first Keycloak SPI: build, package, deploy

Custom authenticators, event listeners, user storage and REST endpoints all build on that last one. (Coming soon.)

Branding the pages your users actually see — the login screen is the one Keycloak page every user looks at:

  1. Your first realm, client, and user
  2. Build a custom Keycloak login theme — colours, wording and a logo, without forking an upstream template
  3. Your first Keycloak SPI: build, package, deploy — the same providers/ directory, for behaviour rather than appearance

Email templates and the account console build on the same theme system. (Coming soon.)

Getting your data back out — what an export actually contains, and proving you could leave:

  1. Export a Keycloak realm, users, and credentials
  2. What personal data Keycloak stores, and how to erase it
  3. Use kcadm.sh: the Keycloak admin CLI

Event retention and realm key management build on the same track. (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.