# Reset User MFA Factors

Resets all multi-factor authentication (MFA) factors for a user in Okta

Resets all multi-factor authentication (MFA) factors for a user in Okta, removing all enrolled MFA methods and returning them to an unenrolled state. The user will need to re-enroll in their MFA factors the next time they authenticate.

> **Warning:** This action removes **ALL** enrolled MFA factors for the user and **cannot be
> undone**. Use with caution.

## Overview

The Okta Reset User MFA Factors tool allows Risotto to automatically reset MFA enrollments for users who have lost access to their authentication devices or are experiencing MFA issues. This is useful for:

- **Lost Device Recovery**: User lost their phone or authenticator device
- **Device Replacement**: User got a new phone and needs to set up MFA again
- **MFA Troubleshooting**: User experiencing authentication issues with their current MFA factors
- **Security Incidents**: Proactive MFA reset after a security concern
- **Onboarding Issues**: New user unable to complete MFA enrollment properly

## How It Works

When executed, this tool:

1. Looks up the user in Okta by their email address
2. Resets **all** enrolled MFA factors for that user
3. Returns the user's MFA factors to an unenrolled state
4. Keeps the user account status as ACTIVE
5. Prompts the user to re-enroll in MFA at their next login

**Factors that are reset include:**

- SMS authentication
- Voice call authentication
- Okta Verify push notifications
- Okta Verify OTP codes
- Google Authenticator
- Hardware tokens
- Security keys (WebAuthn/FIDO2)
- Any other enrolled MFA methods

## Prerequisites

Before setting up this tool, you need:

### 1. Okta Organization Access

Administrative access to your Okta organization with permissions to create API tokens.

### 2. Admin Role with Appropriate Permissions

The API token must be created by an admin with permissions to reset user MFA factors. Minimum required role: **Help Desk Administrator**

**Roles that can reset MFA factors:**

- **Super Administrator** (recommended for full functionality)
- **Org Administrator**
- **Help Desk Administrator** (minimum required)
- **Group Administrator** (for users in managed groups)

### 3. Okta Domain URL

Your Okta organization's domain URL, typically in the format:

- `https://yourcompany.okta.com` (Okta-hosted)
- `https://yourcompany.okta-emea.com` (EMEA region)
- `https://login.yourcompany.com` (custom domain)

You can find your Okta domain in the Admin Console URL or in your organization settings.

## Step-by-Step Setup

### Step 1: Create or Identify a Service Account (Recommended)

For production use, it's recommended to create a dedicated service account for API operations rather than using a personal admin account.

1. Log into your Okta Admin Console as a Super Administrator
2. Navigate to **Directory** > **People**
3. Click **Add Person**
4. Create a service account:
   - **First name**: `API`
   - **Last name**: `Service Account` (or `Risotto Integration`)
   - **Username/Email**: `api-service@yourcompany.com`
   - **Password**: Set a strong, secure password
5. Click **Save**

> **Tip:** Using a service account ensures that API tokens remain active even if
> individual admins leave the organization. If a user account is deactivated,
> all API tokens created by that user are automatically deactivated.

### Step 2: Assign Admin Role to Service Account

1. In **Directory** > **People**, find your service account
2. Click on the account name to open the profile
3. Click the **Admin** button
4. Click **Edit** in the Administrator Roles section
5. Select the appropriate admin role:
   - **Help Desk Administrator** (minimum for MFA reset)
   - **Super Administrator** (recommended for full functionality)
6. If using Help Desk Administrator, specify which groups this admin can manage
7. Click **Save Changes**

> **Note:** Help Desk Administrators can only reset MFA for users in groups they manage.
> Super Administrators can reset MFA for all users in the organization.

> **Warning:** Okta lets only a Super Administrator reset MFA for a user who has the Super
> Administrator role. To test the tool, use a user who has no admin role. A test
> on your own admin account can fail even when the tool is set up correctly.

### Step 3: Create an API Token

1. While viewing the service account profile, click **Security** > **API**
2. Click the **Tokens** tab
3. Click **Create token**
4. Provide a token name:
   - **Token name**: `Risotto MFA Reset Integration`
5. (Optional) Configure network restrictions:
   - Click **Add IP range** to restrict token usage to specific IPs
   - Enter IP address or CIDR range (e.g., `203.0.113.0/24`)
   - This adds an extra layer of security
