Risoluzione dei problemi relativi al modulo Az PowerShell

Abilitare la registrazione di debug

Uno dei primi passaggi da eseguire per risolvere un problema con il modulo Az PowerShell consiste nell'abilitare la registrazione di debug.

Per abilitare la registrazione di debug per ogni comando, specificare il parametro Debug.

Get-AzResource -Name 'DoesNotExist' -Debug

Per abilitare la registrazione di debug per un'intera sessione di PowerShell, devi impostare il valore della variabile DebugPreference su Continue.

$DebugPreference = 'Continue'

Problema noto: l'installazione dei moduli Az da MAR ha esito negativo

Quando si installano determinati moduli Az PowerShell dal Registro di sistema artefatto Microsoft (MAR) usando PSResourceGet, è possibile che si verifichi un errore, ad esempio:

Install-PSResource: Package(s) 'Az.Keyvault' could not be installed from repository 'MAR'.

Per altre informazioni, vedere Bugfix per confrontare il nome del percorso del file per determinare la corrispondenza esatta.

Risoluzione dei problemi di autenticazione a più fattori (MFA)

Errori di accesso interattivi

Se si verificano errori durante l'esecuzione di cmdlet di Azure PowerShell che creano, modificano o eliminano risorse, il problema potrebbe essere causato da un criterio di accesso condizionale di Microsoft Entra ID che richiede l'autenticazione a più fattori (MFA).

Questi errori si verificano in genere quando l'autenticazione a più fattori è richiesta dai criteri, ma non viene applicata durante l'accesso.

Autenticazione SharedTokenCacheCredential non disponibile

Questo errore potrebbe essere visualizzato quando si usa:

• Az Modulo PowerShell versione 14.2.0 o precedente
• Modulo PowerShell Az.Accounts 5.1.1 o versioni precedenti

SharedTokenCacheCredential authentication unavailable. Token acquisition failed for user
[email protected]. Ensure that you have authenticated with a developer tool that supports Azure
single sign on.

Eseguire l'aggiornamento alle versioni seguenti o versioni successive per ricevere messaggi di errore e dettagli sui criteri più informativi:

• Az Modulo PowerShell: versione 14.3.0 o successiva
• Modulo Az.Accounts : versione 5.2.0 o successiva

Risorsa non consentita dai criteri

Questo errore si verifica nelle versioni più recenti del modulo (Az 14.3.0+ e Az.Accounts 5.2.0+), dove L'autenticazione a più fattori è richiesta dall'accesso condizionale per operazioni specifiche.

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>"

Opzioni di risoluzione

• Chiedere all'amministratore di Azure di applicare l'autenticazione a più fattori all'accesso. Ciò consente alla sessione di soddisfare i requisiti di accesso condizionale senza passaggi aggiuntivi.

• Se l'imposizione dell'autenticazione a più fattori all'accesso non è possibile, usare il parametro ClaimsChallenge per eseguire l'autenticazione interattiva:

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

Per altre informazioni, vedere Pianificazione dell'autenticazione a più fattori obbligatoria per Azure e altri portali di amministrazione

Errore ROPC: a causa di una modifica della configurazione apportata dall'amministratore

Usa il flusso ROPC (Resource Owner Password Credential) quando effettui l'accesso ad Azure utilizzando una password. Questo metodo di autenticazione non supporta l'autenticazione a più fattori. Ecco un esempio:

Connect-AzAccount -Credential $Credential

Se l'account utente richiede l'autenticazione a più fattori, il comando non riesce con l'errore seguente:

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

Soluzione: Usare un metodo di autenticazione compatibile con MFA.

Avviso tra tenant: Autenticazione fallita per il tenant

Se hai accesso a più tenant e uno di essi richiede l'autenticazione a più fattori, Azure PowerShell potrebbe mostrare il seguente avviso:

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 tenta di accedere con il primo tenant trovato durante l'accesso. Se tale tenant applica l'autenticazione a più fattori, l'autenticazione potrebbe non riuscire. Per evitare questo problema, specificare in modo esplicito il tenant di destinazione usando il parametro TenantId:

Connect-AzAccount -TenantId 00000000-0000-0000-0000-000000000000

In questo modo si garantisce che l'autenticazione venga eseguita per il tenant corretto, riducendo la probabilità di errori correlati a MFA.

Messaggi di annuncio negli scenari di automazione

Quando ci si connette ad Azure con Azure PowerShell, i messaggi di annuncio vengono visualizzati usando il flusso di informazioni di PowerShell per impedire che modifichino l'output restituito basato su oggetti. Anche se abbiamo fatto ogni sforzo per garantire che i messaggi di annuncio non influiscano sull'esperienza, esistono alcuni scenari di automazione in cui potrebbero influire sull'utilizzo. In caso di problemi, è consigliabile eliminare il flusso di informazioni in questi scenari:

