Stroom – account

Docs: User Accounts

Wed, 29 Jul 2026 00:00:00 +0000

Note

If Stroom is configured to use an external Identity Provider (IDP) Identity Provider (IDP) An Identity Provider is a system or service that can authenticate a user and assert their identity. Identity providers can support single sign on (SSO), which allows the user to sign in once to the Identity Provider so they are then authenticated to all systems using that IDP.Click to see more details… (e.g. Azure Active Directory or AWS Cognito) then all user accounts are managed within that Identity Provider (IDP) Identity Provider (IDP) An Identity Provider is a system or service that can authenticate a user and assert their identity. Identity providers can support single sign on (SSO), which allows the user to sign in once to the Identity Provider so they are then authenticated to all systems using that IDP.Click to see more details… and the Manage Accounts screen in Stroom will not be available. For more details about external Identity Providers, see Open ID Connect.

Accounts vs Stroom Users

See Accounts vs Users for details on the difference between a Stroom User Account and a Stroom User.

Creating User Accounts

User accounts can only be created by a user that holds the Manage Users or Administrator Application permission Application permission This is a permission that is not specific to a single document. It applies to all documents or is not related to documents in any way.Click to see more details....

Create a new user account by selecting

from the main menu.

As a minimum a user account must have a unique identifier that will be used to identify them in Stroom.

If the user’s email address is added then Stroom will be able to email the user to reset their password. This functionality is configured using the properties starting with this prefix stroom.security.identity.email..

Account States

An account has three states and they are independent of one another. An account can be locked and disabled at the same time, or inactive and disabled, and so on. Each is shown as its own column in the Manage Accounts screen because each answers a different question.

The quickest way to keep them apart is to ask what creates each state, because that also tells you what can clear it.

State	What it is	Set by	Cleared by
Disabled	A decision. An administrator has said this account may not be used.	An administrator	An administrator
Locked	A defence. Stroom has reacted to repeated wrong passwords.	Stroom	Time, a password reset, or an administrator
Inactive	An observation. Nobody has used this account for some time.	Stroom	A successful sign in, or an administrator

An account in any of these three states cannot sign in.

Enabled and Disabled

This is the administrator’s control over whether an account may be used at all. It is the only one of the three states that an administrator sets directly.

Disabling an account prevents any further sign in, immediately. A disabled account cannot be recovered by the user under any circumstances. Waiting will not release it and a password reset will not release it. This makes disabling the right action whenever someone must be prevented from signing in, whether temporarily, for example while they are on extended leave, or permanently.

Warning

Disabling an account stops that person signing in again. It does not end the sessions they already hold, nor revoke the tokens they are already using, so somebody who is signed in at the time may carry on working.

To end access that is already in progress, disable the corresponding Stroom User User Refers to a Stroom User that is linked to either an Account in Stroom’s internal Identity Provider or a user account in an external Identity Provider. A Stroom User is primarily concerned with authorisation (i.e. application/document permissions and group memberships) rather than authentication, though disabling one also refuses that person at authentication and ends any access they currently hold.Click to see more details… rather than, or as well as, the account. Disabling a user ends their sessions across the cluster and revokes their tokens. See Sessions and Tokens for how the two differ and when each is appropriate.

Locked

An account is locked automatically after a number of consecutive failed sign in attempts, controlled by stroom.security.identity.failedLoginLockThreshold. It is a defence against password guessing and nothing more.

An administrator cannot lock an account. To prevent someone using Stroom, disable their account instead.

While an account is locked, further sign in attempts are refused without the password being checked at all, and those attempts are not counted against the account. Continued guessing therefore reveals nothing and does not extend the lock.

There are three ways an account becomes usable again.

