What Is a Client in Keycloak?
The complete beginner-to-production guide to Keycloak Clients — the building block that lets every app, API, and service plug into a single login system.
Imagine a large university campus that issues a single student ID card. That one card lets you into the library, the gym, the dining hall, and the computer labs — each building doesn’t run its own separate ID system; instead, every building simply trusts the campus card office and asks it, “is this card valid, and what is this student allowed to do here?” In the world of software, Keycloak plays the role of that campus card office — a dedicated identity server that handles logins for many different applications at once, so no individual app has to build its own login system from scratch. But before any application can ask Keycloak “is this user real?”, that application first has to register itself with Keycloak. That registration record — the thing that represents “this specific application” inside Keycloak — is called a Client.
This guide explains exactly what a Client is, why it exists, how it works internally, the different types of Clients you’ll encounter, and the mistakes that most commonly trip up teams adopting Keycloak for the first time. No prior identity or security background is assumed — every term is explained the moment it appears.
1Core Concepts
What Is Keycloak?
Keycloak is a free, open-source Identity and Access Management (IAM) system, originally built by Red Hat. Its job is to centralize two things that every application needs: confirming who a user is (authentication) and issuing proof of that identity (in the form of digital tokens) that other applications can trust. Instead of every website building its own username/password database, password-reset flow, and two-factor authentication system, they all point to one Keycloak server and let it do the heavy lifting.
What Is a Realm?
Before defining a Client, you need one more concept: a Realm. A Realm is an isolated space inside Keycloak — its own separate universe of users, roles, and settings. A company might have one Realm for its internal employee tools and a completely separate Realm for its customer-facing mobile app, so that employee accounts and customer accounts never mix, even though both run on the same Keycloak server.
What, Exactly, Is a Client?
A Client is a registered entry inside a Realm that represents one specific application, website, mobile app, or backend service that wants to use Keycloak for login and token issuance. Every single application that talks to Keycloak — whether it’s a React web app, an iOS app, or a backend microservice — must be registered as its own Client before Keycloak will trust its login requests.
A “Client” in Keycloak’s terminology is not the end user’s device or browser — it’s the application itself. The confusing part for beginners: the person sitting at the keyboard is the “user,” and the app they’re using (the website, the mobile app) is the “client.” Keycloak juggles both concepts, and mixing them up is the single most common beginner mistake.
Think of Keycloak as a hotel’s central key-card system. Each hotel building on the property — the main tower, the spa, the parking garage — has to be registered with that central system before it can accept the guest’s key card at its own doors. Each building is a “Client”: it’s a known, trusted entity that the central system has agreed to issue access decisions to. The guest (the “user”) is a completely separate concept from the buildings (the “clients”) that check the guest’s card.
Why Clients Exist
Without the concept of a Client, Keycloak would have no way to know which application is asking for a login, what that application is allowed to request, or where it’s safe to send the user back to after login. Registering a Client lets an administrator control exactly which applications can use the Realm, what data they can request about the user, and where tokens are allowed to be delivered — closing off a huge category of impersonation attacks where a malicious website pretends to be a trusted app.
2Architecture & Components
graph TD
KC["Keycloak Server
(Identity Provider)"]
KC --> R1["Realm: 'employees'"]
KC --> R2["Realm: 'customers'"]
R1 --> C1["Client: internal-hr-portal"]
R1 --> C2["Client: internal-payroll-api"]
R2 --> C3["Client: mobile-shopping-app"]
R2 --> C4["Client: public-website"]
C1 --> U1["Users
(employees who log in)"]
C3 --> U2["Users
(customers who log in)"]
C1 --> Roles1["Client Roles
(e.g. hr-admin, hr-viewer)"]
The Key Pieces Around a Client
Client ID
A unique text name identifying the application, like “mobile-shopping-app” — this is what the application sends to Keycloak to say “it’s me.”
Client Secret
A private password known only to the application and Keycloak, used by confidential (backend) clients to prove their identity when requesting tokens.
Redirect URIs
An allow-list of URLs that Keycloak is permitted to send the user back to after a successful login — a critical security boundary covered in Chapter 7.
Protocol Choice
Most modern Clients use OpenID Connect (built on OAuth2); older enterprise systems sometimes use SAML instead. Both are supported.
Client Roles
Fine-grained permissions defined specifically for that one application — separate from Realm-wide roles shared across all Clients.
Client Scopes
Reusable bundles of claims (pieces of user information) that a Client can request be included in its tokens, like email or group membership.
3Client Types
Confidential Clients
A confidential client is a Client that can safely keep a secret — typically a backend server or a traditional web application where the code runs on a server you control, never exposed to the end user’s browser. Confidential clients authenticate themselves to Keycloak using a Client Secret (or a certificate), proving “I really am the payroll-api backend, here’s my password.”
Public Clients
A public client is a Client that cannot safely keep a secret — a single-page JavaScript app, or a mobile app, where anyone could inspect the app’s code and extract any embedded secret. Public clients don’t use a Client Secret at all; instead, they rely on a technique called PKCE (Proof Key for Code Exchange), which we’ll unpack in Chapter 7, to stay secure without needing a hidden password.
Bearer-Only Clients
A bearer-only client never initiates a login itself — it’s typically a backend API that only ever receives tokens that some other application already obtained, and its only job is to validate that an incoming token is genuine before returning data.
| Client Type | Example | Keeps a Secret? |
|---|---|---|
| Confidential | Backend web server, internal admin portal | Yes — Client Secret or certificate |
| Public | React/Angular SPA, iOS/Android app | No — uses PKCE instead |
| Bearer-only | A protected REST API | Not applicable — never logs users in |
A frequent beginner mistake is configuring a single-page JavaScript application as a “confidential” client and embedding the Client Secret directly in the front-end code. Since anyone can open browser developer tools and read that secret, this defeats the entire purpose of a secret — public clients must always be configured as public, not confidential.
4Internal Working
User Clicks “Log In”
The application (the Client) redirects the user’s browser to Keycloak’s login page, including its own Client ID so Keycloak knows which application is asking.
Keycloak Checks the Client Configuration
Keycloak looks up that Client ID inside the Realm and verifies the request is legitimate — including checking that the redirect URL provided matches one on that Client’s approved list.
User Authenticates
Keycloak itself shows the login form (the application never sees the user’s password) — the user enters their username, password, and possibly a second factor like an authenticator app code.
Authorization Code Issued
On success, Keycloak redirects the browser back to the Client’s approved redirect URL, attaching a short-lived, single-use code — not a token yet, just a claim ticket.
Code Exchanged for Tokens
The Client’s backend (for confidential clients, using its secret; for public clients, using PKCE) sends that code directly to Keycloak and exchanges it for real tokens — this exchange happens server-to-server, never visible in the browser’s address bar.
Tokens Returned
Keycloak returns an ID Token (proving who the user is), an Access Token (used to call protected APIs), and often a Refresh Token (used to get new tokens later without asking the user to log in again).
Application Uses the Tokens
The Client stores these tokens and attaches the Access Token to every subsequent API call, letting downstream services (bearer-only clients) validate it without ever contacting the user directly.
5Data Flow & Lifecycle
Registration. An administrator creates the Client inside the Keycloak admin console (or automates it via Keycloak’s own API), choosing its Client ID, type (public/confidential/bearer-only), protocol, and redirect URIs.
Configuration. Client Scopes are attached, Client Roles are defined, and settings like token lifespan or “consent required” are tuned to the application’s needs.
Runtime Use. Every login and every token refresh references this Client configuration — the redirect URI check, the requested scopes, and the token contents are all shaped by what was configured here.
Rotation. Client Secrets should be periodically rotated (replaced with a new value) as a security hygiene practice, especially after a suspected leak, similar to rotating a database password.
Retirement. When an application is decommissioned, its Client entry should be disabled or deleted — a forgotten, unused Client with old permissions is a lingering attack surface.
graph LR
A["Client Registered
(Admin console or API)"] --> B["Configured
(Scopes, Roles, Redirect URIs)"]
B --> C["Used at Runtime
(Every login & token refresh)"]
C --> D{"Change Needed?"}
D -->|"Secret rotation"| E["Secret Regenerated
App updated with new value"]
D -->|"App decommissioned"| F["Client Disabled or Deleted"]
E --> C
Production Example: Multi-App Enterprise Rollout
A large enterprise migrating dozens of internal tools to single sign-on typically registers one Client per application inside a shared “employees” Realm. Each tool gets its own Client ID, its own narrowly scoped redirect URIs, and its own Client Roles — so a security team can disable access to one misbehaving internal tool without affecting any of the others, since each is an independently managed Client.
6Client Roles vs. Realm Roles
Realm Roles
A Realm Role is a permission label that exists at the whole-Realm level and can be assigned to a user regardless of which application they’re using — something broad like “employee” or “verified-customer.”
Client Roles
A Client Role belongs to one specific Client and only makes sense in the context of that one application — something narrow like “payroll-api:can-approve-payments,” which is meaningless to any other Client in the Realm.
A Realm Role is like being a “Registered Guest” at that hotel campus from Chapter 1 — it applies everywhere on the property. A Client Role is like being granted “Spa Manager” access — that title only means something inside the spa building; it’s meaningless at the parking garage.
Service Accounts
Confidential Clients can be granted their own service account — essentially a built-in “robot user” representing the application itself, not any human. This lets a backend service authenticate to other services on its own behalf, using the client credentials grant (no human user or password involved at all), which is common for machine-to-machine communication like a nightly batch job calling an internal API.
7Security
Redirect URI Validation
This is arguably the single most important security setting on any Client. If Keycloak allowed a login flow to redirect anywhere the requester specified, an attacker could trick a user into starting a real login at the real Keycloak server, then redirect the resulting authorization code to an attacker-controlled site instead of the real application — silently stealing the login. By restricting each Client to a strict, pre-approved list of redirect URIs, this entire attack class is closed off.
PKCE for Public Clients
Since public clients (mobile apps, SPAs) can’t hold a secret, PKCE solves a related problem: it ensures that only the exact application that started a login flow can complete it. The app generates a random secret value at the start of login, and must present the matching value again when exchanging the authorization code — so even if the code is intercepted in transit, an attacker without that original random value cannot redeem it for tokens.
Problem
Teams sometimes commit a Client Secret directly into source control, or bake it into a shared configuration file readable by every developer.
Why It Fails
Anyone with read access to that repository or file — including former employees whose access was never revoked, or an accidental public repository — can impersonate the application entirely, requesting tokens as if they were the trusted backend.
Correct Approach
Client Secrets belong in a dedicated secrets manager, injected into the running application only at deploy time, and rotated on a schedule — never stored alongside application source code.
Token Lifespan
Every Client (or the Realm as a whole) configures how long Access Tokens and Refresh Tokens remain valid. Shorter lifespans reduce the damage window if a token is ever stolen, but require more frequent refreshes — another example of the security-versus-convenience trade-off that runs throughout identity systems.
8Monitoring, Logging & Metrics
Login Failure Spikes
A sudden spike in failed logins for one specific Client can indicate credential-stuffing attacks targeting that particular application.
Admin Event Logging
Keycloak can log every change made to a Client’s configuration — who changed a redirect URI, when a secret was rotated — critical for compliance reviews.
Token Issuance Latency
Since every login and token refresh across every Client flows through the same Keycloak server, teams monitor issuance latency to catch capacity problems before they cause outages.
Unused Client Detection
Periodically reviewing which Clients haven’t been used in months helps identify decommissioned applications whose Client entry was never cleaned up.
Give each Client a clear, descriptive Client ID (like “billing-service-prod” rather than “client-1”) so that logs and audit trails are immediately readable months later, when the person investigating an incident may not be the person who originally configured it.
9Best Practices & Common Mistakes
Best Practices
- One Client per application, never sharing a single Client across unrelated apps
- Public clients for anything running in a browser or on a device you don’t control; confidential only for trusted backends
- Narrow, exact redirect URIs — never a wildcard covering an entire domain
- Rotate Client Secrets on a schedule and immediately after any suspected exposure
- Use Client Roles for permissions that only make sense within that one application
Common Mistakes
- Marking a JavaScript single-page app as “confidential” and embedding the secret in front-end code
- Using overly broad redirect URI wildcards for convenience during development, then forgetting to tighten them for production
- Reusing one Client across many unrelated applications, making it impossible to revoke access to just one of them
- Leaving unused, decommissioned Clients enabled indefinitely
- Granting a service account’s role assignments more broadly than the automation actually needs
10Real-World & Industry Examples
Enterprise Single Sign-On
Large organizations commonly run one Keycloak Realm for all internal staff tools — intranet portals, expense systems, internal wikis — each registered as its own confidential Client, letting employees log in once and move between tools without re-entering credentials, while security teams retain the ability to disable any single tool independently.
Customer-Facing Mobile Apps
A retail company’s mobile shopping app is typically registered as a public Client using PKCE, since the app runs on customers’ own devices where no secret can be safely hidden — a textbook example of choosing the public Client type correctly.
Machine-to-Machine Integrations
A nightly data-sync job that pulls records from a partner’s API overnight is often registered as a confidential Client with a service account enabled, authenticating via the client credentials grant — no human user is ever involved in that particular login flow.
API Gateway Protection
Backend microservices sitting behind an API gateway are frequently registered as bearer-only Clients — they never initiate a login themselves, but validate the Access Tokens forwarded to them by the gateway on every incoming request.
11Frequently Asked Questions
12Summary and Key Takeaways
Key Takeaways
- A Client represents one specific application registered inside a Keycloak Realm — never confuse it with the human “user” logging in.
- Choose the right Client type: confidential for trusted backends that can keep a secret, public (with PKCE) for browser apps and mobile apps, bearer-only for APIs that only validate tokens.
- Redirect URI validation is the single most important security setting — keep the list narrow and exact, never a broad wildcard.
- Client Roles scope permissions to one application; Realm Roles apply across the whole Realm — pick the right level for each permission.
- A service account with the client credentials grant lets applications authenticate to each other machine-to-machine, with no human user involved.
- Rotate Client Secrets on a schedule, store them in a secrets manager — never in source control — and disable or delete Clients for decommissioned applications.
- One Client per application is the golden rule — it keeps access reviewable, revocable, and auditable one application at a time.