Skip to content

Password Policy & Lockout

Enforce strong credentials and stop credential-stuffing and brute-force attacks before they reach your applications.

What it is

HelixIAM gives every realm a complete set of credential-hardening controls: a configurable password policy, password history, breached-password detection, modern Argon2id hashing, account lockout / brute-force protection, CAPTCHA, concurrent-session limits, and a Required Actions framework that can compel users to remediate at their next sign-in.

How it works

Password policy

Define the rules new and changed passwords must satisfy — length, character classes, and similar constraints — per realm. The policy is enforced at registration, at self-service password change, and whenever an admin resets a credential.

Password history

Helix remembers a configurable number of previous passwords and rejects reuse, so users can't cycle back to a compromised or expired secret.

Breached-password detection (HIBP)

Passwords are checked against the Have I Been Pwned breach corpus using a privacy-preserving k-anonymity range query — the full password is never sent. Known-breached passwords are rejected even when they technically satisfy the policy.

Breach checks beat complexity rules

A password that meets every complexity rule can still be in a public breach list. Enabling HIBP catches exactly those credentials that look strong but are already burned.

Hashing

Credentials are hashed with Argon2id, a memory-hard algorithm designed to resist GPU and ASIC cracking. Existing hashes are upgraded transparently as users authenticate.

Account lockout / brute-force protection

Repeated failed sign-ins trigger temporary lockout with back-off, protecting accounts from online password guessing and credential stuffing. Thresholds and lockout duration are configurable per realm.

CAPTCHA

Add a CAPTCHA challenge to login and registration to blunt automated attacks and bot-driven account creation.

Concurrent-session limits

Cap how many simultaneous sessions a user may hold, reducing the blast radius of a shared or stolen credential.

Required Actions

The Required Actions framework lets you queue tasks a user must complete before they finish signing in — for example:

  • update password
  • verify email
  • configure OTP / a second factor

The user is interrupted at their next login and guided through the action.

Watch: set the password policy and lockout

31 seconds, no sound. Set the password rules, breached-password check and account lockout, then save. Recorded on the current release.

In the console

Password, lockout, breach-check, CAPTCHA and session-limit controls are all realm-level settings on Realm settings, spread over three tabs.

  1. Open Realm settings → Login. Under Login security, set Minimum password length.
  2. Under Password policy, turn on the character rules you want (Require uppercase, Require lowercase, Require digit, Require special character, Password cannot be username) and set Password history count.
  3. Turn on Check breached passwords to reject known-breached passwords even when they satisfy the rules.
  4. Under CAPTCHA, optionally choose a CAPTCHA provider (Cloudflare Turnstile or Google reCAPTCHA v2) and its Site key and Secret key.
  5. Open Realm settings → Threat protection. Under Brute-force protection, turn on Enable lockout and set Max login failures, Failure reset window (seconds) and Lockout duration (seconds), or turn on Permanent lockout.
  6. Open Realm settings → Tokens & sessions to set Max concurrent sessions and Evict oldest session under Concurrent sessions.
  7. Click Save. Changes apply to the next registration, password change and sign-in.

To force an individual user to remediate, open the user and tick Update password under Required actions on the Details tab, then click Save required actions. It fires at their next sign-in.

Roll out gradually

Enabling strict rules or breach checking on an existing realm can block users with non-compliant passwords. Pair it with the update password required action so users are guided to remediate rather than simply locked out.

Over the API

Every control on this page is a field of the realm-settings resource at /admin/realms/{realm}/settings. The examples below assume you have set $HELIX_URL / $REALM and logged in — see Authenticating to the API.

Read the current policy

curl -s -b cookies.txt "$HELIX_URL/admin/realms/$REALM/settings"
{
  "realmId": "acme",
  "passwordMinLength": 12,
  "passwordRequireUppercase": false,
  "passwordRequireLowercase": false,
  "passwordRequireDigit": false,
  "passwordRequireSpecial": false,
  "passwordNotUsername": false,
  "passwordHistoryCount": 0,
  "breachedPasswordCheck": false,
  "lockoutEnabled": false,
  "maxLoginFailures": 5,
  "lockoutDurationSeconds": 900,
  "failureResetSeconds": 900,
  "permanentLockout": false,
  "captchaProvider": "none",
  "captchaSiteKey": null,
  "captchaSecretKey": null,
  "maxConcurrentSessions": 0,
  "concurrentSessionEvictOldest": true
}

The fields map directly to the features on this page:

Field(s) Controls
passwordMinLength, passwordRequire*, passwordNotUsername Password complexity rules
passwordHistoryCount Password history (reuse depth; 0 = off)
breachedPasswordCheck Have I Been Pwned breach detection
lockoutEnabled, maxLoginFailures, lockoutDurationSeconds, failureResetSeconds, permanentLockout Account lockout / brute-force protection
captchaProvider, captchaSiteKey, captchaSecretKey CAPTCHA on login & registration
maxConcurrentSessions, concurrentSessionEvictOldest Concurrent-session limit (0 = unlimited)

Argon2id hashing is not configurable here

Credentials are always hashed with Argon2id and upgraded transparently on next sign-in — there is no toggle to weaken it.

Update the policy

PUT /settings takes the full settings object — read it first, change the fields you want, then submit the whole document.

# Refresh CSRF after the GET, then PUT (see the auth guide for the helper)
curl -s -b cookies.txt -c cookies.txt "$HELIX_URL/admin/realms/$REALM/settings" >/dev/null
CSRF=$(awk '($6=="__Host-XSRF-TOKEN"||$6=="XSRF-TOKEN")&&$7~/^r1\./{t=$7} END{print t}' cookies.txt)

curl -s -b cookies.txt -X PUT \
  -H "Content-Type: application/json" -H "X-XSRF-TOKEN: $CSRF" \
  -d '{
        "passwordMinLength": 14,
        "passwordRequireUppercase": true,
        "passwordRequireDigit": true,
        "passwordHistoryCount": 5,
        "breachedPasswordCheck": true,
        "lockoutEnabled": true,
        "maxLoginFailures": 5,
        "lockoutDurationSeconds": 900
      }' \
  "$HELIX_URL/admin/realms/$REALM/settings"

Full endpoint set

Method & path (under /admin/realms/{realm}) Purpose
GET /settings · PUT /settings Read / update realm settings (password, lockout, CAPTCHA, sessions, and more)
GET · PUT /users/{userId} Read / update a user, including required actions such as update password

See the API reference for the complete settings schema.

See also