Waiting. The lock lapses on its own after stroom.security.identity.failedLoginLockDuration, which is thirty minutes by default. Nothing needs to happen when it lapses. The next sign in with the correct password simply succeeds. The message shown to the user says roughly how long remains, so in a default configuration a locked user does not need to contact anybody.
Resetting their password. If stroom.security.identity.allowLockedAccountPasswordReset is enabled then the user can request a password reset email and set a new password, which unlocks the account at the same time. This is described in Signing In.
An administrator unlocking it. A user holding the Manage Users or Administrator Application permission Application permission This is a permission that is not specific to a single document. It applies to all documents or is not related to documents in any way.Click to see more details... can use the Unlock action in the Manage Accounts screen.

Setting failedLoginLockDuration to zero means locks never lapse, in which case one of the other two routes is the only way back. The duration is applied when a sign in is attempted rather than when the lock is created, so changing this property also changes locks that are already in force.

Inactive

The Account Maintenance job marks an account as inactive when it has not been used for some time. This happens in one of two cases:

A brand new account that has never been signed into was created longer ago than stroom.security.identity.passwordPolicy.neverUsedAccountDeactivationThreshold.
An account has not been signed into for longer than stroom.security.identity.passwordPolicy.unusedAccountDeactivationThreshold.

Accounts flagged as never expires are exempt, as are accounts that have been reactivated recently, so that reactivating an account does not simply see it deactivated again on the job’s next run.

As with locking, an administrator cannot mark an account as inactive. Disabling is the control for preventing access.

How an inactive account becomes usable again depends on stroom.security.identity.reactivateInactiveAccountsOnLogin.

When it is disabled, which is the default, an administrator must use the Reactivate action in the Manage Accounts screen.
When it is enabled, presenting a valid credential reactivates the account and signs the user in, in one step. This applies equally to a correct password and to a valid certificate.

A disabled account is never reactivated automatically. Reactivation only happens once a credential has been accepted, and a disabled account never gets that far.

Administrator Actions

The Manage Accounts screen offers the following actions to a user holding the Manage Users or Administrator Application permission Application permission This is a permission that is not specific to a single document. It applies to all documents or is not related to documents in any way.Click to see more details....

Action	Effect
Disable / Enable	Prevents or restores the ability to sign in. Does not end sessions already in progress.
Unlock	Clears a failed sign in lock.
Reactivate	Clears the inactive state.
Set password	Sets a new password, optionally requiring the user to change it at their next sign in.

There is deliberately no action to lock an account or to mark one as inactive. Those two states are applied by Stroom in response to something it has observed, and an administrator wanting to prevent access should disable the account.

Requiring a password change at the next sign in can safely be combined with setting a password in the same save. The requirement is kept rather than being cleared by the password change.

Docs: Signing In

Wed, 29 Jul 2026 00:00:00 +0000

This page describes what a user experiences when signing in to Stroom using its internal Identity Provider (IDP) Identity Provider (IDP) An Identity Provider is a system or service that can authenticate a user and assert their identity. Identity providers can support single sign on (SSO), which allows the user to sign in once to the Identity Provider so they are then authenticated to all systems using that IDP.Click to see more details....

Note

None of this applies when Stroom is configured to use an external Identity Provider (IDP) Identity Provider (IDP) An Identity Provider is a system or service that can authenticate a user and assert their identity. Identity providers can support single sign on (SSO), which allows the user to sign in once to the Identity Provider so they are then authenticated to all systems using that IDP.Click to see more details…. In that case sign in, password policy and account recovery are all handled by that provider. See Open ID Connect.

Signing in with a Password

The outcome of a sign in attempt depends on the state of the account as well as the password.

Situation	What the user is told
Correct password, account in good order	Signed in. Any earlier failed attempts are forgotten.
Wrong password	Invalid credentials. The failure is counted towards locking the account.
Account disabled	The account is disabled and they should contact an administrator.
Account locked	The account is locked, together with the quickest way to recover it.
Account inactive, correct password	Either signed in, or told the account has been deactivated. See User Accounts.

A wrong password and a user id that does not exist produce exactly the same answer, so the sign in screen cannot be used to discover which accounts exist.

For a disabled or locked account the password is not checked at all. Neither state can be talked out of with a correct password, so there is nothing to be gained by checking one, and refusing without checking means the sign in screen cannot be used to test whether a password is correct.