6. Click **Create token**

### Step 4: Copy the API Token

After creating the token, Okta will display it in a modal dialog.

> **Warning:** You will only see the token value once. Record it immediately in a secure
> location. After closing the dialog, you cannot retrieve the token value again.

1. Click the **Copy to clipboard** button or manually select and copy the token
2. Store the token securely (password manager, secrets vault, etc.)
3. Click **OK, got it** to close the dialog

**The token will appear in this format:**

```
00AbC1D2EfG3h4I5JkL6MnO7PqR8StU9VwX0YzA1BcD
```

### Step 5: Note Token Characteristics

After creation, note the following about your API token:

- **Expiration**: Token is valid for **30 days from creation or last use**
  - Each API call automatically extends expiration by 30 days
  - Tokens unused for 30 days will automatically expire
- **Rate Limiting**: API tokens are limited to 50% of your organization's API rate limits
- **Deactivation**: Token is automatically deactivated if the creating user account is deactivated
- **Network Restrictions**: Token only works from specified IP ranges (if configured)

### Step 6: Configure the Tool in Risotto

The tool can use the Okta connection of your organization (**Settings > Integrations > Okta**) or its own API token. Configure the tool in Risotto with these settings:

| Field                          | Description                                                                                                                   | Example                        |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
| **Okta Domain URL (Optional)** | Your Okta organization URL. Leave empty to use your organization's Okta connection.                                           | `https://yourcompany.okta.com` |
| **Okta API Token (Optional)**  | The API token from Step 4. Leave empty to use your organization's Okta connection.                                            | `00AbC1D2EfG3...`              |
| **Restrict to Requestor Only** | On by default: the tool can reset MFA only for the ticket's requestor. Turn it off to let IT staff reset MFA for other users. | On                             |

Risotto uses the tool's own token only when both **Okta Domain URL (Optional)** and **Okta API Token (Optional)** have a value. If the organization's Okta connection works but the tool fails with a token error, clear both fields so the tool uses the connection.

## Configuration Options

When using this tool in a runbook, you can specify:

### Parameters:

- **Email** - Email address of the user whose MFA factors should be reset. If it is empty, the tool uses the requestor's email address. With **Restrict to Requestor Only** on, the email address must be the requestor's.

### Optional Parameters:

- **Include Confirmation** (default: `true`) - Whether to include detailed confirmation information in the response (user ID, email, factor status, next steps)
- **Require Confirmation** (default: `false`) - Whether to require explicit confirmation before proceeding with the reset (safety check to prevent accidental resets)

## Usage Examples

### Example 1: Reset MFA with confirmation details

**Request:**

> "Reset MFA factors for <john.smith@company.com>"

**What Happens:**

1. Looks up <john.smith@company.com> in Okta
2. Resets all enrolled MFA factors
3. Returns detailed confirmation with user information and next steps

**Response:**

```
✅ MFA factors reset successfully!

User: john.smith@company.com
User ID: 00u1a2b3c4d5e6f7g8h9
Name: John Smith
Status: ACTIVE

🔐 MFA Reset Completed:
• All MFA factors for john.smith@company.com have been reset
• All factor enrollments have been returned to unenrolled state
• User account status remains ACTIVE
• User will need to re-enroll in MFA factors on next login
• This action cannot be undone

🔔 Next Steps:
• Notify john.smith@company.com that their MFA factors have been reset
• User will be prompted to set up MFA again at next login
• Consider providing MFA setup instructions to the user
```

### Example 2: Reset MFA with safety confirmation prompt

**Request:**

> "Reset MFA factors for <sarah.jones@company.com> with require_confirmation=true"

**What Happens:**

1. Returns a confirmation prompt warning about the destructive action
2. Requires explicit confirmation before proceeding

**Response:**

```
⚠️ IMPORTANT: Confirmation Required

You are about to reset ALL MFA factors for user: sarah.jones@company.com

This action will:
• Remove all enrolled MFA factors (SMS, Voice, Authenticator apps, etc.)
• Return all factors to an unenrolled state
• Require the user to re-enroll in MFA factors on next login
• Cannot be undone once performed

The user's account status will remain ACTIVE.

To proceed with the reset, run this command again with `require_confirmation=False`.
```

