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¶
In the console¶
Password, lockout, breach-check, CAPTCHA and session-limit controls are all realm-level settings on Realm settings, spread over three tabs.
- Open Realm settings → Login. Under Login security, set Minimum password length.
- 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.
- Turn on Check breached passwords to reject known-breached passwords even when they satisfy the rules.
- Under CAPTCHA, optionally choose a CAPTCHA provider (Cloudflare Turnstile or Google reCAPTCHA v2) and its Site key and Secret key.
- 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.
- Open Realm settings → Tokens & sessions to set Max concurrent sessions and Evict oldest session under Concurrent sessions.
- 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¶
{
"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.