Keycloak Clients Explained: OIDC, SAML, URLs, and Client Settings

A Keycloak client is the registration of an application or service that uses Keycloak for authentication, SSO, tokens, or SAML assertions. For example:

• Web application
• Browser SPA
• API or resource server
• Backend or machine client

Each can have its own client configuration inside a Keycloak realm.

The client tells Keycloak how that application is allowed to interact with it — for example:

• Which redirect URIs are trusted
• Whether the application can authenticate itself
• Which login flows it can use

Common misconfiguration effects:

• Bad redirect URIs can stop the login flow
• Incorrect Web Origins can cause browser CORS failures
• Disabled capability settings can prevent the client from using the required OAuth/OIDC flow

This guide walks through the 26.7.3 Admin Console in the golinuxcloud realm. OIDC grant details and SAML metadata belong in dedicated protocol guides; here you learn what the client record means and which settings matter first.

What a Keycloak client is

A Keycloak client represents an application or service that talks to Keycloak for identity services. The client record tells Keycloak:

• Which protocol to use
• Which redirect URLs are trusted
• Whether the app can authenticate as itself

Typical client shapes:

• Web application — server-side app that holds a client secret and exchanges an authorization code for tokens
• Single-page application (SPA) — JavaScript in the browser; usually a public client that uses Authorization Code Flow with PKCE
• API or resource server — accepts access tokens from callers and validates whether they grant access to the API; it may also have its own Keycloak client registration when it needs client-specific roles, audience, or other configuration
• Backend or machine client — authenticates itself to Keycloak and obtains an access token, for example with the Client Credentials grant

Keycloak does not run your application. The client entry is configuration Keycloak uses when:

• Handling login requests
• Issuing tokens or SAML assertions
• Applying client-specific settings such as redirects, roles, and scopes

User accounts still live under Users; permissions still flow through roles described in Keycloak realm roles vs client roles.

Why does Keycloak need clients?

Keycloak may serve many applications in one realm, but each application can differ in:

• Callback URLs
• Authentication methods
• Scopes and roles
• Supported flows

A separate client registration lets Keycloak keep those settings isolated for each application.

Without per-client configuration, one set of redirect URIs, secrets, and capability flags would apply to every app in the realm — which is neither secure nor practical when a storefront, an API, and a reporting portal all integrate differently.

Realm vs client

A Keycloak realm is the isolation boundary. Each client belongs to one realm and uses that realm's users, identity providers, signing keys, sessions, and other realm-level configuration.

  ┌─────────────────────────────────────────────┐
  │ Realm: golinuxcloud                         │
  │   Users, groups, roles, IdPs, token keys    │
  │                                             │
  │   ┌─────────────┐  ┌─────────────┐         │
  │   │ storefront- │  │ storefront- │  …      │
  │   │ web         │  │ spa         │         │
  │   └─────────────┘  └─────────────┘         │
  │      Clients can reuse the realm SSO session │
  └─────────────────────────────────────────────┘

Many clients can register in one realm:

• Users who authenticate through any OIDC client in that realm can often reuse the same SSO session for sibling clients, subject to client session and timeout settings
• Clients belong to one realm and normally authenticate against that realm's users and configuration
• Users and client configuration are not automatically shared between realms; cross-realm login requires an explicit integration such as identity brokering

OIDC vs SAML client

When you create a client, you pick a protocol. That choice drives which Admin Console fields matter and which integration guides apply later.

Keycloak access and ID tokens are JWTs in the normal OIDC configuration used in this guide.

Pick OIDC for new web and API work unless a vendor requires SAML. This guide references a SAML example client to show the protocol selector — full metadata, bindings, and attribute mappers belong in a SAML-focused guide.

Example clients used in this guide

This guide uses three existing example clients to show how different client configurations look:

• storefront-web — confidential OIDC client with redirect URIs and a client secret
• storefront-spa — public OIDC client for a browser SPA
• legacy-reports-saml — SAML protocol client placeholder

The same examples are also used below to explain the difference between clientId and Keycloak's internal client UUID.

  Realm: golinuxcloud
  ├── storefront-web        (OIDC, confidential, server-side web app)
  ├── storefront-spa      (OIDC, public, browser SPA)
  └── legacy-reports-saml (SAML SP placeholder)

Browse clients in Admin Console

Switch the realm selector to golinuxcloud, then open Clients. The list shows protocol, client id, and enabled state for every registration in the realm.

Each row is a client registration inside the realm — not a running application, pod, container, or systemd service.

Client ID and internal UUID

Keycloak has two different client identifiers that are easy to confuse:

They are not interchangeable:

• Your application configuration normally uses the clientId
• Admin REST operations that address /clients/{id} use Keycloak's internal UUID

Assuming ${TOKEN} contains an admin access token, query by clientId — the API search parameter is the protocol id, not the UUID:

curl -s \
  'http://127.0.0.1:8080/admin/realms/golinuxcloud/clients?clientId=storefront-web' \
  -H "Authorization: Bearer ${TOKEN}" | python3 -c 'import sys,json; c=json.load(sys.stdin)[0]; print("clientId:", c["clientId"]); print("id:", c["id"])'

Sample output:

clientId: storefront-web
id: f9e69b6a-f143-42ff-8c2f-f13bcfc8e7ba

