What Is Client Authentication?

Client Authentication is the process by which an application (a Keycloak Client) proves its own identity to Keycloak, separately and distinctly from proving the identity of any human user. It answers a completely different question than user login does: not “who is this person sitting at the keyboard?” but rather “is this application really the trusted, registered application it claims to be, or is it an impostor?”

Where This Fits in the Bigger Picture

Recall from earlier in this series that after a user successfully logs in at Keycloak’s Authorization Endpoint, the application receives a short-lived authorization code, not yet a usable token. The application’s backend must then exchange that code for real tokens at Keycloak’s Token Endpoint. It is precisely at this exchange step — this one specific, security-critical moment — that Client Authentication happens. Keycloak will not hand over tokens in response to that code unless the requesting application first proves its own identity using its configured method.

Why This Step Cannot Be Skipped for Confidential Clients

Without Client Authentication, anyone who intercepted or guessed an authorization code could walk up to the Token Endpoint, present that code, and receive fully valid tokens — no proof required that they were really the application the code was originally issued for. Requiring the application to also prove its own identity closes this gap for confidential Clients (recall from earlier in this series: applications like backend servers that can safely hold a secret). Public Clients, which cannot safely hold any secret at all, rely on a different mechanism entirely, covered fully in Chapter 9.

The Client Authenticator Concept

Inside Keycloak’s own terminology, the specific mechanism a Client uses to authenticate itself is configured as that Client’s Client Authenticator. Every confidential Client has exactly one Client Authenticator selected in its configuration, and this single setting determines everything covered in the rest of this guide: which credential the application must present, and how Keycloak verifies it.

A Question of Trust Direction

It helps to notice that trust flows in two separate directions across a full login. The end user trusts Keycloak’s login page enough to type a password into it. Keycloak, in turn, needs a reason to trust that the application redeeming a code afterward is legitimate — and that reason is exactly what a Client Authentication Method supplies. Without it, Keycloak would be handing out tokens based purely on possession of a code, with no way to confirm the party asking for them is who they claim to be, similar to a bank teller cashing a check without ever checking the identity of the person presenting it.

Not Every Client Needs This At All

It’s worth flagging early — and returning to in depth in Chapter 9 — that this entire guide applies specifically to confidential Clients. Public Clients, by definition, cannot hold a confidential credential at all, so the four methods explored here simply don’t apply to them; they rely on an entirely different mechanism instead. Keeping this distinction in mind from the outset prevents a common early confusion: assuming every application must pick one of these four methods, when in fact an entire category of applications is intentionally excluded from needing to.

How It Works

The application’s backend sends its Client ID alongside its Client Secret directly to the Token Endpoint, either as part of the request body or using standard HTTP Basic Authentication in the request headers. Keycloak compares the submitted secret against the value it has stored for that Client. A match proves the request genuinely originates from an entity that knows the secret — presumably the real application.

Why It’s the Default Choice

This method requires no cryptographic key management on the application’s side — no key pairs to generate, rotate, or store securely beyond the one secret value itself. For the vast majority of backend services with a reasonably mature secrets-management practice already in place, this remains a perfectly appropriate, industry-standard choice.

The Two Ways a Secret Can Be Transmitted

Keycloak accepts a Client Secret submitted in either of two standard ways, and it’s worth knowing both exist even though the practical difference between them is small. The first, HTTP Basic Authentication, packs the Client ID and secret together into a single encoded header value, following a long-standing web standard used across countless other systems. The second places the Client ID and secret as ordinary fields inside the request body itself, alongside the authorization code. Most Keycloak client libraries and adapters choose one of these automatically and consistently, so an individual developer rarely needs to choose manually — but recognizing both forms is useful when reading raw network traffic during troubleshooting.

What a Compromise of This Method Actually Costs

It’s worth being explicit about the failure mode here, since it motivates the more advanced methods covered next. If a Client Secret is captured — through a misconfigured log that accidentally records request bodies, a compromised server, or a careless commit to source control — the person holding it can request tokens as that application indefinitely, until the secret is rotated. There is no built-in limit on how many times a captured secret can be reused, which is precisely the gap the next two methods are designed to close.