Connect-AzAccount -Subscription '<subscription name or id>' -InformationAction Ignore

Responsabile degli Account Web (WAM)

• Il metodo di accesso interattivo non può aprire una finestra per WAM e restituisce l'errore: Autenticazione annullata dall'utente.
• I cmdlet di Azure PowerShell non possono essere eseguiti dopo l'accesso con un nome utente e una password o un codice del dispositivo.
• La finestra popup di WAM non visualizza l'opzione Account aziendale e dell'istituto di istruzione.
• Il metodo di accesso interattivo non può aprire una finestra WAM nella console di Windows PowerShell ISE.

La soluzione alternativa per questi problemi consiste nel disabilitare WAM:

Update-AzConfig -EnableLoginByWam $false

• La finestra popup di WAM per selezionare un account non è facile da trovare. Ridurre al minimo le altre finestre per individuare la finestra popup.

Installazione

Questa sezione contiene un elenco di soluzioni ai problemi comuni durante l'installazione del modulo Az PowerShell.

Coesistenza di Az e AzureRM

In uno scenario in cui è necessario installare il modulo AzureRM e Az PowerShell nello stesso sistema Windows:

• AzureRM deve essere installato solo nell'ambito utente corrente di Windows PowerShell 5.1.
• Installare il modulo Az PowerShell in PowerShell 7.2 o versione successiva.

Visual Studio

Le versioni precedenti di Visual Studio possono installare Azure PowerShell come parte del carico di lavoro di sviluppo di Azure, che installa il modulo AzureRM. Azure PowerShell può essere rimosso usando il programma di installazione di Visual Studio o "Disinstalla" in App e funzionalità. Se è già installato PowerShell 7.x, potrebbe essere necessario installare manualmente il modulo Az PowerShell.

Il proxy blocca la connessione

Se ricevi errori da Install-Module secondo cui la PowerShell Gallery non è raggiungibile, potresti essere dietro un proxy. Diversi sistemi operativi e ambienti di rete hanno requisiti diversi per la configurazione di un proxy a livello di sistema. Per conoscere le impostazioni del proxy e sapere come configurarlo per l'ambiente corrente, contattare l'amministratore di sistema.

PowerShell stesso potrebbe non essere configurato per l'uso automatico di questo proxy. Con PowerShell 5.1 e versioni successive, configurare la sessione di PowerShell per l'uso di un proxy usando i comandi seguenti:

$webClient = New-Object -TypeName System.Net.WebClient
$webClient.Proxy.Credentials = [System.Net.CredentialCache]::DefaultNetworkCredentials

Se le credenziali del sistema operativo sono configurate correttamente, questa configurazione instrada le richieste di PowerShell tramite il proxy. Per rendere persistente questa impostazione tra una sessione e l'altra, aggiungere i comandi al proprio profilo PowerShell.

Per installare il pacchetto, il proxy deve consentire le connessioni HTTPS a www.powershellgallery.com.

Il riferimento all'oggetto non è impostato su un'istanza di un oggetto.

Il messaggio "Riferimento oggetto non impostato su un'istanza di un oggetto" significa che si sta facendo riferimento a un oggetto null o a una risorsa di Azure che non esiste oppure che non si dispone delle autorizzazioni per l'accesso.

$resourceId =  '/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/<resource-group-name>/providers/Microsoft.Web/sites/<webapp-name>/privateEndpointConnections/<endpoint-name>'
Get-AzPrivateEndpointConnection -ResourceId $resourceId

Get-AzPrivateEndpointConnection: Object reference not set to an instance of an object.

È possibile usare il cmdlet Get-AzResource per verificare che la risorsa di Azure specificata esista.

Get-AzResource -ResourceId $resourceId

Problemi di autorizzazione con i cmdlet AzAD

Il modulo Az PowerShell usa l'API Microsoft Graph. L'amministrazione o la gestione delle risorse in Azure con il modulo Az PowerShell richiede le stesse autorizzazioni dell'esecuzione dell'attività identica dal portale di Azure o da qualsiasi altro strumento da riga di comando di Azure. Per domande specifiche sulle autorizzazioni, vedere Riferimento alle autorizzazioni di Microsoft Graph.

Parametri di query di Microsoft Graph

Ora i cmdlet AzAd in Az.Resources supportano i parametri di query e i parametri di ricerca . Per informazioni dettagliate sulla sintassi, vedere i collegamenti a cui si fa riferimento in precedenza.

