Learn Keycloak - OAuth 2.0 Fundamentals

#Introduction

Episode 3 dissected the Keycloak architecture. Episode 4 starts diving into the protocol you'll use most often: OAuth 2.0. You'll understand the four roles always involved, the endpoint and token components, all the grant types and when to use them, and the security considerations you must keep in mind. This material is the foundation for episode 5, which breaks down the Authorization Code flow step by step.

#Roles in OAuth 2.0

OAuth 2.0 defines four cooperating roles:

It's important to understand the boundaries of these roles. The resource owner is almost always a human user. The client can be a web app, a mobile app, or even a backend service acting on its own behalf. The authorization server in our context is Keycloak. The resource server is the API that stores the data you want to access.

#OAuth 2.0 Components

OAuth 2.0 defines several components that serve as the contact points of the flow:

• Authorization endpoint — where the user is authenticated and approves (consents to) access.
• Token endpoint — where the client exchanges a code or credentials for tokens. In Keycloak it's located at /realms/{realm}/protocol/openid-connect/token.
• Scopes — the scope of permission requested by the client, such as openid, profile, and email.
• Access token — temporary credentials for accessing a resource.
• Refresh token — credentials for obtaining a new access token after it expires.

Here's an example response from the token endpoint:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJidWRpIiwiYXVkIjoicG9ydGFsLWFwcCJ9...",
  "expires_in": 300,
  "refresh_expires_in": 1800,
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJidWRpIiwiZXhwIjoyMzQ1Njc4OTB9...",
  "token_type": "Bearer"
}

Notice expires_in: access tokens are short-lived (300 seconds in the example), while refresh_token has a longer lifetime. This design is intentional — short-lived tokens minimize the damage if they leak.

#Grant Types: How to Get Tokens

OAuth 2.0 defines several ways (grant types) to obtain a token, each suited to a context:

• Authorization Code — the safest for web apps: a short-lived code is exchanged for a token on the server, the password never touches the browser. Episode 5 breaks it down in full.
• Implicit — sends the token directly in the redirect URL; insecure and deprecated.
• Password (ROPC) — username and password sent straight to the token endpoint; only for trusted clients and not recommended.
• Client Credentials — for service-to-service communication without a user.
• Device Code — the user enters a code on another device that has a browser.

#Choosing a Grant Type

Four considerations narrow down the choice:

• Is there a user? — if not, use Client Credentials; if yes, use an interactive grant type.
• Can the client store a secret? — if not (SPA, mobile), use Authorization Code with PKCE or Device Code.
• What is the application shape? — a web app with a backend uses Authorization Code; a device without a browser uses Device Code.
• How trusted is the client? — ROPC is only for trusted clients and still not recommended.

A rule of thumb: when in doubt, choose Authorization Code + PKCE. It's the safest combination for almost any case with a user.

#OAuth 2.0 in Keycloak

Keycloak maps OAuth 2.0 roles to real configuration:

• Authorization server — Keycloak itself, accessed via the authorization and token endpoints.
• Client — represented as a client in the admin console, with an access type of public or confidential.
• Scopes — managed via client scopes; there are built-in scopes like openid, profile, and email.
• Access token — issued as a JWT that can be inspected at the token introspection endpoint.

These are the points you'll visit often in the admin console when implementing grant types in episode 5 and beyond.

#Security Considerations

Four security practices that must be part of every OAuth 2.0 implementation:

• State parameter — a random value carried when starting the flow and verified on return; protects against CSRF.
• PKCE (Proof Key for Code Exchange) — a cryptographic challenge that makes a stolen code useless to others; mandatory for SPA and mobile, recommended for all.
• Token binding — binding a token to a specific context, e.g. the TLS connection, to make token theft harder.
• Token storage best practices — store access tokens in memory and refresh tokens in secure storage; never in localStorage exposed to JavaScript.

#The Core Principle

A sentence that summarizes all the considerations above: treat tokens like physical keys. Keys aren't left out in the open, aren't given to strangers, and are replaced if ever lost. State and PKCE ensure tokens reach only the right hands, while secure storage keeps tokens in place.

#Closing

Episode 4 laid the OAuth 2.0 foundation: the four roles, the authorization and token endpoint components, all the grant types, and security considerations. You now know where Keycloak's token endpoint lives and the shape of token responses you'll encounter often.

Key takeaways:

• OAuth 2.0 is an authorization framework — who has permission to access what resource.
• The four roles are a must-understand — resource owner, client, authorization server, resource server.
• Choose the grant type by context — no single grant type fits every case.
• State and PKCE aren't optional — they're the first line of defense.

In the next episode (episode 5), you'll dissect the Authorization Code flow in detail — from the authorization request, user login, the code, token exchange, to PKCE.