# Account Lockouts & MFA Reset

**Categories:** Identity

## What Account Lockouts & MFA Reset does

Harmony's Account Lockouts & MFA Reset agent handles two of the most urgent access recovery requests employees face: unlocking a work account that has been locked out of an Identity Provider (IdP), and resetting an MFA device that is lost, broken, or no longer accessible. When an employee reports they can't sign in, the agent first checks their live account status across connected IdPs, then automatically routes to the right resolution flow - unlocking the account or clearing the MFA enrollment - without requiring IT to intervene manually. For most users, the issue is resolved end-to-end inside a single conversation.

## Who Account Lockouts and MFA Reset Is For

**Persona:** Any employee at an organization using Okta, Microsoft Entra, Google Workspace, or JumpCloud as their Identity Provider.

**Pain point:** Account lockouts and MFA failures are urgent - they block people from doing their job immediately. Before this agent, employees had to open a ticket, wait for an IT agent to notice it, and then wait again while the IT agent manually looked up the account status and performed the unlock or reset. With this agent, the triage, verification, and action happen automatically, often within minutes of the employee reporting the issue.

## Account Unlock Flow

**Trigger:** Employee says they can't sign in, are locked out, or requests help accessing their work account.

1. **Status check** - The agent calls check_idp_account_status to query the employee's live account state across all connected IdPs (Okta, Microsoft Entra). It reads the actual status from the IdP in real time.

2. **Routing** - If the status is locked, the agent offers an unlock. If password_expired, it routes to password reset. If requires_escalation, it opens a regular IT ticket.

3. **Confirmation** - The agent explains what the unlock will do and asks for explicit confirmation before proceeding.

4. **Workflow execution** - A high-priority ticket is created and triggers the idp-account-unlock Temporal workflow, which: verifies the employee's identity via OTP, calls the IdP's unlock API, terminates all active sessions, and sends the employee a confirmation message.

**Outcome:** Ticket is resolved automatically, or escalated to IT if verification fails or the unlock API returns an error.

## MFA Reset Flow

**Trigger:** Employee reports their authenticator app isn't working, they got a new phone, or they can't complete MFA verification.

1. **IdP identification** - Agent checks which IdPs are connected to the employee. If there's only one, it proceeds automatically. If multiple, it asks which account.

2. **Confirmation** - Agent explains the reset will allow re-enrollment on a new device and asks for confirmation.

3. **Workflow execution** - A high-priority ticket triggers the idp-mfa-reset Temporal workflow, which: verifies identity via OTP (email/SMS - not the broken MFA device), optionally routes through a manager/IT approver if approval is required, presents the employee with a list of enrolled MFA devices to select which to remove, calls the IdP's MFA reset API for the selected factors, optionally revokes all active sessions, and sends re-enrollment instructions via direct message.

**Outcome:** Employee receives instructions to set up a new MFA device. Ticket is resolved or escalated.

## Capabilities

- **Live account status check** - Queries the IdP in real time to get the current account state (active, locked, password_expired, requires_escalation, unknown) before taking any action.
- **Automatic IdP detection** - When the employee has only one connected IdP, the agent selects it automatically without asking. When multiple IdPs are connected, it asks once.
- **Account unlock via Okta** - Unlocks the employee's account directly in Okta, then terminates all active sessions to clear any stale tokens.
- **MFA device reset across 4 IdPs** - Removes enrolled MFA factors in Okta, Microsoft Entra, Google Workspace, or JumpCloud, allowing the employee to re-enroll a new device.
- **Identity verification before action** - Uses OTP (email or SMS) to verify the requester's identity before executing any unlock or MFA reset. This is a mandatory security gate.
- **Optional approval gate for MFA resets** - IT can configure MFA resets to require manager or IT approver sign-off before the reset proceeds. The workflow waits, sends nudges, and times out gracefully if no response is received.
- **Device selection UI for MFA** - Presents the employee with their enrolled MFA devices and lets them choose which specific factors to remove, rather than blindly resetting everything.
- **Graceful escalation** - On verification failure, IdP API error, or unsupported account state, the ticket is automatically reassigned to the IT queue with an internal note explaining what happened.
- **Strict separation from password reset** - The agent explicitly checks whether the issue is a password problem or an MFA/verification problem and routes to the correct flow, never conflating the two.

