Username/Password Authentication is the process of confirming a user’s identity by asking them to type two pieces of information they should be the only ones to know (or that identify them): a username (or email) that identifies which account they’re claiming to be, and a password — a secret string only that account holder should know — that proves they’re really that person.

In Keycloak, this isn’t a single hardcoded feature bolted onto the login page. It’s actually one configurable step, called an Authenticator, inside a larger, fully customizable pipeline called an Authentication Flow. The default flow most users experience — called the Browser Flow — includes a step commonly labeled “Username Password Form”, which is exactly the piece responsible for rendering the login form and checking what’s typed into it.

What makes this deceptively simple flow interesting under the hood is everything Keycloak does around that basic check: hashing and never storing raw passwords, enforcing password policies, detecting brute-force attempts, supporting federated directories, and seamlessly chaining into further steps like multi-factor authentication — all without the application itself needing to implement any of that logic.

It’s also worth knowing where the password itself might actually be checked. If the user is a local Keycloak user, the password is verified against a securely hashed value stored in Keycloak’s own database. If the user is a federated user (synced from LDAP or Active Directory), Keycloak instead forwards the check to that external directory in real time — the username/password step behaves identically from the user’s point of view either way, even though very different machinery runs behind it.

flowchart TB
    LoginForm["Login Form (Username Password Form)"] --> AuthFlow["Authentication Flow (e.g. Browser Flow)"]
    AuthFlow --> CredProvider["Credential Provider"]
    CredProvider --> LocalDB["Local Password Hash Store"]
    CredProvider --> LDAPProvider["LDAP / AD Federation Provider"]
    AuthFlow --> PasswordPolicy["Password Policy Engine"]
    AuthFlow --> BruteForce["Brute Force Detection"]
    AuthFlow -->|"on success"| NextStep["Next Flow Step (e.g. OTP)"]
    

Let’s walk through each labeled piece in turn.

Authentication Flow

A named, ordered sequence of steps a login attempt must pass through. Keycloak ships with sensible defaults (like the Browser Flow) but lets administrators fully customize the sequence — reordering steps, marking some as required versus optional, or adding conditional branches.

Username Password Form (the Authenticator)

The specific execution step responsible for rendering the actual login form and capturing what’s submitted. It doesn’t do the cryptographic verification itself — it hands the submitted credentials off to the appropriate Credential Provider.

Credential Provider

The component that actually performs the comparison. For local users, it retrieves the stored password hash and checks it using the same hashing algorithm and parameters used when the password was originally set. For federated users, it delegates the check outward instead.

Password Policy Engine

A configurable set of rules — minimum length, required character types, not matching the username, not reusing recent passwords, expiration after a set number of days — enforced whenever a password is created or changed, though not on every single login check itself.

Brute Force Detection

A safeguard that monitors failed login attempts per user and can temporarily lock an account after too many consecutive failures, slowing down automated password-guessing attacks.

Hashing, Not Encryption

Keycloak never stores a password in a way that could be reversed back into the original text. Instead, when a password is set, it’s run through a one-way hashing algorithm (by default a strong, iterated algorithm like PBKDF2, configurable via the realm’s Password Policy) combined with a unique random salt per user. Only the resulting hash and salt are stored — the original password is discarded immediately after hashing.

The Verification Step

When a user submits a password at login, Keycloak doesn’t “decrypt” anything — it re-runs the exact same hashing process on the submitted password, using the stored salt, and compares the newly computed hash to the one stored on file. If they match exactly, the password is considered correct; if not, authentication fails.

Federated Verification

For users sourced from LDAP or Active Directory, Keycloak typically doesn’t store or hash the password locally at all. Instead, it performs what’s called an LDAP bind operation — attempting to authenticate directly against the external directory server using the submitted credentials — and treats a successful bind as a successful password check.

Required Actions Triggered by This Step

A successful username/password check can still be followed by a mandatory extra step if the user’s account carries a Required Action, such as “Update Password” (often set after an admin-initiated reset) — the user is fully authenticated in terms of “who they are,” but blocked from proceeding until that required step is completed.

flowchart LR
    A["1. User submits username + password"] --> B["2. Keycloak locates the User record"]
    B --> C["3. Determine source: local or federated"]
    C --> D["4. Local: compare password hash"]
    C --> E["5. Federated: attempt LDAP bind"]
    D --> F["6. Check brute-force lockout status"]
    E --> F
    F --> G["7. Resolve pending Required Actions"]
    G --> H["8. Proceed to next flow step (e.g. OTP) or issue token"]
    

Notice that a “successful” username/password check doesn’t necessarily mean the login is complete — it simply means that one specific step in a potentially longer flow has passed. This is exactly what makes layering additional factors on top of username/password authentication so seamless in Keycloak.

Strong Hashing Configuration

Keycloak’s realm-level Password Policy lets administrators configure the hashing algorithm and its iteration count, allowing organizations to keep pace with evolving cryptographic best practices as computing power increases over time.

Brute-Force Protection

Enabling Brute Force Detection at the realm level automatically locks out an account, or introduces increasing delays, after a configurable number of consecutive failed attempts — a critical defense against automated password-guessing and credential-stuffing attacks.

Password Policies Beyond Length

Beyond minimum length, Keycloak’s Password Policy engine can enforce a mix of character types, block reuse of recent passwords, forbid the password from containing the username, and require periodic expiration — each configurable independently per realm.

Transport Security

Credentials must always travel exclusively over HTTPS between the browser and Keycloak — without this, the password (or any token issued afterward) could be intercepted in transit regardless of how strong the hashing or policy configuration is on the server side.

Good Pattern: Layer MFA on Top

Treat username/password as the first, familiar step in a flow, not the entire flow — pairing it with a second factor for any realm handling meaningful access or sensitive data.

Good Pattern: Conditional Flow Branching

Use Keycloak’s conditional flow steps to require stronger verification only when risk signals warrant it — for example, demanding MFA for logins from unrecognized devices while keeping trusted, recognized ones frictionless.

Good Pattern: Federate Rather Than Duplicate

When an organization already has an authoritative LDAP/AD directory, federating username/password checks to it (rather than migrating everyone to local Keycloak accounts) keeps password policy enforcement consistent with existing corporate standards.

Common Mistakes to Avoid

• Leaving Brute Force Detection disabled: This is off by default in some setups and must be deliberately enabled to take effect.
• Assuming HTTPS is “someone else’s problem”: Misconfigured deployments that allow plain HTTP for the login form expose every submitted password in transit.
• Not testing federated login failure modes: If the external LDAP/AD server is unreachable, federated username/password checks will fail — a scenario worth explicitly planning and monitoring for.
• Copying password policy settings between realms without review: A policy appropriate for a low-risk customer realm may be far too weak for an internal administrative realm.