Users and roles

Every person who signs in to Botream has a user account with one or more roles. A role is a set of permissions; a user may do what any of their roles allows. The permissions decide which pages people see and what the server lets them do.

#Roles

Botream starts with four roles. Administrators can change them and add their own under Administration → Roles.

Admin is built in: it cannot be renamed, changed or deleted, and at least one active user always keeps it. Developer, Runner and User are ordinary roles: rename them, change their permissions or delete them when nobody has them any more.

#Permissions

These are the permissions a role can have. The server checks them on every request, and a change applies at once: people do not need to sign in again. Their menu follows when they come back to the Botream tab (or within a few minutes).

Everyone who signs in sees the dashboard and their Inbox, whatever their roles.

#Pages and permissions

The menu shows only the pages a user's permissions open:

#Manage roles

Open Administration → Roles. The list shows each role with its description, how many permissions it has (Admin: All permissions), its directory groups and how many active users have it.

• New role opens the role form: Name (unique, at most 50 characters), Description, the Permissions grouped as in the table above (tick a group's box to tick all of it; each permission says what it allows) and Directory groups (see Directory sign-in).
• Edit opens the same form, with the users who have the role. For Admin only the description and the directory groups can change.
• Delete removes a role nobody has (deactivated users count too). Vault access given to the role ends with it. Admin cannot be deleted.

Tip: Make roles from what people do, for example Finance operator with Run tasks, and give a vault to that role. Someone who also builds tasks gets Developer as a second role.

#Manage users

Open Administration → Users. The list shows each user's name, username and email, Roles, Status (Active or Inactive) and Last login. Search by name, username or email.

#Add a user

Click Add user and fill in the New user dialog:

#Edit a user

Choose Edit in the row's menu, or double-click the row. Leave New password blank to keep the current password.

A change of roles applies to the user's next click; they stay signed in. Changing a user's password, or deactivating them, signs them out on every device at once.

Note: You cannot remove the Admin role from yourself or deactivate your own account, and at least one active user must always keep the Admin role.

#Deactivate a user

Choose Deactivate in the row's menu. The user is signed out immediately and can no longer log in. Users are never deleted: their history, such as the runs they started and their audit entries, stays intact. To let them back in, edit the user and switch Active on.

#Directory sign-in (Active Directory / LDAP)

People can sign in with their Active Directory (or other LDAP directory) user name and password instead of a password kept by Botream. Set it up under Administration → Settings → Directory (LDAP):

Which roles directory users get is set on the roles: open a role under Administration → Roles and enter its Directory groups, as group names (for example Botream Admins) or full DNs. * gives the role to every directory user.

• People sign in as ali, COMPANY\ali or ali@company.local. The directory checks the password; Botream never stores it.
• The first sign-in creates the Botream account (name and email from the directory). Every sign-in sets the roles again from the groups: the person gets every role whose directory groups include one of their groups, nested groups included in Active Directory. Someone who gets no role cannot sign in.
• On Users, directory accounts carry a Directory tag. Their password and roles cannot be changed in Botream; Deactivate keeps them out.
• A local account is never taken over by a directory account of the same name.
• Test sign-in on the settings card tries an account with the saved settings and shows its groups and the roles it would get, without creating anything.

Note: Before roles had directory groups, the groups were four settings (Admin, Developer, Runner and User groups). An upgrade moves them to the directory groups of those four roles.

Tip: Keep one local Admin account, so you can still sign in when the directory cannot be reached.

#Password policy

Passwords must:

• be 8 to 128 characters long,
• contain at least one letter,
• contain at least one digit.

Passwords are stored only as bcrypt hashes; nobody, administrators included, can read them.

#Signing in and sessions

• Sign in with your username and password. A failed sign-in does not tell whether the username exists.
• Sign-in attempts are rate limited per minute (10 by default), so passwords cannot be guessed quickly.
• After sign-in, the browser holds a short-lived access token (15 minutes by default) and a refresh cookie (7 days by default) that renews it in the background. You stay signed in while you use Botream, also across tabs.
• Sign out in the user menu (top right) ends the session.
• If a refresh token that was already used is presented again, Botream treats it as stolen: it ends all sessions of that user and records the event in the audit log.

The token lifetimes and the sign-in rate limit are part of the server's configuration file; see Install the server.

#Audit

Sign-ins (successful and failed), sign-outs, refresh-token reuse, user creation, changes (with the roles before and after) and deactivation, and roles created, changed and deleted are recorded in the audit log. Failed sign-ins include the reason, for example an unknown user, a wrong password, a directory account that gets no role or an unreachable directory. Test sign-in on the settings page is recorded too.