Before touching architecture, let’s build the vocabulary — starting with what a Credential actually represents inside Keycloak.

A Credential in Keycloak is a stored piece of evidence attached to a user’s account that Keycloak uses to verify their identity during login. The most familiar example is a password, but Keycloak treats many other proof types the same way: a one-time code generator (OTP), a WebAuthn hardware security key, a recovery code, or even a client certificate. Each of these is stored as its own Credential record, and a single user account can hold several different Credentials at once, giving them multiple ways to prove who they are.

It helps to separate two ideas that are easy to blur together. Authentication is the overall process of proving identity — the login flow as a whole. A Credential is the specific artifact used as evidence during that process. You can think of authentication as the exam, and a Credential as one specific answer sheet a user is allowed to submit as proof they studied.

A few terms recur constantly in any Credential conversation, and getting them straight now makes the rest of this guide far easier to follow:

It’s worth being precise about one common confusion: a Credential is not the same thing as a Role or a Group. Roles and Groups describe what a user is allowed to do once they’re recognized. A Credential is purely about the earlier step — proving who they are in the first place. Authentication happens first, using Credentials; authorization happens after, using Roles and Groups.

Credentials don’t exist in isolation — they sit inside a small ecosystem of cooperating Keycloak components. Let’s map that ecosystem out.

Every Credential belongs to exactly one User, inside exactly one Realm — Keycloak’s isolation boundary. Around that simple relationship sit several components responsible for storing, protecting, and checking Credentials safely.

graph TD
    U["User Account"] -->|"owns one or more"| CR["Credentials
(password, OTP, WebAuthn...)"]
    CR -->|"protected by"| HASH["Hashing Algorithm
+ Per-Credential Salt"]
    R["Realm
(isolation boundary)"] --> U
    R -->|"defines rules via"| FLOW["Authentication Flow"]
    FLOW -->|"decides which
Credential types apply"| CR
    U -->|"login attempt"| FLOW
    FLOW -->|"verifies match,
never reads secret"| CR
    FLOW -->|"on success"| TOKEN["Signed Token Issued"]
        

Each labeled component in that diagram has a distinct job:

An important architectural nuance: because an Authentication Flow is configurable per Realm, two Realms in the same Keycloak deployment can enforce completely different Credential requirements — one Realm might require only a password, while another requires a password plus a hardware security key, even though both are running on the same underlying Keycloak installation.

Now let’s open the hood and see exactly how a typed password becomes a verified login, without the original secret ever being stored anywhere in readable form.

When a user sets a password, Keycloak never stores the password itself. Instead, it runs the password through a one-way hashing algorithm — a mathematical function that turns readable text into a scrambled value that cannot practically be reversed back into the original. Before hashing, Keycloak also mixes in a random salt value unique to that particular Credential, ensuring that even if two different users happen to choose the identical password, their stored values look completely different from one another.

Other Credential types work on the same underlying principle of “verify without exposing,” even though the mechanics differ. A one-time code (OTP) Credential stores a shared secret used to generate matching six-digit codes on both the user’s authenticator app and Keycloak’s side, comparing the two without ever transmitting the secret itself during login. A WebAuthn hardware security key Credential stores a public cryptographic key; the physical key device proves possession by signing a challenge with its private key, which never leaves the device.

This design means that even if Keycloak’s underlying database were somehow exposed, an attacker would not gain usable passwords directly — they would need to attempt to reverse strong, salted hashes, which is computationally impractical when a modern hashing algorithm and sufficient work factor are used correctly.

Let’s trace one complete journey — from a user first setting a password, to logging in months later with both a password and a one-time code.

sequenceDiagram
    participant U as User
    participant KC as Keycloak
    participant DB as Credential Store

    U->>KC: Set new password
    KC-->>KC: Generate random salt
    KC-->>KC: Hash password + salt
    KC->>DB: Store hash + salt (never the raw password)

    Note over U,KC: Weeks later — login attempt

    U->>KC: Submit username + password
    KC->>DB: Retrieve stored hash + salt
    KC-->>KC: Hash submitted password with same salt
    KC-->>KC: Compare new hash to stored hash
    KC-->>U: Match confirmed — prompt for OTP (second factor)
    U->>KC: Submit OTP code from authenticator app
    KC-->>KC: Verify code against shared OTP secret
    KC-->>U: Both Credentials verified — issue signed token
        

Notice the key detail: at no point during the login attempt does Keycloak retrieve or compare a stored plain-text password — it only ever compares hashed values. The original submitted password is discarded from memory immediately after hashing and comparison, and never written to storage in readable form.

Treating every proof type as a first-class Credential gives Keycloak real flexibility, but that flexibility comes with design considerations.

That last row captures a genuine trade-off worth remembering: a Credential system can be cryptographically excellent and still be undermined by a poorly designed recovery path. If “I lost my security key” resets straight to a weak, easily-guessable fallback, an attacker doesn’t need to break any hashing algorithm — they simply exploit the recovery flow instead.

Because Credentials are the foundation everything else in Keycloak trusts, their protection deserves particular care.

A well-known real-world risk here is credential stuffing, where attackers take passwords leaked from an unrelated breach elsewhere and try them against many different accounts, betting that some users reused the same password. Because Keycloak never sees or stores a user’s password in reusable form, a breach of Keycloak’s own storage doesn’t hand attackers a working password list — but users reusing passwords across services remains a risk outside Keycloak’s control, which is exactly why MFA matters so much.

Because every login attempt touches the Credential system, it becomes one of the richest sources of security signal an organization has — if the right things are watched.

Keycloak logs Credential-related events centrally, giving security teams a single place to see password resets, failed verification attempts, new Credential registrations, and Credential removals across the entire user base, rather than reconstructing this history from scattered application logs.

These logs also support compliance obligations that require organizations to demonstrate how account access is proven and protected. Because Credential events are centralized in Keycloak, producing that evidence is far simpler than reconstructing authentication history from many separate application login systems.

Years of real-world Keycloak deployments have surfaced Credential-handling approaches that hold up well, and habits that reliably cause problems.

One especially instructive anti-pattern is what security teams sometimes call “MFA theater” — an organization proudly enables multi-factor authentication for login, while leaving a password-only recovery flow completely unprotected. Attackers quickly learn to skip the hardened front door entirely and walk straight through the unguarded recovery path instead.

A practical checklist distilled from real deployments — the habits that keep a Credential system trustworthy over time.

Keycloak Credentials aren’t a theoretical concept — they’re quietly proving identity behind real deployments across many industries.

A particularly instructive real-world lesson comes from large-scale credential-stuffing incidents reported across the industry: attackers rarely need to break a strong hashing algorithm directly. Instead, they exploit reused passwords from unrelated breaches, or target weak recovery flows. This consistently reinforces why MFA and careful recovery-path design matter as much as, if not more than, the strength of the primary hashing mechanism itself.

A quick recap of everything this guide has covered — the mental model to carry forward.

A Credential in Keycloak is the stored proof behind every login — a password, an OTP registration, a security key, or any other verifiable evidence of identity. Keycloak never stores these secrets in reversible form; it stores protected representations that can be checked but not read back. A single user can carry multiple Credentials at once, enabling layered, multi-factor authentication without custom engineering — but the real-world strength of that system depends just as much on how carefully recovery flows and Credential lifecycle management are handled as on the cryptography itself.