Docs: Creating the First Administrator

Tue, 11 Aug 2026 00:00:00 +0000

A new Stroom installation normally has no administrator. Until one exists, nobody can log in and set the system up, so this is a required step for most installations.

This page covers how to create that first administrator from the command line. Once you have one, all further users, groups and permissions can be managed from within the Stroom user interface.

Do You Need to Do This?

You do not need to do this if either of the following applies:

You are running the stroom_core_test Docker stack, which is pre-configured with an admin account (password admin). See Single Node (Docker).
You have set stroom.security.identity.autoCreateAdminAccountOnBoot to true before first boot, in which case Stroom creates the admin account for you. This property defaults to false. See Internal IDP.

Everyone else needs to create an administrator manually.

Note

autoCreateAdminAccountOnBoot only has an effect on a fresh database. Setting it on an installation that has already started will not retrospectively create the account, so use this page instead.

Which Procedure Do You Need?

If you have not started Stroom yet, follow the section matching the 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... you have configured, either Internal IDP or External IDP.

If you have already started Stroom and hit a problem, use this table to find the right one.

Symptom	Cause	What to do
You reach the Stroom login page but have no credentials that work	Using the internal 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 no account Account Refers to a user account in Stroom’s internal Identity Provider. An Account holds the credentials a person authenticates with, and exists only where Stroom is its own Identity Provider, unlike a User which exists in every deployment.Click to see more details... exists	Internal IDP below
You can sign in via your identity provider, but Stroom shows no content and you cannot create anything	Using 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... and no 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... exists for your identity, or it has no permissions	External IDP below

The two cases differ because Stroom separates authentication from authorisation:

An Account is an identity used to log in. Accounts only exist in Stroom when the internal IDP is used; with an external IDP the accounts live in that provider.
A Stroom user is the entity that holds group memberships and permissions. One is always needed, whichever IDP is in use.

Before You Start

You will need:

Shell access to a Stroom node as the processing user, e.g. stroomuser.
Stroom not running on that node. Each command runs in its own JVM and is not intended to be run against a live node.
For an external IDP, the unique identifier of the person who will be the administrator, as held by that provider. See Finding the user’s identifier on an external IDP.

The commands below are shown in two forms. Use whichever matches your installation:

Zip distribution - java -jar /absolute/path/to/stroom-app-all.jar COMMAND [ARGS] path/to/config.yml
Docker stack - ./command.sh COMMAND [ARGS] run from the root of the stack directory. The script supplies the config file path for you, so do not pass one.

Internal IDP

This is the default configuration, where Stroom manages its own accounts.

Creating an administrator takes two commands, because an account and a Stroom user are two different things:

create_account creates the account used to log in.
manage_users creates the Stroom user, creates an Administrators group holding the Administrator application permission, and puts the user in that group.

Assuming you want to set up johndoe as an administrator:

Step 1 - Create the Account

java -jar /absolute/path/to/stroom-app-all.jar \
create_account \
--user johndoe \
--firstName John \
--lastName Doe \
--password "correct horse battery staple" \
path/to/config.yml

Or, in a Docker stack:

./command.sh \
create_account \
--user johndoe \
--firstName John \
--lastName Doe \
--password "correct horse battery staple"

By default Stroom will require this password to be changed at first login, governed by stroom.security.identity.passwordPolicy.forcePasswordChangeOnFirstLogin. Pass --noPasswordChange if you do not want that.

Step 2 - Create the Stroom User and Grant Permissions

java -jar /absolute/path/to/stroom-app-all.jar \
manage_users \
--createUser johndoe \
--createGroup Administrators \
--addToGroup johndoe Administrators \
--grantPermission Administrators "Administrator" \
path/to/config.yml

Or, in a Docker stack:

./command.sh \
manage_users \
--createUser johndoe \
--createGroup Administrators \
--addToGroup johndoe Administrators \
--grantPermission Administrators "Administrator"

Warning

The username must match exactly between --user (in create_account), --createUser and --addToGroup (in manage_users). A mismatch produces an account that can log in but has no permissions.

To set up more than one administrator, repeat the create_account command for each person and pass the extra --createUser/--addToGroup arguments in a single manage_users command:

java -jar /absolute/path/to/stroom-app-all.jar \
manage_users \
--createUser johndoe \
--createUser janedoe \
--createGroup Administrators \
--addToGroup johndoe Administrators \
--addToGroup janedoe Administrators \
--grantPermission Administrators "Administrator" \
path/to/config.yml

External IDP

Where a 3rd party identity provider holds the accounts, you only need to create the Stroom user, not an account. The provider is responsible for the credentials.

Warning

Do not run create_account or reset_password when using an external IDP.

Finding the User’s Identifier on an External IDP

Stroom links a Stroom user to an identity on the provider using a single claim from the authentication token. Which claim is used is set by stroom.security.authentication.openId.uniqueIdentityClaim, which defaults to sub.

Establish that claim first, then find its value for the person who will be the administrator. Depending on the provider, the value may look like a UUID UUID A Universally Unique Identifier for uniquely identifying something. UUIDs are used as the identifier in Doc Refs. An example of a UUID is 4ffeb895-53c9-40d6-bf33-3ef025401ad3.Click to see more details..., an email address, or something else.

The provider-specific pages describe where to find this value:

Create the Stroom User and Grant Permissions

Assuming the unique identifier for John Doe is b6e06181-9e10-44eb-a33a-537509ec3abd:

subject_id="b6e06181-9e10-44eb-a33a-537509ec3abd"; \
java -jar /absolute/path/to/stroom-app-all.jar \
manage_users \
--createUser "${subject_id},johndoe,John Doe" \
--createGroup Administrators \
--addToGroup "${subject_id}" Administrators \
--grantPermission Administrators "Administrator" \
path/to/config.yml

The johndoe and John Doe parts are the optional display name and full name. They are there so the Stroom user interface shows something more human friendly than a UUID. They are only initial values and are overwritten with the values from the provider when the user first logs in. See USER_IDENTIFIER for the format of this argument.

Note

Ideally run this before the administrator first logs in. If they have already logged in then Stroom will have created a user for them automatically, and --createUser will leave that user alone, other than re-enabling it if it had been disabled. The --addToGroup and --grantPermission arguments are what actually give them access.

Verifying it Worked

Start Stroom, then log in as the new administrator.

If the login succeeds and the main menu includes

then the user has the Administrator application permission and the setup is complete.

If you can log in but see nothing and the Security menu is missing or sparse, the account exists but the Stroom user has no permissions. Re-check that the identifiers matched exactly, then re-run the manage_users command. It is idempotent, so it is safe to run again.

Warning

If manage_users was run while Stroom was running, the new permissions may not take effect immediately because user permissions are cached. Without Administrator rights you cannot clear the caches from the user interface, so either wait for the cache entries to expire or restart Stroom.

What to Do Next

Now that you have an administrator you can manage everything else from within Stroom:

User Accounts - creating further accounts (internal IDP only).
Users and Groups - creating users and groups.
Application Permissions - granting permissions.

Stroom – install

Docs: Creating the First Administrator

Do You Need to Do This?

Note

Which Procedure Do You Need?

See Also

Before You Start

See Also

Internal IDP

Step 1 - Create the Account

Step 2 - Create the Stroom User and Grant Permissions

Warning

External IDP

Warning

Finding the User’s Identifier on an External IDP

Create the Stroom User and Grant Permissions

Note

Verifying it Worked

Warning

What to Do Next