Password Policy & Lockout¶

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

What it is¶

Helix IAM 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.

In the console¶

Password, lockout, breach-check, CAPTCHA and session-limit controls are all realm-level settings, edited from Authentication → Password policy & lockout.

Open Authentication → Password policy & lockout.
Set the password rules — minimum length, required character classes, "not the username", and how many previous passwords to remember.
Enable breached-password detection (HIBP) to reject known-breached passwords even when they satisfy the rules.
Turn on account lockout and set the failure threshold, lockout duration, and failure-reset window (or make lockout permanent).
Optionally configure a CAPTCHA provider and a concurrent-session limit.
Save — changes apply to the next registration, password change, and sign-in.

To force an individual user to remediate, open the user's record and add the update password Required Action; 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=="XSRF-TOKEN"{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.