What Is a JWT, Briefly?

A JWT (JSON Web Token) is a compact, digitally signed document — the same underlying format used for the ID Tokens and Access Tokens discussed earlier in this series. Here, the application itself constructs and signs one of these documents purely to prove its own identity; this specific JWT is called a client assertion.

How It Works

Instead of sending its raw Client Secret in the request, the application builds a small JWT containing standard claims (who it is, when the assertion expires, a unique identifier to prevent reuse) and signs that JWT using its Client Secret as a cryptographic key, via a signing algorithm called HMAC. The application sends this signed assertion to the Token Endpoint instead of the raw secret. Keycloak, which also knows the same shared secret, recomputes the signature itself and checks that it matches — confirming the assertion was genuinely produced by an entity holding that secret, without the secret ever having traveled across the network in this particular request.

Why Choose This Over the Simpler Method

Because the assertion includes an expiration and a unique identifier, a captured assertion cannot be replayed indefinitely — unlike a raw secret, which remains equally dangerous however many times it’s intercepted, a signed assertion has a short, deliberately narrow window of usefulness even if somehow captured in transit.

Asymmetric Keys, in Plain Terms

Unlike a shared secret (known identically by both sides), an asymmetric key pair consists of two mathematically related but distinct keys: a private key, which the application alone generates and keeps strictly to itself, never sharing it with Keycloak or anyone else, and a corresponding public key, which is freely shared with Keycloak (or published at a JWKS Endpoint) and can verify signatures made by the private key, but cannot itself be used to create new valid signatures.

How It Works

The application signs its client assertion JWT using its own private key instead of a shared secret. Keycloak, holding only the corresponding public key, verifies the signature. Critically, Keycloak never possesses anything capable of forging a new valid signature itself — even if Keycloak’s own database were somehow fully compromised, an attacker would gain only public keys, useless for impersonating the application.

Rotating Keys Without an Outage

Because the public key is what Keycloak actually stores, key rotation for this method can be handled gracefully: an application can publish a new public key alongside the still-valid old one for a short overlap window, switch to signing new assertions with the new private key, and only remove the old public key once every server has confirmed the switch. This overlap period, impossible with a single shared Client Secret (which has only one valid value at any given moment), is one of the quieter operational advantages of the asymmetric approach.

What Is Mutual TLS?

Ordinary secure web traffic uses TLS (Transport Layer Security) in one direction — the server proves its identity to the browser using a certificate, but the browser proves nothing back. Mutual TLS (often abbreviated mTLS) flips this into a two-way handshake: the client also presents its own certificate, and the server verifies it before the connection is even considered established.

How It Works

The application is issued its own X.509 digital certificate (and a corresponding private key it keeps to itself) from a certificate authority Keycloak has been configured to trust. When the application connects to the Token Endpoint, it presents this certificate as part of the TLS handshake itself — before any HTTP request content is even exchanged. Keycloak verifies the certificate’s chain of trust and confirms it belongs to the registered Client.

Where This Shines

Highly regulated environments — banking backbones, healthcare data exchanges, government systems — often already run extensive certificate infrastructure (a Public Key Infrastructure, or PKI) for other purposes. For these organizations, extending that same existing certificate-based trust model to Client Authentication is a natural fit, avoiding the need to separately manage yet another category of credential.

The Operational Cost Behind the Strength

This method’s strength comes bundled with real operational weight. Certificates expire and must be renewed on a schedule, tracked across potentially dozens or hundreds of Clients. A compromised private key requires the corresponding certificate to be revoked, and every relying party (Keycloak included) needs a working, actively checked revocation mechanism to make that revocation actually effective in practice rather than merely theoretical. Organizations without an already-established PKI team typically find this operational burden outweighs the benefit for anything short of a genuinely mandated, highly sensitive integration.

Notice the clear pattern: moving down this table trades increasing setup and operational complexity for increasingly strong guarantees about what an attacker could actually do with intercepted network traffic or a partially compromised server. There is no universally “best” choice — only the right choice for a given organization’s risk tolerance, existing infrastructure, and operational maturity.