Failed attempts against a disabled or locked account are not counted, because the account is already refused.

Being Asked to Change Your Password

A user may be signed in successfully and then be required to set a new password before they can do anything else. This happens in three cases:

It is their first ever sign in and stroom.security.identity.passwordPolicy.forcePasswordChangeOnFirstLogin is enabled, which it is by default.
An administrator has set a new password for them and asked that it be changed.
Their password is older than stroom.security.identity.passwordPolicy.mandatoryPasswordChangeDuration.

The new password must satisfy the password policy, which is applied by the server on every route that sets a password. The previous password cannot be reused.

Getting Locked Out

After a number of consecutive wrong passwords, controlled by stroom.security.identity.failedLoginLockThreshold, the account is locked.

The message shown to a locked user depends on how the system is configured, and always gives them the cheapest way back in.

Configuration	What the user is told
Locks lapse on their own, which is the default	To try again in approximately so many minutes.
Locks lapse and self service reset is enabled	The same, plus a pointer to Forgot password?
Locks never lapse (`failedLoginLockDuration` is zero)	To contact an administrator.
Locks never lapse and self service reset is enabled	To use Forgot password? or contact an administrator.

An administrator is only named where an administrator really is the only way back. In a default configuration a locked user is told to wait, which avoids a support request for something that resolves itself.

See User Accounts for the three ways an account becomes usable again.

Resetting a Forgotten Password

If the user has an email address recorded against their account, and stroom.security.identity.passwordPolicy.allowPasswordResets is enabled, they can use Forgot password? on the sign in screen to be emailed a link for setting a new password.

The response shown on screen is the same whether or not the address belongs to an account, so this screen cannot be used to discover which email addresses have accounts.

The link is valid for stroom.security.identity.token.emailResetTokenExpiration, ten minutes by default, and can be used only once. Requesting another link invalidates any earlier one. Repeated requests are rate limited by stroom.security.identity.passwordResetRequestCooldown.

Completing a reset ends all of that user’s existing sessions everywhere in the cluster. They then sign in with their new password.

When a Reset Cannot be Completed

Some accounts cannot be recovered this way. Rather than sending a link that would not work, Stroom emails the account holder to say that the reset cannot currently be completed and that they should contact an administrator if it continues.

This happens when:

The account is disabled. Only an administrator can enable it again.
The account is locked and stroom.security.identity.allowLockedAccountPasswordReset is not enabled. Note that a lock which has already lapsed does not prevent a reset.
The account is inactive and stroom.security.identity.reactivateInactiveAccountsOnLogin is not enabled. Without it, setting a new password would not be enough to sign in, so an administrator has to reactivate the account first.

The email is deliberately the same in all three cases and does not say which one applies. It goes to the address held against the account, so it tells the account holder something is wrong without telling whoever made the request anything at all.

No email of any kind is sent when there is nobody to send it to, that is when the address matches no account, the account has no email address recorded, password resets are turned off, or an email was already sent within the cool-down period.

Signing in with a Certificate

If stroom.security.identity.allowCertificateAuthentication is enabled, a user presenting a valid certificate can be signed in without typing a password. The user id is taken from the certificate’s common name using stroom.security.identity.certificateCnPattern and stroom.security.identity.certificateCnCaptureGroupIndex.

A valid certificate is treated in exactly the same way as a correct password. The same account states apply in the same order, so a disabled or locked account is still refused, and an inactive account is either reactivated or refused depending on stroom.security.identity.reactivateInactiveAccountsOnLogin.

Stroom – account

Docs: User Accounts

Note

Accounts vs Stroom Users

Creating User Accounts

Account States

Enabled and Disabled

Warning

Locked

Inactive

Administrator Actions

See Also

Docs: Signing In

Note

Signing in with a Password

Being Asked to Change Your Password

Getting Locked Out

Resetting a Forgotten Password

When a Reset Cannot be Completed

Signing in with a Certificate

See Also