# how to set up MFA enforcement for a team

## TL;DR

Enforce MFA in your identity provider so it cant be skipped, prefer phishing-resistant methods (security keys, passkeys) with authenticator apps as the baseline, and roll out with a grace period plus a helpdesk runbook for lockouts. Announce, enforce, audit the stragglers, and have an exceptions process so the rollout doesnt stall on edge cases.

```text
how to set up MFA enforcement for a team
```

## Use this when

- Leadership or compliance says MFA is now mandatory
- An account takeover makes voluntary MFA look naive
- You are configuring a new identity provider or GitHub org
- You need an MFA rollout plan that wont generate a ticket avalanche

## Not for this skill when

- You are setting up MFA on your own personal accounts (just turn it on)
- The question is password policy (different skill)
- You are migrating identity providers entirely (bigger project)

## Steps

### 1. Pick the allowed methods and rank them

Security keys and passkeys resist phishing; TOTP authenticator apps are the practical baseline; SMS is a last resort because of SIM-swap attacks. Decide what you allow before you enforce, or people will pick the weakest option.

```bash
gh api orgs/[org-name] --jq '{two_factor_requirement_enabled}'
```

Expected: for a GitHub org, confirmation of whether 2FA is currently required. In your IdP (Google Workspace, Okta, Entra), find the MFA enforcement policy page and note which methods are currently permitted; that is your starting inventory.

### 2. Turn on enforcement in the identity provider

Flip the setting from optional to required. In Google Workspace this is the 2-Step Verification enforcement under Security; in Okta and Entra it is a sign-on or MFA enrollment policy. Set a grace period (two weeks is typical) so existing sessions dont all die at once.

```bash
gh api -X PATCH orgs/[org-name] -f two_factor_requirement_enabled=true
```

Expected: the org now requires 2FA; members without it get prompted, then blocked. Verify with the read command from step 1; the flag should now be true.

### 3. Publish the rollout plan and the lockout runbook

Tell the team what changes, by when, and what to do when locked out. The runbook needs: helpdesk identity verification, exception approvers, and the recovery-code flow. Most rollouts fail on communication, not technology.

```bash
printf 'MFA enforcement date: [date]\nAllowed methods: security key, authenticator app\nLocked out? contact [helpdesk channel] with [verification details]\n' | tee mfa-rollout-notice.txt
```

Expected: a notice file you can paste into the announcement. Include a test login link and office-hours support for the first week.

### 4. Distribute recovery codes and register spares

Everyone enrolls a primary and a backup method (two keys, or key plus authenticator app), and stores recovery codes somewhere that isnt the laptop that also holds the authenticator. Single-method enrollment is how one lost phone becomes a helpdesk emergency.

```bash
printf 'Enrolled primary: [method]\nEnrolled backup: [method]\nRecovery codes stored: [location, e.g. password manager]\n' | tee -a mfa-enrollment-checklist.txt
```

Expected: a per-person checklist the team fills in during enrollment week. Chase the incomplete ones; they are your incident queue.

### 5. Audit compliance and chase stragglers

After the grace period, restrict anyone still unenrolled until they comply. Exceptions get documented, time-boxed, and reviewed, never permanent.

```bash
gh api orgs/[org-name]/members --jq '.[].login' | while read u; do gh api users/$u --jq '[.login, .two_factor_authentication] | @tsv'; done | grep -i false
```

Expected: a list of members without 2FA, ideally empty. Anyone on it after the deadline gets their access suspended until they enroll; no silent extensions.

### Variant: enforce 2fa github organization

GitHub orgs: Settings, then Authentication security, then require two-factor authentication. Outside collaborators count too. Do this before you worry about branch protection; an org without 2FA is one phished password from a supply-chain incident.

### Variant: mfa for service accounts and break-glass

Service accounts cant tap a push notification. Give them no interactive login at all (API tokens with tight scopes instead), and keep break-glass admin accounts MFA-protected with recovery codes in a sealed envelope or vault, tested twice a year.

### Variant: we tried mfa rollout and people revolted

Usual causes: no grace period, no backup methods, unprepared helpdesk, or exempted leadership. Fix those and re-run.

## Why this happens

Passwords leak constantly (breaches, reuse, phishing), and MFA is the cheapest control that survives a leaked password. Voluntary MFA plateaus around the security-conscious minority; the accounts that get taken over are always in the other group. Enforcement exists because the risk is concentrated exactly where adoption is voluntary.

## Edge cases and pitfalls

- SMS as the only method: SIM-swap attacks make this theater against targeted attackers; allow it only as a fallback, never the sole method.
- Lost second factor with no backup: this is the number-one helpdesk ticket; the backup-method requirement in step 4 prevents most of it.
- Contractor and vendor accounts: they need MFA too, and they are the accounts most often exempted; put them in the IdP, not outside it.
- Enforcement vs enrollment: some IdPs let users dismiss the prompt forever; verify the policy actually blocks access, not just nags.
- Break-glass accounts: if nobody can log in during an IdP outage, you need one; if everyone knows its password, you have a backdoor. Sealed, tested, audited.
- Push fatigue: number-matching or security keys beat plain push approvals, which users approve out of habit.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_LA1MjAz937EFglO7KSIjLw