Break-glass validator

What it does

Runs once a day at 03:00 UTC across every imported tenant and inspects each tenant's latest CA snapshot. For every enforced blocking policy that does not exclude the break-glass (BG) group (or BG member accounts), it raises a critical-severity alert with kind breakglass.exclusion_missing. One alert per tenant; the alert payload lists the offending policies.

This is the safety net behind Policytab's tenant-lockout guardrail: a blocking policy that forgets to exclude the emergency-access group is the most common self-inflicted lockout path. The validator turns that into a nightly check with a critical alert.

When to use it

You do not run it manually in normal operations. It runs on the platform cron. What you do is handle the alerts:

• Mid-incident: breakglass.exclusion_missing means the break-glass account would also be blocked if it tried to sign in right now. Treat as urgent.
• Routine triage: during your morning alerts pass (see Daily workflows), resolve any open breakglass.exclusion_missing alerts.

You can also trigger a single-tenant check from Tenant → Break-glass → Run check now (same validator logic, plus sign-in and membership scans).

What the alert payload contains

{
  "violations": [
    {
      "policy_id": "ca-policy-guid",
      "display_name": "CA107 - Block Legacy Auth",
      "blocking_reason": "explicit block control"
    }
  ],
  "bg_group_id": "<entra-group-guid>",
  "bg_user_count": 2,
  "checked": 14,
  "evaluated_at": "2026-05-19T03:00:42Z"
}

violations is the actionable list. Each entry is an enabled CA policy that would block sign-ins and does not exclude the BG group (via excludeGroups) or BG member accounts (via excludeUsers).

Alerts are deduped: if an unacknowledged breakglass.exclusion_missing alert already exists for the tenant, the cron updates that row's payload and fired_at instead of inserting a duplicate. Acknowledging or resolving is manual - the validator does not auto-close alerts when violations clear.

Fixing violations

For each policy in violations:

1. Tenant detail → Changes → Propose change of kind policy.assignment_change.
2. Add the BG group to the exclude scope: add_exclude_group_ids: ["<bg-group-id>"].
3. Dry-run, approve, and apply through the change workflow.

After the next snapshot (nightly at 02:00 UTC or a manual Resync), re-run the check or wait for the next cron. Acknowledge the alert once you have verified the fix.

Why the BG group must be excluded from blocking policies

The BG group exists so an admin can recover from a CA misconfiguration. Typical failure modes:

• Geo-block + admin travels. Admin lands in a blocked country and cannot sign in to fix CA.
• Push-MFA + Microsoft push outage. Authenticator push is down; MFA-required policy blocks everyone, including BG, if not excluded.

If the BG group is excluded from every blocking policy, you retain at least one recovery path.

Configuration

• What counts as the BG group? Per tenant: tenant.bg_group_mail_nickname (and display name for UI), set on Tenant → Break-glass or during onboarding group mapping. The validator resolves the Entra object id from the latest snapshot's groups list by matching mailNickname. If the nickname is empty or the group is not present in the snapshot, the tenant is skipped (no alert).
• What counts as blocking? State = enabled AND grant controls include an explicit block, OR mandatory require-controls the BG account cannot satisfy, OR authenticationStrength is set.

Policytab membership edits: tenant.bg_membership_edits_blocked blocks Policytab-driven group membership changes to the BG group (group management UI and exclusions). It does not lock the group in Entra - portal changes are detected by the membership diff cron on the Break-glass page.

Troubleshooting

• Alert fires but I just fixed it. The validator uses the latest snapshot. Resync the tenant or wait for the nightly snapshot before expecting a clean re-check.
• Validator never runs. Cron is registered in 20260525120013_breakglass_validator_cron.sql. It skips if app.edge_functions_base_url or app.service_role_key Postgres settings are missing. Confirm via select * from cron.job where jobname = 'kick_breakglass_validator'.
• No alert but Break-glass page shows exclusion gaps. Run Run check now on the Break-glass page; confirm bg_group_mail_nickname is set and the group appears in the latest snapshot.
• Alert payload references a deleted policy id. Resync - the next run uses current snapshot data.

Combining with drift auto-remediation

When drift auto-remediation is on, a breakglass.exclusion_missing violation that maps to a baseline policy's known exclusion shape can be auto-proposed as a policy.assignment_change revert. The change still requires human approval before apply.

Related alerts

See Onboarding a customer for initial BG group setup.