### Example 3: Simple reset without detailed confirmation

**Request:**

> "Reset MFA for <alex.chen@company.com> with include_confirmation=false"

**What Happens:**

1. Resets MFA factors
2. Returns brief success message

**Response:**

```
All MFA factors successfully reset for alex.chen@company.com.
```

## What Happens After MFA Reset

### For the User:

1. **Immediate Effect**: All current MFA factor enrollments are removed
2. **Account Access**: User account remains ACTIVE and accessible
3. **Next Login**: User will be prompted to enroll in MFA factors again
4. **Re-enrollment**: User must set up at least one MFA factor to comply with organization policies

### For Administrators:

1. **Audit Trail**: The MFA reset action is logged in Okta's System Log
2. **User Notification**: Recommended to notify the user that MFA was reset
3. **Support Preparation**: Be ready to assist user with MFA re-enrollment if needed

## Response Format

### Successful Reset (with confirmation):

The tool returns a formatted message with:

- ✅ Success indicator
- User email and ID
- User's full name (if available)
- Account status
- Detailed description of what was reset
- Next steps for administrators

### Successful Reset (without confirmation):

Returns a simple success message:

```
All MFA factors successfully reset for user@company.com.
```

## Error Messages

### User Not Found

- `User {email} not found` - No Okta user has this email address

### Invalid Email

- `Email address '{email}' is invalid.` - Email format is invalid
- `Email address is required to reset MFA factors.` - No email provided and no requestor email

### Configuration Errors

- `No Okta credentials found. Please either configure the tool with api_key and okta_url, or set up Okta credentials in your organization settings.` - The tool has no token of its own and your organization has no Okta connection

### Lookup Errors

- `Error looking up user with email {email}: {error}.`

### Permission Errors