It’s also worth noting that these four methods are not mutually exclusive across an entire Realm — different Clients within the very same Realm can each use a different method, chosen independently based on that specific application’s own risk profile, its team’s operational maturity, and any external requirements imposed by partners or regulators it happens to integrate with. A single organization might reasonably run its internal wiki on plain Client Secret authentication while its payment-partner integration runs on signed JWT with a private key, both coexisting comfortably inside one Keycloak Realm.

Why Some Clients Skip This Entirely

Recall from earlier in this series that public Clients — single-page JavaScript applications, mobile apps — cannot safely hold any confidential value, whether a raw secret, a shared signing key, or even a private key embedded in a distributed app package that a determined user could eventually extract. For these Clients, none of the four Client Authentication Methods above is appropriate, because all four assume the application can keep something secret.

PKCE as the Substitute Protection

Instead, public Clients rely on PKCE (Proof Key for Code Exchange), a mechanism covered in this series’ earlier OIDC guide. PKCE doesn’t prove the application’s long-term identity the way the four methods above do — instead, it proves that whoever is redeeming a specific authorization code is the same entity that originally initiated that specific login, using a one-time random value generated fresh for that single login attempt.

Why This Distinction Matters

Understanding this split is essential: it is not that public Clients are somehow exempt from security scrutiny — it’s that the entire category of Client Authentication Methods in this guide simply doesn’t apply to them, and a different, purpose-built mechanism fills the analogous role instead.

Bearer-Only Clients: Neither Category Applies

It’s worth also placing bearer-only Clients into this picture for completeness. Recall from earlier in this series that a bearer-only Client never initiates a login and never requests tokens for itself at all — it only ever receives and validates tokens that some other application already obtained. Because it never calls the Token Endpoint, the entire question of Client Authentication Methods simply doesn’t arise for it; there’s nothing for it to authenticate itself for.

The Client Credentials Grant, Revisited

Earlier in this series, the client credentials grant was introduced as the mechanism a confidential Client’s service account uses to obtain tokens purely on its own behalf, with no end user involved whatsoever — a nightly batch job pulling data from a partner API being the classic example. What’s worth underscoring here is that this flow does not skip Client Authentication; if anything, it makes Client Authentication the entire basis of the request, since there is no authorization code and no user session standing alongside it.

Which Methods Apply Here

All four methods introduced in Chapters 3 through 6 — Client Secret, signed JWT with a shared secret, signed JWT with a private key, and X.509 Mutual TLS — apply equally well to the client credentials grant. The application simply presents its proof of identity directly to the Token Endpoint, with no authorization code involved at all, since there was never a browser-based login to produce one.

Testing and Local Development Considerations

Developers building and testing an integration locally still need to exercise whichever Client Authentication Method a Client is configured with, and this deserves a moment of deliberate thought rather than an afterthought. A common, reasonable pattern is to register an entirely separate development-only Client, using the simplest method (Client Secret) even when production uses a more advanced one, precisely because the lower-stakes development environment doesn’t justify the operational overhead of managing keys or certificates purely for local iteration. The critical safeguard, revisited from Chapter 13, is ensuring this development Client’s credential can never be mistaken for, or accidentally reused as, the production Client’s credential — they must remain two distinctly separate registrations with two distinctly separate identities from Keycloak’s point of view.

Selection. An administrator chooses the Client Authenticator when registering (or later reconfiguring) a confidential Client, ideally based on the risk profile and existing infrastructure discussed in Chapter 7.

Credential Generation. Depending on the method, this means generating a Client Secret, generating a key pair (for signed JWT with a private key), or issuing an X.509 certificate through the organization’s PKI.

Distribution. The credential (or, for private-key methods, only the public half) is securely delivered to wherever the application actually runs, ideally through a dedicated secrets manager rather than manual copy-paste.

Active Use. Every single token request from that point forward includes this proof of identity, checked by Keycloak as described in Chapter 8.

Rotation. Secrets, keys, and certificates all have a practical shelf life and should be periodically replaced on a schedule, and immediately upon any suspected compromise.

Retirement. When an application is decommissioned, its credential should be revoked or deleted, closing off a potential lingering attack surface.

