Managing Passwords
Fuzzball provides two password management workflows: users can change their own password through a self-service flow, and organization owners can reset a member’s password on their behalf. Fuzzball checks every new password against the requirements below, and Keycloak also applies its realm password policy and handles reauthentication.
Password management applies only to users who authenticate directly with Fuzzball. If your organization uses an upstream identity provider (SSO or LDAP), manage passwords through that provider instead.
Every password a user chooses, and every password an owner sets for a member, must:
- Be at least 12 characters long
- Contain at least one uppercase letter, one lowercase letter, one digit, and one special character (any character that is not a letter or digit, including a space)
- Not contain the word
fuzzballin any case - Not be the same as the user’s username or email address
- Not match any of the user’s 10 most recent passwords (enforced by the Keycloak realm policy; see below)
Passwords submitted through Fuzzball (the web UI Change Password dialog, the web UI and CLI
member and password reset forms, the API, the sign-up page, and the invitation page) are also
rejected if they contain the user’s username or email address. Pages that Keycloak hosts, such as
the link printed by fuzzball context update-user --new-password and the password change
required at the next login after a reset, reject only an exact match.
Users in the Fuzzball Local organization do not use Keycloak. Fuzzball checks their passwords against the same requirements, except the password history. When an owner resets a member’s password, the username and email checks are also skipped.
Passwords that were set before these requirements existed keep working. The requirements apply the next time the password changes. The same applies to the organization owner’s initial password taken from the deployment configuration.
Fuzzball sets these requirements as the password policy of each organization’s Keycloak realm, unless the realm already has a policy or Fuzzball uses an external Keycloak. Fuzzball never changes an existing realm policy or any realm on an external Keycloak; that policy, if any, applies to every password change. Passwords submitted through Fuzzball are also checked against every requirement above except the password history, which only the realm policy enforces.
Fuzzball turns on Keycloak brute force detection for the realm of each organization it creates. After 5 failed sign-in attempts, Keycloak locks the user out of the realm. The lock lifts after 15 minutes, and the failure count starts over after 15 minutes without a failed attempt. Two failed attempts less than a second apart lock the user for one minute, even before the fifth. Anyone who can reach the sign-in page can lock an account this way, so a locked user may not be the one who entered the wrong password.
Realms created before this setting existed, and realms on an external Keycloak, are left as they are. To protect an existing realm, turn on brute force detection in the realm’s security defenses settings in the Keycloak admin console. An administrator can also unlock a locked user there before the lock lifts.
Users in the Fuzzball Local organization do not use Keycloak. Fuzzball locks local password sign-in with the same limits; see Initial Login for how to unlock a local account.
Users can change their own password at any time when they know their current password.
- Log into your Fuzzball UI
- Click your user avatar or name in the top right corner and select Change Password
- In the dialog, enter your current password and your new password twice, then click Change password
If your organization uses SSO or LDAP, you will see an informational message directing you to manage your password through your identity provider instead.
- Fuzzball CLI installed with an active context
Run the following command to get a link to the Keycloak password change page:
$ fuzzball context update-user --new-password
Note: If your organization uses SSO or LDAP, manage your password
through your identity provider instead.
Using a secure browser, open the link to change your password:
https://auth.example.fuzzball.ciq.dev/realms/<realm>/protocol/openid-connect/auth?client_id=account-console&code_challenge=...&code_challenge_method=S256&kc_action=UPDATE_PASSWORD&redirect_uri=https%3A%2F%2Fauth.example.fuzzball.ciq.dev%2Frealms%2F<realm>%2Faccount%2F&response_type=code&scope=openidOpen the URL in your browser. Keycloak will prompt you to reauthenticate and then set a new password. After the password is saved, Keycloak opens its Account Console for your realm.
The link uses account-console, a client that Keycloak creates in every realm. If an administrator
has disabled that client, Keycloak shows Client disabled. instead; change your password in the
web UI.
The browser link is printed only for contexts that authenticate through Keycloak (OIDC). On a context using a local account,--new-passwordchanges the password in place: it prompts forCurrent password:, thenNew password:andConfirm new password:, and printsPassword changed successfully.Pass--current-passwordalongside--new-passwordto supply the existing password non-interactively.
Organization owners can reset a member’s password without knowing the current one. Doing so requires organization owner permissions and a Fuzzball CLI context logged in as that owner.
Fuzzball records the audit event before it changes the password. If the event cannot be recorded,
the reset is refused with the audit service is unavailable; try again and the member’s password is
left as it was. Adding a member and creating an organization work the same way. Because the success
event is recorded before the change, a request that is then refused or fails is followed by an error
event with the same activity context id.
By default the reset password is permanent — the user is not required to change it. To force a
password change on next login, pass --require-update-password.
Use the organization member update subcommand with the member’s email address or UUID.
Auto-generate a new password:
$ fuzzball organization member update user2@ciq.com --generate-password
⚠️ GENERATED PASSWORD (save this - it won't be shown again):
riJ@Kb#2#KpV8g*1S7_Q_4^MLp8I^N52
Password reset successfully.Auto-generate and require the user to change it on next login:
$ fuzzball organization member update user2@ciq.com --generate-password --require-update-password
⚠️ GENERATED PASSWORD (save this - it won't be shown again):
riJ@Kb#2#KpV8g*1S7_Q_4^MLp8I^N52
The user will be required to change this password on next login.Set a password interactively:
$ fuzzball organization member update user2@ciq.com --password
Password: ········
Confirm: ········
Password reset successfully.Set a password inline:
$ fuzzball organization member update user2@ciq.com --password='TempPass-2026!'
Password reset successfully.The--passwordand--generate-passwordflags are mutually exclusive. Use--password=VALUEto set a password directly,--passwordwith no value to be prompted for it, or--generate-passwordto have Fuzzball generate one.
The same organization member update subcommand also resets passwords for organization owners:
$ fuzzball organization member update user3@ciq.com --generate-passwordShare the new password with the user.