Keycloak Core Concepts

Table of Contents

1. Realm
2. User
3. Client
4. Client Types
5. Roles
6. Groups
7. Identity Providers
8. Access Token, Refresh Token, ID Token
9. OAuth 2.0 and OpenID Connect
10. Beginner Pitfalls

---

These concepts are worth understanding before opening the Admin Console in Part 3 — every screen in Keycloak is just a UI over these ideas.

1. Realm

A realm is an isolated space that manages a set of users, clients, roles, and sessions. Realms don't share data with each other — a user in one realm is completely invisible to another.

• Realm vs application: a realm is not "one app" — it's closer to a tenant. One realm can back several applications (a frontend, a backend API, a mobile app) that all share the same users and login.
• Realm isolation: this is what makes Keycloak safe to use for multiple projects on the same server — a bug or breach in one realm's configuration can't leak into another's.

2. User

A user is an account inside a realm. The fields that matter for this crash course:

• Username — how the user identifies themselves at login
• Email — often used for verification/reset flows (not configured in this crash course)
• Password — stored and hashed by Keycloak, never by your app
• Roles — what the user is allowed to do (see §5)

3. Client

A client represents an application that wants to authenticate users through the realm — your frontend, your backend API, a mobile app. Each one is registered in Keycloak as its own client.

• Why an application needs a client: Keycloak needs to know who's asking to authenticate a user, so it can apply the right settings (redirect URIs, token lifetimes, allowed flows) and issue tokens scoped to that application.
• Client ID: the unique identifier for that application inside the realm — it shows up inside issued tokens (the azp / aud claims — see Part 6).

4. Client Types

A public client (like a React SPA) can't safely store a client secret — anyone can open dev tools and read it. A confidential client runs somewhere only your team controls, so it can hold a secret and use it to authenticate itself to Keycloak.

5. Roles

Roles are what turn "this user is logged in" into "this user is allowed to do X." Keycloak has two scopes of role:

• Realm roles — apply across the whole realm (e.g. admin, user). This is what this crash course uses.
• Client roles — scoped to a single client, for when different applications need their own independent permission sets.

6. Groups

A group is a named collection of users that can have roles assigned to it — add a user to the group and they inherit every role the group has, instead of assigning roles one by one. Useful at scale; not needed for a realm with two test users, so this crash course doesn't configure one.

7. Identity Providers

Keycloak can also delegate authentication to an external identity source instead of (or alongside) its own login form — this is a federated identity provider:

• Google / GitHub — "Login with Google" style social login
• LDAP — sync against an existing corporate directory

Configuring one is straightforward once a realm exists, but it's a separate topic — see Part 8 for what this crash course deliberately leaves out.

8. Access Token, Refresh Token, ID Token

Keycloak issues three related but distinct tokens after a successful login:

All three are covered in depth once we have a real one to decode, in Part 6.

9. OAuth 2.0 and OpenID Connect

Note: OAuth 2.0 is primarily about authorization — it defines how an application gets a token that grants access to a resource. OpenID Connect (OIDC) is a thin identity layer built on top of OAuth 2.0 that adds authentication — the ID Token, and a standard way to ask "who is this user?"

Keycloak implements OIDC (and SAML, unused in this crash course), which is why it can hand out all three token types above in one login — OAuth 2.0's access/refresh tokens, plus OIDC's ID token.

10. Beginner Pitfalls

• Confusing realm with client. A realm is the whole tenant (users, roles, all clients); a client is one application inside it. You'll create one realm and one client in Part 3–Part 4.
• Assuming access tokens and ID tokens are interchangeable. An access token authorizes API calls; an ID token describes the user. Sending an ID token to an API as a bearer token is a common mistake — the API should validate an access token.
• Treating public and confidential as a formality. The distinction is a real security boundary — a client secret checked into frontend JavaScript is a leaked secret, not a protected one.