# Unlock User Account

**Categories:** Identity

Restores access for locked-out users across all integrated identity providers through a single verified, automated flow

- Triggered when a user requests their account to be unlocked
- Verifies the requester's identity through a secure authentication step
- Checks for active security flags or suspicious activity on the account
- Unlocks the account across the configured identity systems
- Confirms restored access with the user through their preferred communication channel
- Updates the ticket with the full outcome for audit and traceability

## What Unlock User Account does

Unlock User Account is Harmony's automated workflow for restoring access to an employee's work account after it has been locked out - typically due to too many failed login attempts. The employee asks the helpdesk chatbot, Harmony checks the account status to confirm it's actually locked, verifies the employee's identity, unlocks the account in the identity provider, and terminates any stale sessions - all without IT needing to touch the IdP admin console.

## Who Unlock User Account Is For

**Persona:** Employees who are locked out of their work account and can't log in even though they know their password.

**Pain point:** Account lockouts are urgent and disruptive - an employee can't work until their account is unblocked. Without automation, this requires an IT agent to locate the account, verify the request is legitimate, and manually unlock it in the IdP. Harmony handles the entire loop automatically, so the employee's access is restored in minutes rather than waiting in an IT queue.

## How Unlock User Account Works

**Trigger:** An employee tells the helpdesk chatbot they can't log into their work account. The chatbot checks the account status first to confirm it's actually locked (not a password or MFA issue).

1. **Status-based routing** - If the account is locked, the chatbot explains what the unlock will do and asks for confirmation. If the account is active, password-expired, or in an escalation state, the chatbot routes to the appropriate workflow or opens a regular IT ticket instead.

2. **Identity verification** - The workflow verifies the employee via OTP (one-time passcode) or Okta Verify, using recovery contact information from the IdP. If verification fails or times out, the ticket is escalated to IT.

3. **Account unlock** - On successful verification, the workflow calls the IdP to unlock the account. If the unlock succeeds, the flow continues; if it returns a non-"UNLOCKED" status, the ticket is escalated.

4. **Session cleanup** - After unlocking, the workflow terminates all active sessions in the IdP to ensure the employee starts fresh.

**Outcome:** A success notification is sent to the employee via DM with instructions to sign in using their existing credentials. The ticket is resolved.

## Capabilities

- **Check account status before acting** - Always verifies the account is actually locked (not just password-expired or in an unknown state) before offering or triggering the unlock flow.
- **Verify identity before unlocking** - Sends an OTP or uses Okta Verify to confirm the employee's identity before making any changes in the IdP.
- **Unlock accounts in Okta** - Directly removes the lockout state from the employee's Okta account (the confirmed supported IdP for account unlock).
- **Terminate active sessions after unlock** - Clears all active IdP sessions after the unlock so the employee signs in fresh with clean state.
- **Status-based routing** - The agent interprets account status ("locked", "active", "password_expired", "requires_escalation") and routes to the right workflow or escalates rather than attempting an unlock for the wrong state.
- **Context-aware escalation path** - If password reset or MFA reset workflows are enabled for the tenant, the agent offers those for non-locked states rather than just opening a general IT ticket.
- **Post-unlock guidance** - If the employee still can't log in after a successful unlock (such as due to a separate MFA issue), the agent instructs them to start a new conversation for the next step.

## Main use cases

**Employee Locked Out After Too Many Failed Attempts** - An employee tried the wrong password several times and their Okta account got locked. They know their password - they just can't get past the lockout. The chatbot checks the account status, confirms it's locked, verifies the employee's identity via OTP, unlocks the account in Okta, terminates stale sessions, and sends a confirmation DM - all without an IT agent.

**Employee Who Thinks They're Locked Out but Actually Forgot Their Password** - An employee says "my account is locked" but the status check shows the account is active - they've actually forgotten their password. The chatbot reads the status check result, doesn't trigger an unlock (which would do nothing), and routes the employee to the Password Reset workflow instead.

**Employee Locked Out Who Also Has MFA Concerns** - An employee unlocks successfully but then finds they also can't complete MFA because they got a new phone. The post-unlock success message explains that if they still can't sign in, they should start a new conversation - the chatbot then handles the MFA reset as a separate workflow in the next conversation.

## Integrations

| Integration | Role in the agent flow |
| --- | --- |
| Okta | Account status check, account unlock, and session termination - the confirmed supported IdP for this workflow |
| Service Desk (internal) | HIGH-priority ticket created at request time; updated throughout; resolved on successful unlock or escalated on failure |
| Notifications system (Slack/Teams) | Delivers OTP for identity verification; sends success confirmation or escalation notice via DM |

## FAQ

### What exactly is Unlock User Account - is it a bot, a workflow, or something else?

It's both. The AI Helpdesk chatbot handles the conversation - checking account status, explaining what the unlock will do, and asking for confirmation. Once the ticket is created, a deterministic workflow takes over: identity verification, account unlock in the IdP, session termination, and ticket resolution.

### How does it know the account is actually locked before doing anything?

The chatbot always calls the account status check tool first. It reads the status returned by the IdP ("locked", "active", "password_expired", "requires_escalation") and only offers the unlock flow when the status is confirmed as "locked". For any other status, it routes to an appropriate alternative.

### What does it handle and what does it hand off to a human?

Harmony handles the full loop when the account is locked in Okta and identity verification succeeds: unlock, session cleanup, and confirmation. It hands off to IT if: the account status is "requires_escalation"; identity verification fails or times out; the unlock call doesn't return an "UNLOCKED" status; or an unexpected error occurs. In all escalation cases the ticket stays open and is reassigned with a clear explanation.

### Which IdPs does account unlock support?

Based on the codebase, account unlock is confirmed for Okta only (`AccountUnlockIdp = Literal[SupportedIdp.OKTA]`). Password reset and MFA reset support additional IdPs, but the unlock-specific toolset is scoped to Okta in the current implementation.

### What does it need to be connected to before it works?

An Okta integration must be configured in tenant settings. The notifications system must be set up for OTP delivery and DM notifications. The workflow template must be explicitly enabled per tenant (disabled by default).

## Related platform features

- **AI Helpdesk Chatbot** - Entry point - checks account status first, determines lock state, calls `idp_account_unlock` to create the ticket and start the workflow