Creating the First Administrator

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.

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.

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:

1. create_account creates the account used to log in.
2. 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"

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.

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:

• KeyCloak
• AWS Cognito
• Google
• Azure AD / Entra ID

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.

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.

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.