Break-glass access

Break-glass access is the way in when single sign-on is down or every administrator is locked out. An emergency account is a local account that signs in with its password and second factor only while a break-glass window is open, and only from an address the window allows. The window is opened on the hub’s own host with the backend’s own credential, so it works while every backend is down and nobody can open it from the network.

Create an emergency account#

A platform administrator marks a local account as an emergency account:

$ weikio user create oncall@example.com --display-name "On-call"
$ weikio user set oncall@example.com --break-glass=true

The account stays refused until a window opens. It always gives a code from an authenticator app at sign-in, whatever the installation’s two-factor setting says.

Open a window#

On the hub’s host, in the stack’s folder:

$ docker compose run --rm infra weikio-backend breakglass enable --hours 4 --cidr 203.0.113.7/32 --reason "Entra ID sign-in is down"

--hours is 1 to 72. --cidr, repeated for several ranges, gives the addresses the emergency accounts may sign in from, and without it any address may. The command prints a one-time set-password link for every emergency account that has no password yet. A new window replaces an open one and ends every break-glass session, so the accounts sign in again under the new window’s hours and addresses. When no emergency account exists, the command says so and gives the two commands above.

The address is the caller’s address as the terminator sees it, or the address the CDN gives when the hub is behind one. When the hub has allowed networks and the window’s address isn’t on them, add it first, which works without signing in:

$ docker compose run --rm infra weikio-backend networks add 203.0.113.7/32 --reason "break-glass sign-in"

Check and close it#

$ docker compose run --rm infra weikio-backend breakglass status
$ docker compose run --rm infra weikio-backend breakglass disable --reason "Entra ID sign-in works again"

status shows whether a window is open, until when, for which addresses and how many sign-ins it has had. disable closes the window early and ends every session signed in through it. A platform administrator also sees the open window with weikio platform breakglass.

Every request is audited#

Opening and closing a window are in the audit trail as BreakGlassEnabled and BreakGlassDisabled, with the reason. Every request of a break-glass session is in the trail too, and so is the end of a session the hub ended because a request came while no window was open or from an address the window doesn’t allow.

To post each of those records as JSON to a system of your own as it’s written, such as your alerting, set its https:// address in .env and run docker compose up -d:

WEIKIO_BREAK_GLASS_WEBHOOK_URL=https://alerts.acme.example/hooks/weikio

An http:// address stops the backend at its start with a line that gives the setting, because the copies would travel in clear text.

An API key of an emergency account is refused the same way outside a window, and the CLI says that no break-glass window is open or the address isn’t allowed, with the weikio-backend breakglass enable line.