## Main use cases

**New Phone, Authenticator App Needs Re-Enrollment** - An employee gets a new phone and can no longer access their Okta Verify app. They message Harmony saying "My MFA isn't working after I got a new phone." The agent identifies this as an MFA issue (not a password issue), confirms the employee's Okta account, verifies their identity via email OTP, shows them a list of their enrolled devices, removes the old Okta Verify enrollment, and sends them instructions to set up the authenticator on their new phone. No IT agent involvement needed.

**Account Locked After Too Many Failed Login Attempts** - An employee tries the wrong password several times and their Okta account gets locked. They message Harmony saying "I can't sign in, I think I'm locked out." The agent runs a live status check, confirms the account status is `locked`, explains the unlock to the employee, verifies their identity via OTP, calls the Okta unlock API, clears all active sessions, and sends a confirmation. The employee can sign in again within minutes.

**Ambiguous "can't Log In" - Needs Triage First** - An employee says "I can't access my account" without specifying whether it's a password, MFA, or lockout issue. The agent checks account status across all connected IdPs first. If it comes back `locked` it offers an unlock. If `password_expired` it routes to password reset. If `active` it asks clarifying questions. No guessing - the live IdP state drives the routing.

**Manager Approval Required for MFA Reset** - A company has configured MFA resets to require IT manager approval as a security policy. After identity verification, the workflow sends an approval request to the configured approvers, waits up to 48 hours (configurable), sends nudges at configured intervals, and only proceeds with the reset once approval is granted. If denied or timed out, the ticket is updated accordingly.

## Integrations

| Integration | Role in the agent flow |
| --- | --- |
| Okta | Account status check, account unlock, MFA factor listing, MFA factor reset, session termination |
| Microsoft Entra | Account status check, MFA factor reset |
| Google Workspace | MFA factor reset |
| JumpCloud | MFA factor reset |
| Harmony Service Desk | Ticket creation (HIGH priority), status updates, internal notes, employee notifications |
| OTP verification | Identity verification via email/SMS before any unlock or reset action |

## FAQ

### What exactly is this - is it a bot, a workflow, or something else?

It's both. The conversational part is powered by Harmony's AI helpdesk agent, which understands what the employee is asking and handles the dialogue. Once the agent determines what action to take, it creates a ticket that triggers a Temporal workflow - a reliable, step-by-step automation that calls the IdP APIs, handles verification, and updates the ticket. The conversation is AI; the execution is a structured workflow.

### How does it know whether to unlock the account or reset MFA - does it guess?

No. It calls the IdP directly to read the live account status before deciding anything. `locked` → account unlock flow. MFA issue described by employee (can't complete verification after entering password) → MFA reset flow. Ambiguous cases → it asks one clarifying question. It will not trigger an unlock if the account isn't actually locked.

### What does it handle automatically and what gets escalated to a human?

Handled automatically: locked accounts (Okta), MFA resets for all four supported IdPs, identity verification, session termination. Escalated to IT: accounts with `requires_escalation` status (suspended/deprovisioned), verification failures (employee didn't complete OTP in time), IdP API errors, and accounts not found in the connected IdP. Every escalation includes an internal note explaining why.

### Can it reset MFA without the employee verifying their identity first?

No - identity verification is a mandatory gate that cannot be bypassed. Because the MFA device is the thing being reset, the workflow uses OTP (email or SMS) as the verification method instead. The workflow will not call the MFA reset API until the OTP verification step completes successfully.

### What needs to be set up before this works for a tenant?

The tenant must have at least one supported IdP integration connected in Harmony (Okta is required for account unlock; Okta/Entra/Google Workspace/JumpCloud for MFA reset). The `idp-account-unlock` and `idp-mfa-reset` workflow templates must be enabled for the tenant - they are disabled by default. Optionally, IT can configure the approval gate for MFA resets and whether to terminate sessions after a reset.

## Related platform features

- **Identity Status Check** - The mandatory first step before either unlock or MFA reset - checks live account state and drives the routing decision.
- **Helpdesk chatbot** - The outer container that hosts all toolkits. The chatbot routes the conversation to the right toolkit based on what the employee describes.