From the API response:

• clientId is what you configure in the application
• id is what Keycloak uses in Admin API paths — copy it when a script updates client settings by UUID

Root URL, home URL, and redirect URIs

URL fields on Clients → client → Settings control where Keycloak sends the browser after login and which redirect targets are allowed.

Redirect URI matching is a security control:

• Keycloak rejects authorization responses to URIs that are not listed — that blocks token theft via open redirects
• Keycloak matches redirect URIs exactly, with limited wildcard support at the end of a pattern, specifically to prevent unsafe redirects

Practical rules:

• Prefer exact redirect URIs such as http://127.0.0.1:3000/callback when your application has a fixed callback path
• Keycloak supports a wildcard at the end of a URI pattern when multiple callback paths are genuinely required, but avoid broad patterns in production
• List every host and path your app uses in development and production, including both 127.0.0.1 and localhost when your team tests with both
• A mismatch in scheme, host, port, or path causes Keycloak to reject the redirect_uri

Open storefront-web → Settings to see the lab values:

storefront-web uses:

• Root URL http://127.0.0.1:3000
• Home URL /
• Valid redirect URI patterns http://127.0.0.1:3000/* and http://localhost:3000/*

That lets the same dev app work whether you browse via loopback or the localhost hostname.

Web origins

Web origins control which browser origins Keycloak allows for cross-origin requests (CORS). This matters when JavaScript running at one origin calls Keycloak at another origin.

Do not copy redirect URIs into web origins verbatim — the formats differ (path included on redirects vs origin without path for CORS).

Open storefront-spa → Settings to see the lab values:

• Valid redirect URIs on port 5173
• Web origins +
• Client authentication off

With Client authentication off, a browser SPA cannot safely store a client secret.

Client authentication

On Keycloak 26.x, Client authentication on the Settings tab replaces the older Access Type dropdown:

Confidential clients expose a Credentials tab where Keycloak stores:

• A generated client secret by default
• JWT or certificate authenticators when configured

Treat the secret like a password:

• Rotate it if leaked
• Never embed it in frontend code

Public versus confidential trade-offs, PKCE, and service-account patterns are covered in a dedicated public/confidential client guide; this page only maps the Admin Console toggle.

Client capability settings

Below authentication, capability toggles enable OAuth 2.0 / OIDC grant families. You do not need every flow on every client.

The lab storefront-web client enables Standard flow only. In the API record:

• directAccessGrantsEnabled is false
• serviceAccountsEnabled is false

Grant-by-grant configuration, PKCE, and token exchange belong in the OpenID Connect tutorial cluster, not on this vocabulary page.

Client credentials mechanisms

When Client authentication is ON, the client can authenticate itself to Keycloak using a configured credential. Common mechanisms include:

• Client secret — shared secret; default for many confidential clients
• Signed JWT — client proves possession of a private key

Keycloak supports additional client-authentication mechanisms as well; use those only when your application's integration requires them.

When Client authentication is enabled:

• These mechanisms are available on the Credentials tab

When Client authentication is off:

• Public clients do not have a reusable client credential because applications running in browsers or installed on user devices cannot safely keep one confidential

Pick the mechanism in the dedicated public/confidential guide when you move from lab to production.

Client scopes

Client scopes group protocol mappers and role scope mappings that influence the contents of tokens or assertions:

• Default and Optional — shared scopes linked to a client
• Dedicated — client-specific mappings for an OIDC client

The realm-level Client scopes page contains built-in scopes as well as any custom scopes you create:

For OIDC clients:

• Default scopes are applied automatically
• Optional scopes are applied when requested through the OIDC scope parameter

The dedicated Keycloak client scopes guide demonstrates the difference with before-and-after tokens.

Legacy Access Type vs current Admin Console

Older Keycloak tutorials and blog posts reference Access Type:

The current Admin Console exposes Client authentication for the normal public/confidential distinction. Keep these points in mind when reading older material:

• Existing imports and Admin REST representations can still contain fields such as publicClient and bearerOnly
• Do not translate old bearer-only examples into a modern public client mechanically
• If an older tutorial describes a client as confidential, the equivalent modern Admin Console concept is Client authentication ON
• For public, it is Client authentication OFF
• Treat old bearer-only configurations separately rather than converting them to a public client

Common client problems

Summary

A Keycloak client is the configuration that represents an application or service inside a realm:

• OIDC clients may be public or confidential
• SAML clients represent SAML service providers
• Each client can have its own redirect URIs, authentication settings, allowed flows, roles, and client scopes

For OIDC clients:

• Client authentication OFF represents a public client that cannot keep a secret
• Client authentication ON represents a confidential client that authenticates itself
• Redirect URIs control where Keycloak may return the browser
• Web Origins control cross-origin browser requests to Keycloak

When troubleshooting a client, first check:

• Realm and client ID
• Redirect URIs
• Client authentication setting
• Web Origins
• Enabled capability flows

Then move to protocol-specific token, role, or mapper troubleshooting if the client configuration is correct.

References

• Keycloak Server Administration Guide — Managing clients
• Keycloak Server Administration Guide — Client scopes
• OpenID Connect Core 1.0
• OAuth 2.0 RFC 6749