> For the complete documentation index, see [llms.txt](https://docs.harmony.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.harmony.io/ai-agents/access-control/idp-account-unlock.md).

# IdP Account Unlock

The Automated IDP Account Unlock Workflow lets you resolve locked Identity Provider (IDP) account situations without any manual intervention. By adding the `unlock_user` block to a Harmony Workflow, you can handle the full unlock lifecycle - from verifying the requester's identity, to unlocking the account, to notifying the user and closing the associated ticket - all in a single automated flow.

This article explains how the feature works, what statuses are supported, and how to configure the workflow block for your environment.

***

### How It Works

When a user's IDP account is locked, the workflow is triggered automatically. The `unlock_user` block takes over and performs the following steps in sequence:

1. **Identity verification** - Confirms the requester's identity before any unlock action is taken.
2. **Unlock attempt** - Issues the unlock call to the connected IDP.
3. **Status-aware routing** - Evaluates the outcome of the unlock attempt and branches the workflow accordingly.
4. **Notification** - Sends the user a confirmation or a next-steps message depending on the outcome.
5. **Ticket resolution** - Closes or escalates the associated support ticket based on the final state.

Because the routing is driven by the actual account status returned by the IDP, the workflow automatically handles edge cases without requiring separate manual rules.

***

### Supported Identity Providers

#### Okta

The `unlock_user` block has full support for Okta accounts. The behavior depends on the status Okta reports for the account at the time the workflow runs:

| Okta Account Status | Workflow Outcome                                                          |
| ------------------- | ------------------------------------------------------------------------- |
| Locked out          | Account is unlocked automatically and the user is notified.               |
| Suspended           | Routed to the escalation path - agent review required.                    |
| Deprovisioned       | Routed to the escalation path - agent review required.                    |
| Password expired    | Routed to the escalation path - user is prompted to reset their password. |

This status-aware routing means your team only receives escalations for situations that genuinely require human judgment. Routine lockouts are resolved end-to-end without touching the queue.

***

### Configuring the `unlock_user` Block

To add the IDP account unlock capability to a workflow, follow these steps:

1. Open **Harmony Workflows** and create a new workflow or open an existing one.
2. In the workflow editor, add a new block and select **Unlock User** from the block library.
3. In the block configuration panel, set the following:
   * **Identity Provider** - Select the IDP connected to your environment (for example, Okta).
   * **Identity Verification Method** - Choose how the requester's identity should be confirmed before the unlock is attempted.
   * **Escalation Path** - Define which team or queue should receive escalations for statuses that cannot be resolved automatically.
   * **Notification Template** - Select or customize the message sent to the user after the unlock attempt.
4. Connect the block's outcome branches - typically a **success** branch for unlocked accounts and an **escalation** branch for all other statuses.
5. Save and activate the workflow.

***

### Workflow Outcome Branches

The `unlock_user` block exposes the following outcome branches that you can connect to downstream steps:

* **Unlocked** - The account was successfully unlocked. Use this branch to send a confirmation message and auto-resolve the ticket.
* **Escalated** - The account is in a state that requires manual review (suspended, deprovisioned, or password expired). Use this branch to assign the ticket to an agent and notify the user that assistance is on the way.
* **Error** - An unexpected error occurred during the unlock attempt. Use this branch to log the failure and alert your team.

***

### Benefits

* **Faster resolution** - Locked-out users are unblocked immediately, without waiting for an agent to pick up the ticket.
* **Reduced queue volume** - Only genuinely complex cases reach your support team.
* **Consistent handling** - Every unlock request follows the same verified, auditable process.
* **Status-aware escalation** - Accounts that need more than a simple unlock are automatically routed to the right place, reducing back-and-forth between agents and users.

***

### Requirements

* Your IDP (for example, Okta) must be connected to Harmony as an integration before the `unlock_user` block is available in the workflow editor.
* The service account or API token used for the IDP integration must have sufficient permissions to read account status and perform unlock operations.
* Identity verification must be configured within the workflow to satisfy your organization's security policy before any unlock action is executed.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.harmony.io/ai-agents/access-control/idp-account-unlock.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.