Skip to content

Add error messages to troubleshooting section of MFA doc #3672

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 7 commits into
base: main
Choose a base branch
from
Draft
Changes from 4 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 53 additions & 0 deletions docs-conceptual/azps-14.2.0/authenticate-mfa.md
Original file line number Diff line number Diff line change
Expand Up @@ -161,6 +161,58 @@ To learn more about federated identities, see:

## Troubleshooting

### Multifactor authentication (MFA) interactive login failures

If you encounter errors when running Azure PowerShell cmdlets that create, modify, or delete Azure
resources, the issue might be caused by a Microsoft Entra ID conditional access policy that requires
multifactor authentication (MFA).

#### Common error messages

You might see an error like the following:

```Output
Resource was disallowed by policy. Users must use MFA for Create operation.
Users must authenticate with multi-factor authentication to create or update resources.
Run the cmdlet below to authenticate interactively; additional parameters may be added as needed.
Connect-AzAccount -Tenant (Get-AzContext).Tenant.Id -ClaimsChallenge "<claims-challenge-token>"
```

Or:

```Output
SharedTokenCacheCredential authentication unavailable. Token acquisition failed for user
someone@contoso.com. Ensure that you have authenticated with a developer tool that supports Azure
single sign on.
```

These messages indicate that your session doesn't meet the conditional access requirements,
typically, that MFA is required but not enforced at login.

### Resolution steps

To resolve these errors, upgrade to either or these supported module versions:

- **Az** PowerShell module: version 14.3.0 or later
- **Az.Accounts** module: version 5.x.y or later

These versions improve error reporting by identifying the exact conditional access policy causing
the issue and providing guidance.

Recommended Actions:

- Preferred: Ask your Azure administrator to enforce MFA at sign-in for your account. This ensures
compatibility with conditional access policies that require MFA.
- Alternative: If MFA can't be enforced at sign-in, use interactive authentication with the
**ClaimsChallenge** parameter as shown in the following example:

```PowerShell
Connect-AzAccount -Tenant (Get-AzContext).Tenant.Id -ClaimsChallenge "<claims-challenge-token>"
```

For more information about Microsoft Entra ID conditional access policies that require MFA, see
[Planning for mandatory multifactor authentication for Azure and other admin portals][01]

### ROPC error: Due to a configuration change made by your administrator

You use the Resource Owner Password Credential (ROPC) flow when signing into Azure using a password.
Expand Down Expand Up @@ -233,3 +285,4 @@ The Microsoft Entra ID documentation site offers more detail on MFA.
[steps-assign-role]: /azure/role-based-access-control/role-assignments-steps
[assign-roles]: /azure/role-based-access-control/role-assignments-powershell
[fic-serviceconn-blog]: https://devblogs.microsoft.com/azure-sdk/improve-security-posture-in-azure-service-connections-with-azurepipelinescredential/
[01]: /entra/identity/authentication/concept-mandatory-multifactor-authentication