diff --git a/docs-conceptual/azps-14.2.0/authenticate-mfa.md b/docs-conceptual/azps-14.2.0/authenticate-mfa.md index 835a0251e3..31769946f7 100644 --- a/docs-conceptual/azps-14.2.0/authenticate-mfa.md +++ b/docs-conceptual/azps-14.2.0/authenticate-mfa.md @@ -159,47 +159,6 @@ To learn more about federated identities, see: - [What is workload identity federation?][identity-federations] - [Migrate to Microsoft Entra multifactor authentication with federations][mfa-federations] -## Troubleshooting - -### 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. -This authentication method doesn't support MFA. Here's an example: - -```azurepowershell -Connect-AzAccount -Credential $Credential -``` - -If the user account requires MFA, the command fails with the following error: - -```Output -Connect-AzAccount : UsernamePasswordCredential authentication failed: Response status code does not indicate success: 400 (BadRequest). -See the troubleshooting guide for more information -https://aka.ms/azsdk/net/identity/usernamepasswordcredential/troubleshoot -``` - -**Solution:** Use an authentication method that's compatible with MFA. - -### Cross-tenant warning: Authentication failed against tenant - -If you have access to multiple tenants, and one of them requires MFA, Azure PowerShell might display -the following warning: - -```Output -WARNING: Unable to acquire token for tenant '00000000-0000-0000-0000-000000000000' with error 'Authentication failed against tenant 00000000-0000-0000-0000-000000000000. User interaction is required. This may be due to the conditional access policy settings such as multi-factor authentication (MFA). If you need to access subscriptions in that tenant, please rerun 'Connect-AzAccount' with additional parameter '-TenantId 00000000-0000-0000-0000-000000000000.' -``` - -Azure PowerShell attempts to sign in with _the first tenant found_ during login. If that tenant -enforces MFA, authentication might fail. To avoid this issue, explicitly specify the target tenant -using the **TenantId** parameter: - -```azurepowershell -Connect-AzAccount -TenantId 00000000-0000-0000-0000-000000000000 -``` - -This ensures that authentication is attempted against the correct tenant, reducing the likelihood of -MFA-related failures. - ## Learn more about multifactor authentication The Microsoft Entra ID documentation site offers more detail on MFA. @@ -233,3 +192,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 diff --git a/docs-conceptual/azps-14.2.0/troubleshooting.md b/docs-conceptual/azps-14.2.0/troubleshooting.md index cdf65e5b2b..d8c4f0b49a 100644 --- a/docs-conceptual/azps-14.2.0/troubleshooting.md +++ b/docs-conceptual/azps-14.2.0/troubleshooting.md @@ -26,6 +26,103 @@ To enable debug logging for an entire PowerShell session, you set the value of t $DebugPreference = 'Continue' ``` +## 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 "" +``` + +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 one of 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: + + ```azurepowershell + Connect-AzAccount -Tenant (Get-AzContext).Tenant.Id -ClaimsChallenge "" + ``` + +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. +This authentication method doesn't support MFA. Here's an example: + +```azurepowershell +Connect-AzAccount -Credential $Credential +``` + +If the user account requires MFA, the command fails with the following error: + +```Output +Connect-AzAccount : UsernamePasswordCredential authentication failed: Response status code does not +indicate success: 400 (BadRequest). See the troubleshooting guide for more information +https://aka.ms/azsdk/net/identity/usernamepasswordcredential/troubleshoot +``` + +**Solution:** Use an authentication method that's compatible with MFA. + +### Cross-tenant warning: Authentication failed against tenant + +If you have access to multiple tenants, and one of them requires MFA, Azure PowerShell might display +the following warning: + +```Output +WARNING: Unable to acquire token for tenant '00000000-0000-0000-0000-000000000000' with error +'Authentication failed against tenant 00000000-0000-0000-0000-000000000000. User interaction is +required. This may be due to the conditional access policy settings such as multi-factor +authentication (MFA). If you need to access subscriptions in that tenant, please rerun +'Connect-AzAccount' with additional parameter '-TenantId 00000000-0000-0000-0000-000000000000.' +``` + +Azure PowerShell attempts to sign in with _the first tenant found_ during login. If that tenant +enforces MFA, authentication might fail. To avoid this issue, explicitly specify the target tenant +using the **TenantId** parameter: + +```azurepowershell +Connect-AzAccount -TenantId 00000000-0000-0000-0000-000000000000 +``` + +This ensures that authentication is attempted against the correct tenant, reducing the likelihood of +MFA-related failures. + ## Announcement messages in automation scenarios When connecting to Azure with Azure PowerShell, announcement messages are displayed using