Skip to content

Commit e82b0e1

Browse files
committed
Moved errors to troubleshooting section of mfa doc
1 parent d44e154 commit e82b0e1

File tree

2 files changed

+53
-30
lines changed

2 files changed

+53
-30
lines changed

docs-conceptual/azps-14.2.0/authenticate-mfa.md

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -161,6 +161,58 @@ To learn more about federated identities, see:
161161

162162
## Troubleshooting
163163

164+
### Multifactor authentication (MFA) interactive login failures
165+
166+
If you encounter errors when running Azure PowerShell cmdlets that create, modify, or delete Azure
167+
resources, the issue might be caused by a Microsoft Entra ID conditional access policy that requires
168+
multifactor authentication (MFA).
169+
170+
#### Common error messages
171+
172+
You might see an error like the following:
173+
174+
```Output
175+
Resource was disallowed by policy. Users must use MFA for Create operation.
176+
Users must authenticate with multi-factor authentication to create or update resources.
177+
Run the cmdlet below to authenticate interactively; additional parameters may be added as needed.
178+
Connect-AzAccount -Tenant (Get-AzContext).Tenant.Id -ClaimsChallenge "<claims-challenge-token>"
179+
```
180+
181+
Or:
182+
183+
```Output
184+
SharedTokenCacheCredential authentication unavailable. Token acquisition failed for user
185+
[email protected]. Ensure that you have authenticated with a developer tool that supports Azure
186+
single sign on.
187+
```
188+
189+
These messages indicate that your session doesn't meet the conditional access requirements,
190+
typically, that MFA is required but not enforced at login.
191+
192+
### Resolution steps
193+
194+
To resolve these errors, upgrade to either or these supported module versions:
195+
196+
- **Az** PowerShell module: version 14.3.0 or later
197+
- **Az.Accounts** module: version 5.x.y or later
198+
199+
These versions improve error reporting by identifying the exact conditional access policy causing
200+
the issue and providing guidance.
201+
202+
Recommended Actions:
203+
204+
- Preferred: Ask your Azure administrator to enforce MFA at sign-in for your account. This ensures
205+
compatibility with conditional access policies that require MFA.
206+
- Alternative: If MFA can't be enforced at sign-in, use interactive authentication with the
207+
**ClaimsChallenge** parameter as shown in the following example:
208+
209+
```PowerShell
210+
Connect-AzAccount -Tenant (Get-AzContext).Tenant.Id -ClaimsChallenge "<claims-challenge-token>"
211+
```
212+
213+
For more information about Microsoft Entra ID conditional access policies that require MFA, see
214+
[Planning for mandatory multifactor authentication for Azure and other admin portals][01]
215+
164216
### ROPC error: Due to a configuration change made by your administrator
165217

166218
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.
233285
[steps-assign-role]: /azure/role-based-access-control/role-assignments-steps
234286
[assign-roles]: /azure/role-based-access-control/role-assignments-powershell
235287
[fic-serviceconn-blog]: https://devblogs.microsoft.com/azure-sdk/improve-security-posture-in-azure-service-connections-with-azurepipelinescredential/
288+
[01]: /entra/identity/authentication/concept-mandatory-multifactor-authentication

docs-conceptual/azps-14.2.0/troubleshooting.md

Lines changed: 0 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -55,36 +55,6 @@ Update-AzConfig -EnableLoginByWam $false
5555
- WAM popup window to select an account isn't easy to find. Minimize other windows to locate the
5656
popup window.
5757

58-
## SharedTokenCacheCredential authentication unavailable
59-
60-
If you receive this error when running an Azure PowerShell cmdlet that creates or modifies Azure
61-
resources, it's likely that you're blocked by the Microsoft Entra ID Conditional Access policy.
62-
63-
The complete error message is as follows:
64-
65-
```Output
66-
SharedTokenCacheCredential authentication unavailable. Token acquisition failed for user
67-
[email protected]. Ensure that you have authenticated with a developer tool that supports
68-
Azure single sign on.
69-
```
70-
71-
To resolve this issue, update to one of the following versions:
72-
73-
- **Az** PowerShell module version 14.X.Y or later
74-
- Or equivalently, **Az.Accounts** PowerShell module version 5.X.Y or later
75-
76-
These versions provide improved error messages that identify the specific Conditional Access policy
77-
causing the issue and offer guidance for resolving it.
78-
79-
For example, if your organization requires multifactor authentication (MFA), you see an error
80-
message like:
81-
82-
```powershell
83-
{Placeholder for error message}
84-
```
85-
86-
To complete sign-in using MFA, follow the instructions in the error message.
87-
8858
## Installation
8959

9060
This section contains a list of solutions to common problems when installing the Az PowerShell

0 commit comments

Comments
 (0)