graph LR
    A["Method Selected
(at Client registration)"] --> B["Credential Generated
(secret, key pair, or certificate)"]
    B --> C["Securely Distributed
to the running application"]
    C --> D["Used on Every
Token Request"]
    D --> E{"Rotation Needed?"}
    E -->|"Scheduled or suspected leak"| F["Credential Rotated"]
    F --> C
    E -->|"App decommissioned"| G["Credential Revoked"]
    

A useful rule of thumb: the right method is rarely determined solely by which one is theoretically most secure in isolation. It’s determined by matching the method to the organization’s actual operational capacity to manage the resulting credentials correctly, indefinitely, without the process itself becoming a source of mistakes.

Questions Worth Asking Before Deciding

Beyond the four broad situations above, a more granular set of questions tends to surface the right answer for any specific application under consideration:

• Who else will need to trust this application? An integration with a single external partner who mandates a specific method (often signed JWT or mTLS) has the decision effectively made for it by that partner’s own requirements.
• How mature is this team’s secrets-management practice already? A team without a dedicated secrets manager or automated rotation tooling in place will likely introduce more risk trying to manage private keys or certificates than they remove, at least until that operational foundation is built out first.
• How often does this application get redeployed or rebuilt? Frequent redeployments make manual credential handling more error-prone regardless of method, strengthening the case for automation before reaching for a more complex credential type.
• Is there a compliance or contractual mandate at play? Some industries and some partner agreements specify a required method outright, removing this decision from the team’s own discretion entirely.

Credential Storage Discipline

Whichever method is chosen, the resulting credential — a secret string, a private key, or a certificate’s private key — must be stored in a dedicated secrets manager, injected into the running application only at deploy time, and never committed to source control or embedded in a shared configuration file readable by every developer.

Algorithm Confusion in Signed JWT Methods

A well-documented category of real-world vulnerabilities involves an application accepting a signed JWT without strictly enforcing which signing algorithm was actually used, allowing an attacker to substitute a weaker or entirely different algorithm than intended. Keycloak’s configuration should always pin the exact expected algorithm for a given Client rather than accepting whatever algorithm a submitted assertion happens to claim.

Certificate Revocation for Mutual TLS

Organizations using X.509 Mutual TLS must maintain a working certificate revocation process — if an application’s private key is ever suspected of compromise, its certificate needs to be revoked promptly, and Keycloak’s trust configuration must actually check revocation status, not merely validate the certificate chain in isolation.

Defense in Depth, Even Here

Strong Client Authentication reduces, but does not eliminate, the value of the other security layers discussed throughout this series — redirect URI validation, short token lifespans, and careful Role scoping all remain essential regardless of which Client Authentication Method is in use.

Clock Skew and Replay Protection

Both signed JWT methods rely on the client assertion’s expiration timestamp to limit how long a captured assertion remains useful, which means the clocks on the application’s server and Keycloak’s own server must stay reasonably synchronized. A significant clock drift can cause legitimate assertions to be wrongly rejected as expired, or — in the opposite failure mode — allow an assertion’s effective usable window to be larger than intended. Pairing signed JWT authentication with network time synchronization across all involved servers is a small but easily overlooked operational requirement.

Incident Response Readiness

A mature security posture doesn’t stop at choosing a strong method — it also means having a rehearsed process for what happens the moment a credential is suspected of compromise, regardless of which method is in use: how quickly can the affected Client’s credential actually be rotated, how is the application notified to pick up the new value, and how is any token already issued under the compromised credential’s watch handled in the meantime. Organizations that only think through this process after a real incident tend to take far longer to fully contain it than those with a documented, tested runbook ready in advance.

Good Patterns

• Environment-separated credentials: a distinct Client (and distinct credential) per environment, as covered in Chapter 13
• Centralized secrets management: every credential injected at deploy time from a dedicated secrets manager, never hand-copied into configuration files
• Scheduled rotation with automation: credential rotation handled by automated tooling rather than a manual, easily-forgotten calendar reminder
• Algorithm pinning: explicitly configuring the exact expected signing algorithm for signed JWT methods, rather than accepting whatever the request claims

Anti-patterns to Avoid