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.
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:
- Looks up the user in Okta by their email address
- Resets all enrolled MFA factors for that user
- Returns the user's MFA factors to an unenrolled state
- Keeps the user account status as ACTIVE
- 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.
- Log into your Okta Admin Console as a Super Administrator
- Navigate to Directory > People
- Click Add Person
- Create a service account:
- First name:
API - Last name:
Service Account(orRisotto Integration) - Username/Email:
api-service@yourcompany.com - Password: Set a strong, secure password
- First name:
- Click Save
Step 2: Assign Admin Role to Service Account
- In Directory > People, find your service account
- Click on the account name to open the profile
- Click the Admin button
- Click Edit in the Administrator Roles section
- Select the appropriate admin role:
- Help Desk Administrator (minimum for MFA reset)
- Super Administrator (recommended for full functionality)
- If using Help Desk Administrator, specify which groups this admin can manage
- Click Save Changes
Step 3: Create an API Token
- While viewing the service account profile, click Security > API
- Click the Tokens tab
- Click Create token
- Provide a token name:
- Token name:
Risotto MFA Reset Integration
- Token name:
- (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
- Click Create token
Step 4: Copy the API Token
After creating the token, Okta will display it in a modal dialog.
- Click the Copy to clipboard button or manually select and copy the token
- Store the token securely (password manager, secrets vault, etc.)
- 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:
- Looks up john.smith@company.com in Okta
- Resets all enrolled MFA factors
- 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:
- Returns a confirmation prompt warning about the destructive action
- 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:
- Resets MFA factors
- Returns brief success message
Response:
All MFA factors successfully reset for alex.chen@company.com.
What Happens After MFA Reset
For the User:
- Immediate Effect: All current MFA factor enrollments are removed
- Account Access: User account remains ACTIVE and accessible
- Next Login: User will be prompted to enroll in MFA factors again
- Re-enrollment: User must set up at least one MFA factor to comply with organization policies
For Administrators:
- Audit Trail: The MFA reset action is logged in Okta's System Log
- User Notification: Recommended to notify the user that MFA was reset
- 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 invalidEmail 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.
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:
- Verify the email address spelling
- Check in Okta Admin Console if user exists (Directory > People)
- 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
"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:
- Verify the admin account has Help Desk Admin role or higher
- If using Help Desk Admin, ensure user is in a group managed by that admin
- Consider upgrading to Super Admin role for the API service account
- 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:
- Verify API token is correct and hasn't expired (30-day expiration)
- Check Okta domain URL format (should include
https://) - Ensure network connectivity to Okta
- Check if rate limits are exceeded (see Okta API rate limit documentation)
- 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:
- Create a new API token following Steps 3-4
- Update the token in Risotto configuration
- 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:
- Check if the service account is still active in Directory > People
- Reactivate the service account if it was accidentally deactivated
- 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:
- Navigate to Security > API > Tokens
- Find the token in the list
- Click Revoke next to the token
- 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
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
Classic Engine vs. Identity Engine
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
Something wrong or missing? Report an issue · View as Markdown