What Is the Difference Between RS256 and HS256 Signing in Keycloak?
The complete, in-depth guide to how Keycloak signs its tokens, and why the choice of algorithm shapes an entire application architecture.
Picture two very different ways of sealing an important letter. In the first, sender and recipient share one identical stamp, kept in both of their desks, and either party could have pressed it onto the wax — the seal proves the letter came from someone who holds that shared stamp, but it can’t prove which one of them actually sent it, and anyone else who obtained a copy of that same stamp could forge a letter indistinguishable from a genuine one. In the second, the sender keeps a unique, never-shared signet ring, while every recipient is given only a printed reference image of the wax pattern it produces — enough to verify a seal is genuine, but useless for producing one. Keycloak’s token signing options work on exactly this same distinction, and the two most common choices — HS256 and RS256 — sit on opposite sides of it.
This guide is a comprehensive, ground-up exploration of RS256 and HS256 signing in Keycloak: what a JWT signature is actually for, the mathematical distinction between symmetric and asymmetric cryptography that separates these two algorithms, how each one changes an application’s architecture and threat model, where Keycloak lets an administrator configure this choice, and the real-world reasoning that leads virtually every modern Keycloak deployment toward RS256 as the default. No prior cryptography background is assumed — every term is explained in full the moment it first appears.
1Core Concepts
What Is a JWT Signature For?
A JSON Web Token (JWT), the format Keycloak uses for its Access Tokens and ID Tokens as covered in this series’ guide to OpenID Connect, is a piece of readable, structured data describing a user’s identity and permissions. A JWT’s signature is a cryptographic value attached to it that lets anything receiving the token verify two things: that the token’s contents haven’t been altered since it was issued, and that it genuinely came from Keycloak itself rather than being forged by an attacker.
The One-Word Difference: The “256” Doesn’t Change; the Letters Do
Both algorithm names end in the same number, referring to the same underlying 256-bit strength of the hashing step involved — that part isn’t the meaningful difference. The meaningful difference is the letters at the front: HS stands for HMAC (Hash-based Message Authentication Code), a symmetric technique using one shared secret. RS stands for RSA, an asymmetric technique using a mathematically linked pair of different keys.
Nearly everything else covered in this guide — how key distribution works, what a compromised Client can and can’t do, how key rotation happens, why one algorithm scales better across many applications — flows directly from this single underlying distinction. Understanding symmetric versus asymmetric cryptography thoroughly is genuinely most of what there is to understand about choosing between these two algorithms.
2Architecture & Components
graph TD
subgraph HS256["HS256 (Symmetric)"]
KC1["Keycloak"] -->|"Shares one secret"| Secret["Shared Secret"]
Secret -->|"Same secret"| App1["Application"]
KC1 -->|"Signs token with"| Secret
App1 -->|"Verifies token with same"| Secret
end
subgraph RS256["RS256 (Asymmetric)"]
KC2["Keycloak"] -->|"Keeps private"| Priv["Private Key"]
KC2 -->|"Publishes openly"| Pub["Public Key
(via JWKS endpoint)"]
KC2 -->|"Signs token with"| Priv
App2["Application"] -->|"Verifies token with"| Pub
end
HS256 Shared Secret
One single secret value, known to both Keycloak and the verifying application, used for both signing and verifying.
RS256 Private Key
Held exclusively by Keycloak, used only to sign tokens, and never shared with any application.
RS256 Public Key
Mathematically linked to the private key, safe to share openly, and used only to verify — not create — a signature.
JWKS Endpoint
The standard endpoint Keycloak exposes, publishing its current public keys so any application can fetch them automatically — covered fully in Chapter 6.
3Deep Dive: How HS256 Actually Works
The Shared Secret
Under HS256, Keycloak and the verifying application both possess an identical secret value — in Keycloak’s world, this is commonly the Client’s own secret, the same one covered in this series’ guide to Client Authentication Methods. Keycloak uses this secret, combined with the token’s contents, to produce the signature. The application uses that exact same secret to recompute what the signature should be and compares it against what was actually attached.
Why This Requires Trust in Every Verifier
Because the shared secret can be used interchangeably to both create and check a signature, anything holding that secret is, cryptographically speaking, just as capable of producing a convincing, valid-looking token as Keycloak itself. This isn’t a flaw in the algorithm’s math — HMAC is a well-established, secure technique — but a direct architectural consequence of the symmetric design: verification capability and signing capability are the same capability.
This is the shared wax stamp from the opening. Anyone holding a copy of the identical stamp can press a seal onto a letter that looks exactly as genuine as one the original sender produced. The stamp itself doesn’t distinguish between “the person authorized to send letters” and “anyone who happens to have a copy” — possession alone grants both capabilities equally.
4Deep Dive: How RS256 Actually Works
The Key Pair
Under RS256, Keycloak generates a mathematically related pair of keys: a private key, kept strictly confidential and never leaving Keycloak’s own control, and a public key, which is deliberately published for anyone to retrieve. The mathematics behind RSA guarantee that a signature produced with the private key can be verified using only the public key, but the public key cannot be used, even in principle, to produce a new valid signature of its own.
Why This Separates Signing From Verifying
This asymmetry is the entire point: an application holding only the public key can confidently verify that a token was genuinely signed by whoever holds the matching private key — presumably Keycloak — without that application ever gaining any ability to forge a new, convincing token of its own. Verification capability and signing capability are now genuinely different, separable capabilities.
This is the signet ring and its printed reference pattern from the opening. Anyone can hold the printed pattern and confidently check whether a wax seal matches it — but no amount of studying that printed pattern lets them carve their own working signet ring capable of producing a new, genuine-looking seal.
Production Example: A Public Mobile App Verifying Tokens Locally
A mobile application distributed publicly through an app store, and therefore fundamentally unable to keep any embedded secret truly confidential (since a determined user can decompile the app), can still safely hold Keycloak’s RS256 public key and verify tokens locally, since possessing that public key grants no ability to forge new tokens even if an attacker fully reverse-engineers the app.
5The Core Security Trade-off, Stated Directly
| Question | HS256 | RS256 |
|---|---|---|
| Can a verifying application forge a new, valid token? | Yes — it holds the same secret used to sign | No — it holds only a public key, insufficient to sign |
| Is it safe to give the verification material to an untrusted client, like a public mobile app or browser-based JavaScript app? | No — this exposes the same secret used for signing | Yes — the public key grants no signing capability |
| How many different applications can safely verify tokens independently? | Limited — each one needs the secret, multiplying exposure | Unlimited — the public key can be freely distributed to any number of verifiers |
| What happens if one verifying application is compromised? | The shared secret is exposed, and every application relying on that same secret must now be treated as compromised too | Only that application’s own trust is affected; the private key, and every other verifier’s ability to trust tokens, remains completely unaffected |
Given the comparison above, it should be clear why virtually every modern Keycloak deployment defaults to, and stays with, RS256. HS256 isn’t broken or insecure in isolation, but it creates a fundamentally more fragile trust architecture the moment more than one, fully trusted application needs to verify tokens — which describes essentially every real-world deployment beyond the very simplest single-application setup.
6Deep Dive: The JWKS Endpoint and Automatic Key Distribution
What JWKS Is
JWKS stands for JSON Web Key Set — a standard, machine-readable format for publishing one or more public keys. Keycloak exposes its own current public keys at a predictable, well-known URL for each Realm, discoverable through the same OpenID Connect discovery document covered elsewhere in this series.
Why This Matters in Practice
Because the public key is published at a standard, automatically discoverable location, a properly built application library doesn’t need an administrator to manually copy and paste a key value anywhere — it simply fetches the current key set from the JWKS endpoint itself, typically caching it for a reasonable period before refreshing. This stands in sharp contrast to HS256, where the shared secret genuinely has to be manually distributed and kept synchronized across every application that needs it.
Production Example: Adding a New Microservice Without Any Coordination
An organization adding a brand-new backend microservice that needs to verify incoming Access Tokens can simply point its token-verification library at Keycloak’s JWKS endpoint, with no manual secret-sharing step or coordination with whoever manages Keycloak required at all — a meaningful operational advantage that compounds as the number of independently deployed services grows.
7Deep Dive: Key Rotation
Rotating an RS256 Key Pair
Because RS256 verifiers fetch the current public key from the JWKS endpoint rather than having it hard-coded anywhere, Keycloak can generate a new key pair and publish the new public key at that same endpoint, and every properly built verifying application picks up the change automatically the next time it refreshes its cached key set — typically without any coordinated, simultaneous update across every application at all.
Rotating an HS256 Shared Secret
Rotating a shared HS256 secret is a fundamentally more disruptive operation: every single application holding the old secret needs to be updated to the new one, and until every one of them has been updated, there’s a genuine risk of tokens failing to verify correctly during the transition — a coordination burden that grows directly with the number of applications relying on that shared secret.
To make RS256 rotation even smoother, Keycloak’s key management can keep a previous key active for verification purposes for a period after a new one becomes the active signing key, ensuring tokens signed just before the rotation don’t suddenly fail verification the moment the new key takes over — a graceful transition that would be far harder to replicate safely with a single shared HS256 secret.
8Where This Is Actually Configured in Keycloak
Realm-Level Default Signature Algorithm
A Realm’s own Tokens settings, in its broader Realm Settings, include a default signature algorithm applied to tokens issued within that Realm, with RS256 as Keycloak’s standard, out-of-the-box default.
Per-Client Overrides
An individual Client’s own Advanced settings can override the Realm’s default, specifying a different algorithm for tokens issued to that specific Client — a capability that exists mainly for compatibility with an older or unusual application with a hard requirement for a specific algorithm, rather than as a routinely exercised option.
Production Example: A Legacy Application Requiring HS256
An organization integrating an older, third-party application that was built years ago with hard-coded support only for HS256 verification might configure that one specific Client to use HS256, while leaving every other Client in the Realm on the default RS256 — an isolated, deliberate exception rather than a Realm-wide compromise.
9Internal Working: The Full Signing and Verification Flow
Keycloak Issues a Token
Following a successful login, Keycloak constructs the token’s contents and signs it using its own private key, producing the final signed JWT.
Token Reaches an Application
The application receives this token, typically as part of an API request’s Authorization header, exactly as covered in this series’ broader OpenID Connect guide.
Application Fetches (or Uses a Cached Copy of) the Public Key
The application’s token-verification library retrieves the appropriate public key from Keycloak’s JWKS endpoint, or uses an already-cached copy if it’s still within its refresh window.
Signature Verified Mathematically
Using the public key, the application confirms that the token’s signature could only have been produced by whoever holds the matching private key, and that the token’s contents haven’t been altered since it was signed.
Application Trusts the Token’s Contents
Once verification succeeds, the application proceeds to trust the token’s claims — the user’s identity, their Roles — exactly as it would for any other successfully authenticated request.
10Why Browser-Based Applications Specifically Should Never Use HS256
JavaScript Running in a Browser Can’t Keep Any Secret
An application built as JavaScript code running directly inside a user’s browser — a Single Page Application, in common terminology — has its entire source code delivered directly to that browser, where any reasonably determined user can inspect it freely. Any secret value embedded in that code, including an HS256 shared secret, should be treated as fully exposed the moment the application is loaded by anyone at all.
If a browser-based application were configured with HS256 and its shared secret embedded in its own JavaScript, literally any visitor to that application could extract the secret and use it to forge arbitrary, fully valid-looking tokens claiming to be any user at all — including an administrator. This is precisely why Public Clients, covered elsewhere in this series, are architecturally incompatible with HS256’s shared-secret model, and why RS256 (or an equivalent asymmetric approach) is essentially mandatory for any browser-based application.
This Is Also Why Public Clients Generally Don’t Hold Any Signing Secret at All
In practice, this issue is addressed at a more fundamental level than choosing between algorithms: a Public Client, as covered in this series’ guide to Client Authentication Methods, is never given a Client secret in the first place, precisely because it cannot be trusted to keep one confidential — reinforcing, from a different angle, why the entire architecture points firmly toward RS256’s asymmetric model wherever a fully untrusted verifier or holder might be involved.
Mobile Applications Face the Same Underlying Problem
A native mobile application distributed through a public app store shares the same fundamental weakness as browser-based JavaScript, even though its code isn’t as trivially readable at a glance: a sufficiently motivated attacker can decompile a mobile app’s binary and extract embedded strings, including any hard-coded secret. Treating a mobile app as capable of confidentially keeping a shared HS256 secret is just as unsound as making the same assumption about browser code, which is why mobile applications integrating with Keycloak are typically configured as Public Clients relying on RS256 verification, exactly like their browser-based counterparts.
Server-Side Confidential Clients Are a Genuinely Different Case
It’s worth contrasting this against a traditional server-side web application, running entirely on infrastructure the organization itself controls and never exposing its own source code or configuration to an end user’s device. A Confidential Client of this kind genuinely can keep a secret private, which is part of why HS256 remains at least theoretically viable there — though even in this case, the operational and scaling advantages of RS256 described throughout this guide generally still make it the better default choice.
11Data Flow & Lifecycle
Generation. Keycloak generates its signing material for a Realm — a key pair for RS256, or relies on Client secrets for HS256 — either automatically at Realm creation or through explicit administrator configuration.
Active Use. The current active key signs every newly issued token for that Realm, while applications verify incoming tokens against the corresponding verification material.
Publication (RS256 Only). The public key is continuously available at the JWKS endpoint, allowing any application to fetch or refresh it at any time without requiring any coordination.
Rotation. Periodically, for good security hygiene, the active signing key is rotated — a comparatively smooth, low-coordination process under RS256, and a comparatively disruptive, tightly coordinated one under HS256, as covered in Chapter 7.
Retirement. An old key is eventually retired from active signing use, though it may remain available briefly for verification purposes to avoid disrupting tokens issued just before the rotation.
graph LR
A["Key Generated"] --> B["Active Signing Use"]
B --> C{"RS256 or HS256?"}
C -->|"RS256"| D["Public Key Published
at JWKS Endpoint"]
C -->|"HS256"| E["Secret Manually
Distributed to Verifiers"]
D --> F["Smooth, Low-Coordination
Rotation"]
E --> G["Disruptive, Tightly
Coordinated Rotation"]
12Advantages, Disadvantages & Trade-offs
RS256 Advantages
- Verifiers can never forge new tokens, even if fully compromised or fully public, since they hold only a public key
- Scales cleanly to any number of independent verifying applications with no added coordination cost
- Key rotation is smooth and largely automatic, via the JWKS endpoint
- The only architecturally sound choice for browser-based or otherwise untrusted verifiers
HS256 Trade-offs
- Slightly simpler to reason about and marginally faster computationally in isolated, single-application scenarios
- Requires manually distributing and safeguarding one shared secret across every verifier, growing more fragile as more applications need to verify tokens
- A single compromised verifier compromises the shared secret for every other verifier relying on it too
- Fundamentally unsuitable for any untrusted or publicly distributed verifier, including virtually all browser-based applications
13Security
Problem
A verifying application’s token-validation library is configured to accept any algorithm a presented token happens to claim, rather than being explicitly restricted to expect only RS256.
Why It Fails
This opens the door to a well-documented class of attack where a malicious actor crafts a token claiming to use HS256, then signs it using the RS256 public key itself as if it were an HS256 shared secret — a trick that can succeed against a poorly configured verifier that doesn’t strictly enforce which algorithm it expects.
Correct Approach
Always explicitly configure a verifying application’s library to accept only the specific algorithm actually expected — RS256, in virtually every modern deployment — and reject a token outright if it claims to use anything else, regardless of what that token’s own header states.
Never Roll a Realm’s Default Down to HS256 for Convenience
It can be tempting, especially early in a project, to switch a Realm’s default signing algorithm to HS256 for perceived simplicity. Given the architectural risks covered throughout this guide — particularly the browser-compatibility issue in Chapter 10 — this is rarely, if ever, the right trade-off for a production deployment, and the operational cost of eventually migrating back to RS256 later is generally far higher than simply starting with RS256 from the beginning.
Key Size and Algorithm Strength Considerations
Beyond the symmetric-versus-asymmetric distinction, the underlying key size Keycloak generates for its RSA key pair also matters for long-term security. A larger key size generally provides a greater margin of safety against future advances in computational power, at a modest cost in signing and verification performance. Keycloak’s own defaults are chosen to reflect current, broadly accepted security guidance, and an organization with unusually strict compliance requirements should confirm the specific key size in use aligns with whatever standard they’re required to meet, adjusting it explicitly if not.
Signature Algorithm Choice Doesn’t Replace Transport Security
It’s worth being explicit that neither RS256 nor HS256 does anything to protect a token in transit between Keycloak and an application — that protection comes entirely from HTTPS, covered in this series’ guide to CSP and browser security headers. A properly signed RS256 token sent over an unencrypted connection is still fully readable, and potentially interceptable, by anyone positioned on that network path; the signature only ever protects against tampering and forgery, never against exposure in transit.
14Monitoring, Logging & Metrics
Signature Verification Failure Rate
Tracking how often incoming tokens fail signature verification can surface a key-rotation problem, a clock-synchronization issue, or a misconfigured verifying application before it causes widespread outages.
Per-Client Algorithm Configuration Review
Periodically reviewing which Clients have been given an algorithm override away from the Realm default helps confirm every exception still has a genuine, current justification.
JWKS Endpoint Availability
Since every RS256 verifier depends on being able to reach the JWKS endpoint, monitoring its own uptime and response correctness is essential — an unreachable JWKS endpoint can cause verification failures across every dependent application simultaneously.
Verifier Algorithm Restriction Confirmation
Confirming that every verifying application explicitly restricts its accepted algorithm list, as covered in Chapter 13, rather than accepting whatever a token happens to claim.
Watching for a Spike Immediately After a Key Rotation
A brief, small spike in signature verification failures immediately following a planned key rotation can be a normal, expected artifact of applications catching up with a newly published key, particularly if any of them cache the JWKS response for a longer period than ideal. What deserves genuine concern is a spike that persists well beyond a reasonable refresh window, which usually points to a specific application holding an unusually long cache duration, a misconfigured client library, or a genuine connectivity problem reaching the JWKS endpoint — each worth investigating as a distinct, separate possibility rather than assuming the rotation itself was simply at fault.
Alerting Thresholds Should Reflect Normal Baseline Noise
Because a small, ongoing trickle of verification failures is often unavoidable in any sufficiently large, distributed system — an occasional expired token being retried, a rare clock-drift edge case — an effective monitoring setup establishes a realistic baseline for ordinary noise before configuring alert thresholds, rather than triggering an alert on any failure at all. This keeps genuine incidents visible without burying the team in false alarms during entirely ordinary operation.
15Design Patterns & Anti-patterns
Good Patterns
- Keep RS256 as the Realm-wide default and reach for an algorithm override only for a genuinely justified, isolated legacy compatibility need
- Always explicitly restrict a verifier’s accepted algorithm list, rather than trusting a token’s own self-declared algorithm
- Let properly built libraries fetch keys from the JWKS endpoint automatically, rather than hard-coding a key value anywhere
- Never assign a shared secret to a Public Client or any browser-based application, as covered in Chapter 10
Anti-patterns to Avoid
Common Mistakes
- Switching a Realm’s default to HS256 for perceived simplicity, without weighing the architectural cost, as discussed in Chapter 13
- Embedding any shared signing secret inside browser-delivered JavaScript code
- Failing to restrict a verifier’s accepted algorithms, opening the door to the algorithm-confusion attack in Chapter 13
- Hard-coding a public key value instead of fetching it dynamically from the JWKS endpoint, defeating the smooth rotation RS256 otherwise enables
16Real-World & Industry Examples
Microservices Architectures
An organization running dozens of independently deployed backend microservices, each needing to verify incoming Access Tokens on its own, relies on RS256 specifically because it lets every new service verify tokens by simply fetching the public JWKS endpoint, with zero coordination required with whichever team manages Keycloak itself.
Public Single Page Applications
A customer-facing web application built as a browser-based Single Page Application relies entirely on RS256, given the fundamental incompatibility between HS256’s shared-secret model and any code delivered directly to an untrusted browser, covered fully in Chapter 10.
Regulated Industries With Formal Key-Management Requirements
A financial or healthcare organization subject to formal security compliance standards typically mandates RS256 specifically because its clean separation between signing and verification capability, along with its smoother key-rotation story, aligns far more naturally with standard key-management and audit practices than a widely shared symmetric secret would.
Legacy System Integration as the Rare Exception
An organization integrating one specific, older internal system that was built years before RS256 support was added to its own libraries might configure that one Client for HS256 as a narrow, deliberate, and typically temporary exception, while every other Client in the deployment remains on RS256.
17Frequently Asked Questions
18Summary and Key Takeaways
Choosing between these two algorithms is, in practice, rarely a close call once the underlying trust model is genuinely understood — the question isn’t which one is “better” in the abstract, but which trust model actually matches how a real deployment is architected. An organization with exactly one fully trusted, server-side application and nothing else might find HS256 tolerable in principle, but the moment a second application, a mobile client, or a browser-based interface enters the picture, RS256’s asymmetric separation of signing from verification stops being a nice-to-have and becomes the only architecturally sound choice actually available, which is precisely why it remains Keycloak’s own default and the recommendation this entire guide arrives at.
Key Takeaways
- HS256 is symmetric — one shared secret both signs and verifies, meaning any verifier could also forge a token.
- RS256 is asymmetric — a private key signs, and a separate public key verifies, meaning a verifier can never forge a new token even if fully compromised or fully public.
- RS256’s public key is published at the JWKS endpoint, enabling automatic, zero-coordination key distribution and rotation across any number of applications.
- Browser-based and other untrusted applications must never use HS256, since any embedded shared secret should be treated as fully exposed the moment the application is loaded.
- RS256 is Keycloak’s default and the right choice for essentially every modern deployment; HS256 is reserved for narrow, justified legacy-compatibility exceptions.
- Always explicitly restrict a verifier’s accepted algorithm list rather than trusting a token’s own self-declared algorithm, closing off a well-known algorithm-confusion attack.
- Treat mobile applications the same as browser-based ones — a decompiled binary exposes an embedded secret just as thoroughly, so both should rely on RS256 as Public Clients rather than holding any shared secret.
- Signature algorithm choice protects against tampering and forgery, not exposure in transit — that protection still depends entirely on HTTPS, regardless of which signing algorithm is used.