Skip to main content

Local administrator

The local administrator is a single password sign-in that does not depend on any directory. You use it to set Delegaris up before Active Directory or Entra ID is connected, and to get back in if the directory connection ever breaks. It is the break-glass way in.

Turning it on​

Set a password in the settings file: .env with Docker, or /etc/delegaris/delegaris.env with the Linux package (where the installer has already set a random one):

LOCAL_ADMIN_PASSWORD=choose-a-long-password

Then restart Delegaris: docker compose up -d with Docker, or sudo systemctl restart delegaris with the Linux package. The sign-in page then accepts the username admin with that password.

SettingDefaultPurpose
LOCAL_ADMIN_PASSWORDnoneThe password. While it is set, the local administrator works
LOCAL_ADMIN_USERNAMEadminThe username to type
LOCAL_ADMIN_EMAILnoneAn email address, so the local administrator can receive Slack messages, for example while testing

The password and username can only be set in the settings file, never in the web UI.

What it can do​

  • It is always an administrator, with every right on every resource and every setting.
  • It shows as "Local administrator", signed in with "the local administrator account".
  • It works whatever is chosen under Settings > Sign-in or in AUTH_PROVIDERS. Even if you tick only Active Directory, or set AUTH_PROVIDERS=ldap, the local administrator stays on while its password is set.

Settings > Sign-in > Ways in shows Local administrator (admin) with On or Off, and Settings > Access > Administrators and auditors lists it as an administrator "set in the service's environment". Neither can be changed in the UI.

When Entra ID signs people in automatically​

If Entra ID is the only other way in and Skip the sign-in page and go straight to Microsoft is on, opening Delegaris goes straight to Microsoft. To reach the password form, open:

https://<your host>/?manual=1

Keeping it safe​

  • Use a long, unique password. Wrong passwords are throttled like any other password sign-in (see How sign-in works).
  • Require two-step sign-in for administrators, which covers the local administrator. See Two-step sign-in.
  • Every sign-in is recorded in the activity log, as user admin, via local.
  • While it is on, Delegaris logs a reminder at every start that the local administrator sign-in is enabled.

Keep LOCAL_ADMIN_PASSWORD set as the break-glass sign-in, with the password kept safe and two-step sign-in on, so there is always a way in. Remove it only if you do not want a break-glass account (below).

Removing it​

  1. Make sure someone else can administer Delegaris: an Administrator groups or Administrator users entry under Settings > Sign-in, or ADMIN_GROUPS / ADMIN_USERS in the settings file. Sign in as that person and check you see Settings in the top bar.
  2. Remove LOCAL_ADMIN_PASSWORD from the settings file (.env, or /etc/delegaris/delegaris.env).
  3. Restart Delegaris (docker compose up -d, or sudo systemctl restart delegaris).
warning

With the local administrator gone, a broken directory connection means nobody can sign in until the directory is fixed or LOCAL_ADMIN_PASSWORD is set again.

Locked out by two-step sign-in​

If the local administrator has two-step sign-in set up and the phone is lost, and no recovery code is to hand, reset it from the host. With Docker, from the folder with your docker-compose.yml:

docker compose exec delegaris python -m app.mfa reset admin

With the Linux package:

sudo delegaris mfa reset admin

The next sign-in as admin sets two-step sign-in up again if it is required, or signs in with the password alone if it is not. See Two-step sign-in.

To change the local administrator's password, change LOCAL_ADMIN_PASSWORD in the settings file and restart Delegaris, as under Turning it on.