Users and roles

Every person who signs in to the console holds exactly one role. The role decides what they can see and change. Gardience also uses two service identities of its own, which no person can take.

The roles#

A "grant" below is a permission in the Salt master's access list. Operators, approvers and help desk users get grants written as gdn:<function>. Salt never matches these against a real function, so their own Salt session is read-only. Gardience reads the grants when they sign in, checks approvals, change windows and locks, and only then runs the change as its automation identity. The audit log records the person who asked.

The read access that operators and approvers share covers: test.ping, grains.items, grains.item, grains.get, grains.ls, pkg.list_upgrades, pkg.list_pkgs, service.status, service.get_all, win_wua.list, gardience.baseline, gardience.inventory and job results.

Two rules apply to every role:

• The person who launches a run can never approve it. Someone else with the admin or approver role must.
• Gardience records a person's grants when they sign in. A role change takes effect at their next sign-in. Sessions last 8 hours for local accounts (session_hours in config/users.yaml) and 1 hour for LDAP and single sign-on accounts (directory_session_hours), so directory changes apply within the hour. gardience user del, a role change and gardience user passwd end that person's open sessions at once; gardience user signout NAME (or --all) does it on demand.

Service identities#

Gardience creates these at install. They are not people and cannot be removed.

Their passwords are random and stored in the install's .env file (SVC_PASS and AUTOMATION_PASS).

Team scopes#

A team scope limits a person to some node groups: they see and change only the machines in them. Use it when one team runs the web servers and another the databases, or a contractor looks after one site. People without a scope see the whole fleet. Admins are never limited, because they manage scopes.

sudo /opt/gardience/gardience user scope sam "Web servers,Web staging"   # limit sam to two node groups
sudo /opt/gardience/gardience user scope sam --clear                    # the whole fleet again
sudo /opt/gardience/gardience users                                     # who is limited to what

The groups are any node groups on the Groups page, built in or your own. The new limits apply from the person's next sign-in (setting a scope ends their open sessions). For single sign-on, set Limit to node groups on the group mapping instead; see Single sign-on.

What a limited person gets:

• Pages that list machines show only theirs: the dashboard, Machines and each machine's page, Vulnerabilities and its export, Jobs and each job (with only their machines' results), runs, fixes in progress, and the audit log export (entries they made, or about their machines or groups only).
• Changes reach only their machines: a runbook or command must target one of their node groups or machines inside them, the one-click fixes refuse other machines, and they can approve only runs on their groups. Workflows span several groups, so an admin starts those.
• Ask Gardience looks things up within their scope only.
• Their own Salt session (the raw Salt view) can read only their machines, and nothing fleet-wide: no grains cache, key list or other machines' job results. Single sign-on users limited this way have no direct Salt reads at all.
• Everything else is refused with a message: settings, the full audit log, reports and evidence packs, the daily briefing, inventory and other whole-fleet pages. A page added in a later release stays refused for them until it is made scope-aware, so an upgrade cannot widen what they see.
• Once anyone has a scope, a person Gardience has no record of (not in users.yaml and not a known single sign-on person) sees no machines at all, rather than the whole fleet. The one exception is a directory group entry (users.yaml names ending in %): its members keep the whole fleet only while no such group has a scope. Add people to users.yaml, or give their group a scope, to set what they see. On an all-in-one install this exception is safe because Salt admits only the people and groups in users.yaml, so an unlisted person who signs in is a member of one of those groups. In attach mode your own Salt master decides who signs in, so the exception does not apply: once anyone is limited, a person not listed in users.yaml sees no machines.

If a group's membership cannot be worked out (the Salt master is restarting), the limited person's request is refused for a moment rather than shown unfiltered. The release check signs in as a limited person, calls every read route the console has, and fails if any machine outside the scope appears.

Manage accounts on an all-in-one install#

An all-in-one install runs its own Salt master. Accounts live in config/users.yaml in the install directory. Run these commands as root (or as a user that can run Docker) from any directory, using the full path to the gardience command (/opt/gardience/gardience by default).

To list accounts:

/opt/gardience/gardience users

Each line shows the name, the role and the sign-in type (file for a local account, ldap for a directory account).

To add a local account:

1. Run:

   Copy

   /opt/gardience/gardience user add alice operator

2. Copy the password it prints. It is 20 random characters and is shown once.
3. Give the password to the person over a safe channel.

To add a directory (LDAP or Active Directory) account, set up the directory first (see Single sign-on), then:

/opt/gardience/gardience user add alice operator --ldap

No password is created. The person signs in with their directory password.