Get-AzAdGroupMember non restituisce i principali di servizio

A causa delle limitazioni dell'API Graph corrente, le entità di servizio non vengono restituite da Get-AzAdGroupMember in Az 7.x. Come soluzione alternativa, è possibile usare Invoke-AzRestMethod con la versione beta dell'API Microsoft Graph.

L'esempio seguente richiede il modulo Az PowerShell. Sostituire myGroupName nella prima riga con il nome del gruppo.

$Group = Get-AzADGroup -DisplayName myGroupName
((Invoke-AzRestMethod -Uri "https://graph.microsoft.com/beta/groups/$($Group.id)/members").Content |
  ConvertFrom-Json).value |
  Select-Object -Property DisplayName, Id, @{label='OdataType';expression={$_.'@odata.type'}}

Il comando è stato trovato ma non è stato possibile caricarlo

Il messaggio seguente viene restituito da PowerShell quando si tenta di eseguire uno dei comandi Az PowerShell.

Connect-AzAccount: The 'Connect-AzAccount' command was found in the module 'Az.Accounts', but the module could not be loaded. For more information, run 'Import-Module Az.Accounts'.

Questo messaggio si verifica quando sono installati entrambi i moduli Az e AzureRM PowerShell nello stesso sistema basato su Windows e sono presenti nel $env:PSModulePath per la stessa versione di PowerShell.

Sia Az che AzureRM possono coesistere nello stesso sistema Windows, ma solo se AzureRM è installato nell'ambito CurrentUser di Windows PowerShell e Az è installato in PowerShell 7. Per altre informazioni, vedere Installare il modulo Az PowerShell.

In macOS viene restituito un errore quando l'autorizzazione KeyChain fallisce

Quando si esegue Azure PowerShell in MacOS, è possibile che venga visualizzato un messaggio di errore durante il tentativo di accedere all'account Azure da una sessione di PowerShell.

DeviceCodeCredential authentication failed: Persistence check failed. Reason: KeyChain authorization/authentication failed. .Error code: -25293. OS error code -25293.

Come soluzione alternativa a questo problema, è possibile disabilitare l'archiviazione delle credenziali tra le sessioni eseguendo il comando seguente. Dopo aver apportato questa modifica, è tuttavia necessario eseguire Connect-AzAccount ogni volta che si avvia una nuova sessione di PowerShell.

Disable-AzContextAutosave

La connessione per il sito non è sicura

Quando il browser predefinito è Microsoft Edge, è possibile che si verifichi l'errore seguente quando si tenta di accedere ad Azure in modo interattivo con Connect-AzAccount: "La connessione per questo sito non è sicura." Per risolvere questo problema, visitare edge://net-internals/#hsts in Microsoft Edge. Aggiungere localhost in "Elimina criteri di sicurezza del dominio" e fare clic su Elimina.

Errore del dominio verificato di Service Principal IdentifierUri

Errore: i valori della proprietà identifierUris devono usare un dominio verificato dell'organizzazione o il relativo sottodominio viene visualizzato durante l'esecuzione di New-AzADServicePrincipal o New-AzADApplication.

A causa della modifica rivoluzionaria di Microsoft Entra che richiede che l'Uri AppId nelle applicazioni a tenant singolo utilizzi lo schema predefinito o domini verificati, è necessario aggiornare il modulo Az.Resources alla versione 4.1.0 o successiva per continuare a utilizzare i cmdlet New-AzADServicePrincipal o New-AzADApplication.

È anche possibile eseguire l'aggiornamento al modulo Az PowerShell versione 6.0 o successiva.

Sequenza temporale

Il requisito è entrato in vigore il 15 ottobre 2021.

Versioni interessate

Le versioni seguenti di Azure PowerShell sono interessate dalla modifica importante di AzureAD:

• Modulo Az.Resources PowerShell versione 3.5.1-preview o inferiore.
• Modulo Az PowerShell versione 5.9.0 o inferiore.

Se si verificano ancora problemi dopo l'aggiornamento, è possibile aprire un problema.

Soluzione

Se non è possibile eseguire l'aggiornamento ai moduli di PowerShell descritti in precedenza, è possibile seguire questi passaggi durante la creazione di un'entità servizio:

• Se necessario, aggiungere il nome di dominio personalizzato usando l'interfaccia di amministrazione di Microsoft Entra
• Creare un'applicazione con un IdentifierUri accettato
• Creare un service principal che fa riferimento a questa applicazione

Altri problemi

Se si verifica un problema di prodotto con Azure PowerShell non elencato in questo articolo o si richiede ulteriore assistenza, segnalare un problema in GitHub.