From 0350fe4aa2261d63ebdc4e330fd9ca87d450bb99 Mon Sep 17 00:00:00 2001 From: Yeming Liu <11371776+isra-fel@users.noreply.github.com> Date: Fri, 4 Jul 2025 15:02:29 +1000 Subject: [PATCH 1/6] Add FAQ about MFA --- docs-conceptual/azps-14.1.0/faq.yml | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/docs-conceptual/azps-14.1.0/faq.yml b/docs-conceptual/azps-14.1.0/faq.yml index 81e80bead8..92b12eea6a 100644 --- a/docs-conceptual/azps-14.1.0/faq.yml +++ b/docs-conceptual/azps-14.1.0/faq.yml @@ -87,3 +87,32 @@ sections: ``` **Note:** Handle plain text carefully, as it is less secure than a SecureString. + + - question: | + How to mitigate the error "SharedTokenCacheCredential authentication unavailable"? + answer: | + If you are getting this error when using an Azure PowerShell cmdlet that creates or + makes change to Azure resources, it is likely that you are blocked by the Entra ID + Conditional Access policy. + + The complete error message is as follows: + + ``` + SharedTokenCacheCredential authentication unavailable. Token acquisition failed for user + someone@example.com. Ensure that you have authenticated with a developer tool that supports + Azure single sign on. + ``` + + To resolve this issue, please update to version 14.X.Y or later of the Azure PowerShell module, + or equivalently, version 5.X.Y of the Az.Accounts module. + With these versions, the Azure PowerShell cmdlets will be able to display detailed error messages + regarding which policy is blocking the authentication, and how to resolve the issue. + + For example, if the admin has configured the policy to require multi-factor authentication (MFA), + you will see an error message similar to the following: + + ```powershell + {Placeholder for error message} + ``` + + Follow the instructions in the error message to sign in through multi-factor authentication (MFA). From d44e1543e70343fb7d591eb6d3a7ada341576a4e Mon Sep 17 00:00:00 2001 From: "Mike F. Robbins" <6719572+mikefrobbins@users.noreply.github.com> Date: Tue, 8 Jul 2025 11:17:49 -0500 Subject: [PATCH 2/6] Moved message to troubleshooting article --- docs-conceptual/azps-14.1.0/faq.yml | 29 ------------------ .../azps-14.2.0/troubleshooting.md | 30 +++++++++++++++++++ 2 files changed, 30 insertions(+), 29 deletions(-) diff --git a/docs-conceptual/azps-14.1.0/faq.yml b/docs-conceptual/azps-14.1.0/faq.yml index 92b12eea6a..81e80bead8 100644 --- a/docs-conceptual/azps-14.1.0/faq.yml +++ b/docs-conceptual/azps-14.1.0/faq.yml @@ -87,32 +87,3 @@ sections: ``` **Note:** Handle plain text carefully, as it is less secure than a SecureString. - - - question: | - How to mitigate the error "SharedTokenCacheCredential authentication unavailable"? - answer: | - If you are getting this error when using an Azure PowerShell cmdlet that creates or - makes change to Azure resources, it is likely that you are blocked by the Entra ID - Conditional Access policy. - - The complete error message is as follows: - - ``` - SharedTokenCacheCredential authentication unavailable. Token acquisition failed for user - someone@example.com. Ensure that you have authenticated with a developer tool that supports - Azure single sign on. - ``` - - To resolve this issue, please update to version 14.X.Y or later of the Azure PowerShell module, - or equivalently, version 5.X.Y of the Az.Accounts module. - With these versions, the Azure PowerShell cmdlets will be able to display detailed error messages - regarding which policy is blocking the authentication, and how to resolve the issue. - - For example, if the admin has configured the policy to require multi-factor authentication (MFA), - you will see an error message similar to the following: - - ```powershell - {Placeholder for error message} - ``` - - Follow the instructions in the error message to sign in through multi-factor authentication (MFA). diff --git a/docs-conceptual/azps-14.2.0/troubleshooting.md b/docs-conceptual/azps-14.2.0/troubleshooting.md index cdf65e5b2b..9b4cfc2679 100644 --- a/docs-conceptual/azps-14.2.0/troubleshooting.md +++ b/docs-conceptual/azps-14.2.0/troubleshooting.md @@ -55,6 +55,36 @@ Update-AzConfig -EnableLoginByWam $false - WAM popup window to select an account isn't easy to find. Minimize other windows to locate the popup window. +## SharedTokenCacheCredential authentication unavailable + +If you receive this error when running an Azure PowerShell cmdlet that creates or modifies Azure +resources, it's likely that you're blocked by the Microsoft Entra ID Conditional Access policy. + +The complete error message is as follows: + +```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. +``` + +To resolve this issue, update to one of the following versions: + +- **Az** PowerShell module version 14.X.Y or later +- Or equivalently, **Az.Accounts** PowerShell module version 5.X.Y or later + +These versions provide improved error messages that identify the specific Conditional Access policy +causing the issue and offer guidance for resolving it. + +For example, if your organization requires multifactor authentication (MFA), you see an error +message like: + +```powershell +{Placeholder for error message} +``` + +To complete sign-in using MFA, follow the instructions in the error message. + ## Installation This section contains a list of solutions to common problems when installing the Az PowerShell From e82b0e118e5a27005db9c56e99775e05067d1c00 Mon Sep 17 00:00:00 2001 From: "Mike F. Robbins" <6719572+mikefrobbins@users.noreply.github.com> Date: Thu, 17 Jul 2025 13:38:15 -0500 Subject: [PATCH 3/6] Moved errors to troubleshooting section of mfa doc --- .../azps-14.2.0/authenticate-mfa.md | 53 +++++++++++++++++++ .../azps-14.2.0/troubleshooting.md | 30 ----------- 2 files changed, 53 insertions(+), 30 deletions(-) diff --git a/docs-conceptual/azps-14.2.0/authenticate-mfa.md b/docs-conceptual/azps-14.2.0/authenticate-mfa.md index 835a0251e3..f0829f50e2 100644 --- a/docs-conceptual/azps-14.2.0/authenticate-mfa.md +++ b/docs-conceptual/azps-14.2.0/authenticate-mfa.md @@ -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 "" +``` + +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 "" + ``` + +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. @@ -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 diff --git a/docs-conceptual/azps-14.2.0/troubleshooting.md b/docs-conceptual/azps-14.2.0/troubleshooting.md index 9b4cfc2679..cdf65e5b2b 100644 --- a/docs-conceptual/azps-14.2.0/troubleshooting.md +++ b/docs-conceptual/azps-14.2.0/troubleshooting.md @@ -55,36 +55,6 @@ Update-AzConfig -EnableLoginByWam $false - WAM popup window to select an account isn't easy to find. Minimize other windows to locate the popup window. -## SharedTokenCacheCredential authentication unavailable - -If you receive this error when running an Azure PowerShell cmdlet that creates or modifies Azure -resources, it's likely that you're blocked by the Microsoft Entra ID Conditional Access policy. - -The complete error message is as follows: - -```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. -``` - -To resolve this issue, update to one of the following versions: - -- **Az** PowerShell module version 14.X.Y or later -- Or equivalently, **Az.Accounts** PowerShell module version 5.X.Y or later - -These versions provide improved error messages that identify the specific Conditional Access policy -causing the issue and offer guidance for resolving it. - -For example, if your organization requires multifactor authentication (MFA), you see an error -message like: - -```powershell -{Placeholder for error message} -``` - -To complete sign-in using MFA, follow the instructions in the error message. - ## Installation This section contains a list of solutions to common problems when installing the Az PowerShell From e90198cab3cde4cf46560ae6e38255bf428a788f Mon Sep 17 00:00:00 2001 From: "Mike F. Robbins" <6719572+mikefrobbins@users.noreply.github.com> Date: Thu, 17 Jul 2025 14:13:01 -0500 Subject: [PATCH 4/6] Wordsmithing based on copilot review --- docs-conceptual/azps-14.2.0/authenticate-mfa.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs-conceptual/azps-14.2.0/authenticate-mfa.md b/docs-conceptual/azps-14.2.0/authenticate-mfa.md index f0829f50e2..919a6e5f27 100644 --- a/docs-conceptual/azps-14.2.0/authenticate-mfa.md +++ b/docs-conceptual/azps-14.2.0/authenticate-mfa.md @@ -191,7 +191,7 @@ typically, that MFA is required but not enforced at login. ### Resolution steps -To resolve these errors, upgrade to either or these supported module versions: +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 From 57f036baf8f61c2d385d6089a0fcd2f84d9c2199 Mon Sep 17 00:00:00 2001 From: "Mike F. Robbins" <6719572+mikefrobbins@users.noreply.github.com> Date: Thu, 17 Jul 2025 20:50:43 -0500 Subject: [PATCH 5/6] Combined troubleshooting section into one article --- .../azps-14.2.0/authenticate-mfa.md | 93 ------------------ .../azps-14.2.0/troubleshooting.md | 97 +++++++++++++++++++ 2 files changed, 97 insertions(+), 93 deletions(-) diff --git a/docs-conceptual/azps-14.2.0/authenticate-mfa.md b/docs-conceptual/azps-14.2.0/authenticate-mfa.md index 919a6e5f27..31769946f7 100644 --- a/docs-conceptual/azps-14.2.0/authenticate-mfa.md +++ b/docs-conceptual/azps-14.2.0/authenticate-mfa.md @@ -159,99 +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 - -### 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: - - ```PowerShell - 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. - ## Learn more about multifactor authentication The Microsoft Entra ID documentation site offers more detail on MFA. diff --git a/docs-conceptual/azps-14.2.0/troubleshooting.md b/docs-conceptual/azps-14.2.0/troubleshooting.md index cdf65e5b2b..1e099111e5 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: + + ```PowerShell + 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 From f08e90e47d7619e8b7eebea973b013645122a61d Mon Sep 17 00:00:00 2001 From: "Mike F. Robbins" <6719572+mikefrobbins@users.noreply.github.com> Date: Thu, 17 Jul 2025 20:53:22 -0500 Subject: [PATCH 6/6] Corrected code fence label --- docs-conceptual/azps-14.2.0/troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs-conceptual/azps-14.2.0/troubleshooting.md b/docs-conceptual/azps-14.2.0/troubleshooting.md index 1e099111e5..d8c4f0b49a 100644 --- a/docs-conceptual/azps-14.2.0/troubleshooting.md +++ b/docs-conceptual/azps-14.2.0/troubleshooting.md @@ -73,7 +73,7 @@ Recommended Actions: - Alternative: If MFA can't be enforced at sign-in, use interactive authentication with the **ClaimsChallenge** parameter as shown in the following example: - ```PowerShell + ```azurepowershell Connect-AzAccount -Tenant (Get-AzContext).Tenant.Id -ClaimsChallenge "" ```