- `Error resetting MFA factors.` - Okta refused the reset. The usual cause is that the Okta account behind the token or connection has no admin role over the user. See the Warning under [Prerequisites](#prerequisites).

## Troubleshooting

### "User not found"

**Possible Causes:**

- Email address is misspelled
- User doesn't exist in Okta
- User's email address in Okta differs from the provided email

**Solution:**

1. Verify the email address spelling
2. Check in Okta Admin Console if user exists (**Directory** > **People**)
3. Verify user's primary email in Okta matches the email you're using. Risotto needs an exact match, not a partial one. See [How Risotto finds a user in Okta](https://www.tryrisotto.com/docs/integrations/idp/okta#how-risotto-finds-a-user-in-okta)

### "Error resetting MFA factors."

**Possible Causes:**

- API token lacks sufficient permissions
- Admin role doesn't have MFA reset privileges
- Help Desk Admin trying to reset MFA for user outside managed groups
- The user has the Super Administrator role, and the admin behind the token or connection is not a Super Administrator

**Solution:**

1. Verify the admin account has Help Desk Admin role or higher
2. If using Help Desk Admin, ensure user is in a group managed by that admin
3. Consider upgrading to Super Admin role for the API service account
4. Create a new API token after changing permissions

### "Error looking up user with email"

**Possible Causes:**

- API token is invalid or expired
- Network connectivity issues
- Okta domain URL is incorrect
- API rate limit exceeded

**Solution:**

1. Verify API token is correct and hasn't expired (30-day expiration)
2. Check Okta domain URL format (should include `https://`)
3. Ensure network connectivity to Okta
4. Check if rate limits are exceeded (see Okta API rate limit documentation)
5. Generate a new API token if the current one has expired

### API Token Expired (30 days of inactivity)

**Symptoms:**

- Authentication failures after period of no API usage
- "Invalid API token" errors

**Solution:**

1. Create a new API token following Steps 3-4
2. Update the token in Risotto configuration
3. Consider implementing automated API health checks to keep tokens active

### Service Account Deactivated

**Symptoms:**

- All API calls fail with authentication errors
- Token suddenly stops working

**Solution:**

1. Check if the service account is still active in **Directory** > **People**
2. Reactivate the service account if it was accidentally deactivated
3. If account cannot be reactivated, create a new service account and API token

## Security Considerations

### 1. API Token Security

- API tokens grant programmatic access to reset user MFA factors
- Tokens are displayed only once during creation
- Store tokens securely in a password manager or secrets vault
- Never commit API tokens to version control or share publicly
- Risotto encrypts API tokens at rest

### 2. Service Account Best Practices

**Why use a service account:**

- Prevents token deactivation when individual admins leave
- Provides clear audit trail for automated actions
- Separates automated operations from personal admin actions

**Service account security:**

- Use a dedicated email (e.g., `api-service@company.com`)
- Set a strong, unique password
- Store credentials in a secure vault
- Document service account purpose and ownership

### 3. Least Privilege Access

Grant only the minimum permissions needed:

- For MFA reset only, Help Desk Administrator is sufficient
- Super Administrator provides broader access but may be unnecessary
- If using Help Desk Admin, scope to specific groups to limit access
- Review admin role assignments regularly

### 4. Token Lifecycle Management

**Active token management:**

- Tokens automatically expire after 30 days of inactivity
- Each API call refreshes the 30-day expiration
- Review active tokens regularly in **Security** > **API** > **Tokens**
- Revoke unused or compromised tokens immediately
- Rotate tokens periodically (recommended: every 90 days)

**To revoke a token:**

1. Navigate to **Security** > **API** > **Tokens**
2. Find the token in the list
3. Click **Revoke** next to the token
4. Confirm revocation

### 5. Network Restrictions (Recommended)

When creating API tokens, configure IP restrictions to limit where tokens can be used:

- Specify Risotto's server IP addresses
- Use CIDR notation for IP ranges
- This prevents token misuse if credentials are compromised

### 6. Audit Logging

All MFA reset operations are logged in Okta:

- View System Log: **Reports** > **System Log**
- Search for events: `user.mfa.factor.reset_all`
- Monitor for suspicious patterns or unexpected resets
- Set up alerts for MFA reset events

### 7. Rate Limiting

**Okta API rate limits:**

- API tokens are automatically limited to 50% of org rate limits
- Rate limits vary by Okta plan and organization size
- The tool automatically retries with exponential backoff on rate limit errors
- Monitor rate limit headers for capacity planning

**If rate limits are reached:**

- The tool will automatically wait and retry
- Consider optimizing request frequency
- Contact Okta support to discuss rate limit increases

## Important Notes

### Token Expiration and Refresh

- Tokens are valid for 30 days from creation or last use
- Each API call automatically extends expiration by 30 days
- Tokens that remain unused for 30 consecutive days will expire
- Expired tokens must be revoked and recreated

### User Account Status

> **Note:** Resetting MFA factors does **NOT** change the user's account status. The user
> remains ACTIVE and can log in (after re-enrolling in MFA).

### MFA Policy Enforcement

After MFA reset:

- User must re-enroll in MFA per organization policies
- If MFA is required, user cannot access apps until re-enrolled
- Organization's MFA policies determine which factors are available
- Factor prompt frequency is determined by authentication policies

### API Version

This tool uses the Okta Management API v1:

- **Endpoint**: `POST /api/v1/users/{userId}/lifecycle/reset_factors`
- **Authentication**: SSWS API token (format: `SSWS {token}`)
- **Documentation**: [Okta User Lifecycle API](https://developer.okta.com/docs/reference/api/users/)

### Classic Engine vs. Identity Engine

> **Warning:** This tool is designed for **Okta Classic Engine**. Organizations using **Okta
> Identity Engine** may need alternative approaches. Verify your Okta version in
> the Admin Console.

## Related Tools

- **Okta User Provisioning**: Create and manage user accounts (coming soon)
- **Okta Password Reset**: Reset user passwords programmatically (coming soon)
- **Okta Group Management**: Add/remove users from groups (coming soon)

## Additional Resources

- [Okta API Token Creation Guide](https://developer.okta.com/docs/guides/create-an-api-token/main/)
- [Okta Users API Documentation](https://developer.okta.com/docs/reference/api/users/)
- [Okta System Log Events](https://developer.okta.com/docs/reference/api/system-log/)
- [Help Desk Administrator Role](https://help.okta.com/en-us/content/topics/security/administrators-help-desk-admin.htm)
- [Okta MFA Overview](https://help.okta.com/en-us/content/topics/security/mfa/mfa-home.htm)
- [Okta API Rate Limits](https://developer.okta.com/docs/reference/rate-limits/)

Source: https://www.tryrisotto.com/docs/integrations/tools/okta/reset_factors
