Skip to content
Tutorials Center
My learning

Topics

Lesson 14 of 37 ยท OAuth2 and OIDC Flows

OAuth 2.0 and OpenID Connect Grants in Keycloak: Overview

Compare OAuth 2.0 and OpenID Connect grant types in Keycloak: authorization code with PKCE, client credentials, refresh token, device code and legacy grants, and choose the right one.

OAuth 2.0 is a framework for letting one piece of software get limited access on behalf of someone (or on its own behalf). It defines several grant types, each a recipe for getting tokens in a particular situation. OpenID Connect (OIDC) adds login and identity on top. Choosing the correct grant is the most important integration decision, and Keycloak supports all the modern ones. This lesson is the decision guide for the whole chapter.

The vocabulary again

  • Resource owner: the user.
  • Client: the application asking for tokens.
  • Authorization server: Keycloak. It has an authorization endpoint (browser-facing: login and consent) and a token endpoint (back-channel: exchanges credentials or codes for tokens).
  • Resource server: the API that accepts access tokens.
  • Scope: a named permission the client asks for (openid, email, invoices:read).
  • Redirect URI: where Keycloak sends the browser back after login.

The grants

Grant Who is it for? Short description
Authorization code + PKCE Web apps, SPAs, mobile and desktop apps (users involved) The browser is redirected to Keycloak, then back with a one-time code; the app exchanges the code for tokens. The default choice.
Client credentials Machine-to-machine, no user The client authenticates with its own credentials and gets a token for itself (a service account).
Refresh token Anything that already has a refresh token Exchange a refresh token for a new access token without a new login.
Device authorization TVs, CLIs, devices without a browser or keyboard The device shows a code; the user approves on another device.
Token exchange Services acting for a user, impersonation, swapping tokens between audiences Trade one token for another (Standard Token Exchange in current Keycloak).
CIBA (back-channel authentication) Authentication started on a different device The client asks Keycloak to ask the user on their phone.
Resource owner password (direct access grant) Legacy only Client collects username and password. Avoid.
Implicit Legacy only Tokens returned in the URL fragment. Do not use.

In OAuth 2.1 (the consolidation of best practices) PKCE is mandatory for the code flow, and the implicit and password grants are removed. In the client's Settings tab, Capability config offers each of these as a switch.

Decision guide

flowchart TD
  Q1{"Is a user present?"}
  Q1 -->|"No"| CC["Client credentials"]
  Q1 -->|"Yes"| Q2{"Can the app open a browser?"}
  Q2 -->|"Yes"| AC["Authorization code + PKCE"]
  Q2 -->|"No (TV, CLI, IoT)"| DV["Device authorization grant"]
  AC --> RT["Use refresh token to stay signed in"]

Start with "is a user present?".

OIDC on top of OAuth 2.0

When the scope includes openid, the code flow also returns an ID token and unlocks the userinfo endpoint. The three tokens:

  • ID token: for the client; tells it who the user is, when they logged in, and how.
  • Access token: for the API; says what the client may do.
  • Refresh token: for Keycloak; used to get new tokens.

Never send an ID token to an API, and never read the access token in the client as if it were meant for it. Each token has an audience.

Endpoints you will call

Endpoint Path under /realms/{realm}/protocol/openid-connect/
Authorization auth
Token token
User info userinfo
JWKS (public keys) certs
Logout (end session) logout
Introspection token/introspect
Revocation revoke
Device authorization auth/device

Choosing a client type

  • Public client (SPA, mobile, desktop CLI): no secret; PKCE protects the code; restrict redirect URIs strictly.
  • Confidential client (server-side web app, backend job): holds a secret or a signed JWT (private_key_jwt); still use PKCE for the code flow, as recommended practice.
  • Backend-for-frontend (BFF): for a SPA, a small server component runs the code flow and keeps tokens off the browser, handing the SPA only a session cookie. It is increasingly the recommended pattern for sensitive apps.

Recognizing a grant on the wire (stand-in)

You can identify the grant from the token request's grant_type. This runnable stand-in classifies requests, checks the minimum parameters for each and warns about legacy grants. It is a learning aid, not Keycloak's implementation.

Node.js Stand-in: classify token requests

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

A grant chooser (stand-in)

Encode the decision tree as code to practice it. Feed in scenarios and read the recommendation.

Node.js Stand-in: choose the right grant

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Common mistakes

  • Using the password grant "because it is easy" and then having to migrate later.
  • Putting a client secret inside a mobile app or a JavaScript bundle. Anyone can extract it.
  • Wildcard redirect URIs such as https://app.example.com/*. Use exact URIs.
  • Sending the ID token to an API instead of the access token.
  • Requesting scopes the app does not need.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which grant should a single-page application use for user login?

    Authorization code with PKCE is the recommended flow for browser and mobile apps.
  2. 2. A nightly job calls your API with no user involved. Which grant fits?

    Client credentials authenticates the client itself and returns an access token for its service account.
  3. 3. What does adding the openid scope enable?

    openid turns an OAuth 2.0 request into an OpenID Connect authentication request.
  4. 4. Which two grants does OAuth 2.1 drop?

    Implicit and password grants have known weaknesses and are removed in OAuth 2.1.

Summary

  • A grant is a recipe for obtaining tokens; pick by whether a user is present and whether a browser exists.
  • Authorization code with PKCE is the default; client credentials is for machines; device grant for browserless devices.
  • Avoid the implicit and password grants.
  • OIDC adds the ID token and userinfo via the openid scope; each token has its own audience.
  • Public clients cannot keep secrets; use exact redirect URIs and PKCE.

Next: Authorization Code Flow with PKCE