Everyone with a local account can change their own password in the console: select your name at the top of any page (Your account), enter the current password and the new one. The change takes effect within about 15 seconds and signs out your other open sessions. Directory and single sign-on accounts change their password in the directory.

Your account also lists where you are signed in right now (when each session started, its address, and its browser) with Sign out everywhere else, which ends every session but the one you are using. Admins see everyone's open sessions under Your account > Signed in now and can sign out any one of them; that is recorded in the audit log.

An admin can reset someone else's local password under Your account > People > Reset password. Gardience shows a one-time password once; give it to the person over a safe channel. Their open sessions end, and at their next sign-in every page asks them to choose their own password before anything else. Changes, refused attempts and resets are written to the audit log.

To set a new password for a local account from the server:

/opt/gardience/gardience user passwd alice

The new password is printed once.

To change someone's role, run user add again with the same name and the new role. This replaces the account and, for a local account, prints a new password.

To remove an account:

/opt/gardience/gardience user del alice

Removal takes effect in two steps:

• The person's API keys stop working at once.
• Any console session they already have ends within the hour, when it expires.

Each of these commands rewrites the Salt master's permissions and restarts the Salt master and the Gardience service, then waits for the console to answer.

Password rules#

Local passwords must be at least 12 characters. The commands above always generate a 20-character password. Gardience stores only a SHA-512 crypt hash.

Manage admins and approvers in attach mode#

In attach mode, Gardience uses a Salt master you already run. People and their Salt rights live in that master's external_auth settings, not in Gardience (see Attach to an existing Salt master). Gardience only needs to know who administers it and who may approve runs.

To see the current lists:

/opt/gardience/gardience roles

To set them:

/opt/gardience/gardience roles --admins alice --approvers bob,carol

Points to know:

• Admins can always approve. Gardience adds every admin to the approver list for you.
• Give both options each time. If you give only --admins, the approver list becomes the admins alone. If you give only --approvers, the current admins are kept.
• Names may use letters, digits, _, ., @ and -.
• The service reads the lists live. No restart is needed.
• On an all-in-one install this command only shows the lists. To change them there, use gardience user add.

You can also set both lists at install time with the installer's --admins and --approvers options. See Installer options.

Reserved names#

These names belong to Gardience. Nobody can be created with them, sign in with them, or arrive with them through single sign-on. The match ignores case.

• automation
• gardience, and any name starting with gardience-
• any name starting with schedule

Only gardience-scanner and gardience-automation can hold the scanner and automation roles.

One-time codes (MFA) for local accounts#

Local and directory accounts can add a second factor: a 6-digit code from any authenticator app (Microsoft Authenticator, Google Authenticator, 1Password, Authy and others: the standard time-based codes, RFC 6238).

sudo /opt/gardience/gardience user mfa alice        # prints the setup key once, and an otpauth:// link
sudo /opt/gardience/gardience user mfa alice off    # remove it (for a lost phone; then set a new one)
sudo /opt/gardience/gardience mfa require admin,approver   # these roles cannot sign in without a code
sudo /opt/gardience/gardience mfa require none

• On the sign-in page the person selects Use a one-time code under the password and types the code. People without a key never see the box.
• Each code works once, for about a minute; a wrong or missing code gets the same answer as a wrong password, and counts towards the sign-in throttle. Every refusal is in the audit log.
• Keys are kept sealed in the vault, never in plain text.
• With a role required, an account in that role that has no key yet is refused (and told to ask an admin), even with the right password.
• Single sign-on users get MFA from your identity provider; Gardience does not ask them for a second code.
• API keys and the gdn command line use their own keys, not passwords, so no code is asked for.

Single sign-on users#

People who sign in through single sign-on do not appear in users.yaml. Their role comes from their identity provider groups at each sign-in. A single sign-on name that matches a local account is refused, so the two can never be confused. See Single sign-on.

Break-glass account#

For an emergency that the governed path cannot handle, root on the Gardience server can open a break-glass account with full Salt rights for a limited time:

sudo /opt/gardience/gardience breakglass on --minutes 60     # prints a one-time password
sudo /opt/gardience/gardience breakglass status
sudo /opt/gardience/gardience breakglass off                  # close it early

Sign in as gardience-breakglass with the one-time password (method: Local account). Gardience records the opening in the audit log, sends a notification, and when the time is up discards the password and ends the account's sessions. Nobody can be given the break-glass role, and single sign-on cannot map to it. Opening it needs root on the server, so a stolen console session or API key can never reach raw Salt rights.

Related#

• Single sign-on
• API keys and the REST API
• Security model
• CLI reference