Устранение неполадок с модулем Az PowerShell

Включение ведения журнала отладки

Одним из первых шагов, которые необходимо предпринять при устранении неполадок с модулем Az PowerShell, является включение ведения журнала отладки.

Чтобы включить ведение журнала отладки для отдельных команд, укажите параметр Debug.

Get-AzResource -Name 'DoesNotExist' -Debug

Чтобы включить ведение журнала отладки для всего сеанса PowerShell, задайте для переменной DebugPreference значение Continue.

$DebugPreference = 'Continue'

Известная проблема: сбой установки модулей Az из MAR

При установке определенных модулей Az PowerShell из реестра артефактов Майкрософт (MAR) с помощью PSResourceGet может возникнуть ошибка, например:

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

Дополнительные сведения см. в разделе "Исправление ошибки" для сравнения имени пути к файлу, чтобы определить точное соответствие.

Устранение неполадок многофакторной проверки подлинности (MFA)

Сбои интерактивного входа

Если при выполнении командлетов Azure PowerShell, которые создают, изменяют или удаляют ресурсы, возникают ошибки, проблема может быть вызвана политикой условного доступа Microsoft Entra ID, требующей многофакторной проверки подлинности (MFA).

Эти ошибки обычно возникают, когда MFA требуется политикой, но не применяется во время входа.

Проверка подлинности SharedTokenCacheCredential недоступна

Эта ошибка может появиться при использовании:

• Аз Модуль PowerShell версии 14.2.0 или более ранней версии
• Модуль PowerShell Az.Accounts 5.1.1 или более ранний

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.

Обновите до следующих версий или более поздних версий, чтобы получить более информативные сообщения об ошибках и сведения о политике:

• Аз Модуль PowerShell: версия 14.3.0 или более поздняя
• Модуль Az.Accounts: версия 5.2.0 или более поздняя

Ресурс был запрещен политикой

Эта ошибка возникает в более новых версиях модуля (Az 14.3.0+ и Az.Accounts 5.2.0+), где MFA требуется условным доступом для определенных операций.

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

Параметры разрешения

• Попросите администратора Azure применить MFA при входе. Это позволяет сеансу соответствовать требованиям условного доступа без дополнительных действий.

• Если принудительное применение MFA при входе невозможно, используйте параметр ClaimsChallenge для интерактивной проверки подлинности:

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

Дополнительные сведения см. в разделе Планирование обязательной многофакторной аутентификации в Azure и других порталах администрирования

Ошибка ROPC: из-за изменения конфигурации, внесенного администратором

Вы используете поток Resource Owner Password Credential (ROPC) при входе в Azure с помощью пароля. Этот метод проверки подлинности не поддерживает MFA. Приведем пример:

Connect-AzAccount -Credential $Credential

Если для учетной записи пользователя требуется многофакторная проверка подлинности, команда завершается ошибкой ниже.

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

решение : Использовать метод проверки подлинности, совместимый с MFA.

Предупреждение о межарендаторском доступе: сбой аутентификации в арендаторе

Если у вас есть доступ к нескольким клиентам, и для одного из них требуется многофакторная проверка подлинности, Azure PowerShell может отобразить следующее предупреждение:

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 пытается войти с помощью первого найденного арендатора во время входа. Если этот пользователь применяет многофакторную аутентификацию (MFA), проверка подлинности может завершиться ошибкой. Чтобы избежать этой проблемы, явно укажите целевой клиент с помощью параметра TenantId:

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

Это гарантирует, что проверка подлинности выполняется в правильном арендаторе, что снижает вероятность сбоев, связанных с многофакторной аутентификацией.

Сообщения объявлений в сценариях автоматизации

При подключении к Azure с помощью Azure PowerShell сообщения объявлений отображаются с помощью потока сведений PowerShell, чтобы предотвратить изменение возвращаемых выходных данных на основе объектов. Хотя мы предприняли все усилия, чтобы гарантировать, что сообщения объявлений не влияют на ваш опыт, существуют некоторые сценарии автоматизации, в которых они могут повлиять на использование. При возникновении проблем рекомендуется отключить поток информации в этих сценариях:

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

Менеджер веб-учетных записей (WAM)

• Интерактивный метод входа не может открыть окно для WAM и возвращает ошибку: пользователь отменил проверку подлинности.
• Azure PowerShell командлеты не могут выполняться после входа с помощью имени пользователя и пароля или кода устройства.
• Всплывающее окно WAM не отображает параметр "Рабочая и учебная учетная запись ".
• Интерактивный метод входа не может открыть окно WAM в консоли Windows PowerShell ISE.

Обходной путь для этих проблем — отключить WAM:

Update-AzConfig -EnableLoginByWam $false

• Всплывающее окно WAM для выбора учетной записи не легко найти. Минимизируйте другие окна, чтобы найти всплывающее окно.

Installation

В этом разделе содержится список решений для распространенных проблем при установке модуля Az PowerShell.

Сосуществование Az и AzureRM

В сценарии, в котором необходимо установить модуль AzureRM и Az PowerShell в одной Windows системе:

• AzureRM необходимо установить только в текущей области пользователя Windows PowerShell 5.1.
• Установите модуль Az PowerShell в PowerShell 7.2 или более поздней версии.

Visual Studio

Более старые версии Visual Studio могут устанавливать Azure PowerShell в рамках рабочей нагрузки разработки Azure, которая устанавливает модуль AzureRM. Azure PowerShell можно удалить с помощью установщика Visual Studio или с помощью команды "Удалить" в функциях приложений и функций. Если вы уже установили PowerShell 7.x, может потребоваться вручную установить модуль Az PowerShell.

Прокси-сервер блокирует подключение

Если вы получаете ошибки из Install-Module, что коллекция PowerShell недоступна, возможно, вы находитесь за прокси-сервером. Различные операционные системы и сетевая среда имеют разные требования к настройке прокси-сервера на уровне системы. Обратитесь к системному администратору, чтобы узнать о параметрах своего прокси-сервера и о том, как настроить их для своей среды.

Сам PowerShell не может быть настроен для автоматического использования этого прокси-сервера. С помощью PowerShell 5.1 и более поздних версий настройте сеанс PowerShell для использования прокси-сервера с помощью следующих команд:

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

Если учетные данные операционной системы настроены правильно, эта конфигурация направляет запросы PowerShell через прокси-сервер. Чтобы такое поведение сохранялось между сеансами, добавьте команду в профиль PowerShell.

Для установки пакета ваш прокси-сервер должен разрешать HTTPS-подключения по следующему адресу: www.powershellgallery.com.

Ссылка на объект не установлена для экземпляра объекта

Сообщение "ссылка на объект не указывает на экземпляр объекта" означает, что вы ссылаетесь на объект, который является null, или на ресурс Azure, который не существует, или у вас нет разрешений на доступ.

$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.

Для проверки наличия указанного ресурса Azure можно использовать командлет Get-AzResource.

Get-AzResource -ResourceId $resourceId

Проблемы с разрешениями командлетов AzAD

Модуль Az PowerShell использует microsoft API Graph. Для администрирования ресурсов в Azure с помощью модуля Az PowerShell требуются те же разрешения, что и для выполнения идентичной задачи на портале Azure или любом другом средстве командной строки Azure. Дополнительные вопросы о разрешениях см. в справочнике по разрешениям Microsoft Graph.

параметры запроса Microsoft Graph

Командлеты AzAd в Az.Resources теперь поддерживают параметры запросов и параметры запросов поиска. Дополнительные сведения о синтаксисе см. в ранее указанных ссылках.

Get-AzAdGroupMember не возвращает учетные записи служб

Из-за ограничений текущего API Graph, команды Get-AzAdGroupMember в Az 7.x не возвращают служебные учетные записи. В качестве обходного решения можно использовать Invoke-AzRestMethod<>/c0> с бета-версией Microsoft API Graph.

В следующем примере требуется модуль Az PowerShell. Замените myGroupName в первой строке именем группы.

$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'}}

Команда найдена, но не может быть загружена

Следующее сообщение возвращается PowerShell при попытке выполнить любую из команд 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'.

Это сообщение возникает при наличии модулей Az и AzureRM PowerShell, установленных в одной Windows системе, и они существуют в $env:PSModulePath для той же версии PowerShell.

Az и AzureRM могут сосуществовать в одной системе Windows, но только если AzureRM установлен в области CurrentUser Windows PowerShell и Az установлен в PowerShell 7. Дополнительные сведения см. в статье Установка модуля Az PowerShell.

В MacOS ошибка возвращается при сбое авторизации KeyChain

При запуске Azure PowerShell в MacOS может возникнуть сообщение об ошибке при попытке входа в учетную запись Azure из сеанса PowerShell.

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

В качестве обходного решения этой проблемы можно отключить хранение учетных данных между сеансами, выполнив следующую команду. Однако после внесения этого изменения необходимо запускать Connect-AzAccount при каждом запуске нового сеанса PowerShell.

Disable-AzContextAutosave

Подключение для этого сайта не является безопасным

Если ваш браузер по умолчанию — Microsoft Edge, вы можете столкнуться со следующей ошибкой при попытке интерактивного входа в Azure с помощью Connect-AzAccount: "Соединение с этим сайтом не является безопасным." Чтобы решить эту проблему, посетите edge://net-internals/#hsts в Microsoft Edge. Добавьте localhost в раздел "Удалить политику безопасности домена" и нажмите кнопку "Удалить".

Ошибка связанная с IdentifierUri проверенного домена для главного объекта службы

Ошибка Значения свойства identifierUris должны использовать проверенный домен организации или ее поддомен отображается при выполнении New-AzADServicePrincipal или New-AzADApplication.

Из-за критических изменений Microsoft Entra, требующих AppId URI в однопользовательских приложениях, что требует использования схемы по умолчанию или проверенных доменов, необходимо обновить модуль Az.Resources до версии 4.1.0 или более поздней, чтобы продолжить использование командлетов New-AzADServicePrincipal или New-AzADApplication.

Вы также можете обновить модуль Az PowerShell до версии 6.0 или более новой.

Временная шкала

Требование вступило в силу 15 октября 2021 года.

Затронутые версии

На следующие версии Azure PowerShell повлияли критические изменения в AzureAD:

• Модуль Az.Resources PowerShell версии 3.5.1-preview или более ранней.
• Модуль Az PowerShell версии 5.9.0 или меньше.

Если после обновления по-прежнему возникают проблемы, смело откройте проблему.

Обходной путь

Если вы не можете обновить модули PowerShell, описанные ранее, можно выполнить следующие действия при создании субъекта-службы:

• При необходимости добавьте пользовательское доменное имя с помощью административного центра Microsoft Entra
• Создание приложения с принятым идентификаторомUri
• Создайте учетную запись службы, ссылающуюся на это приложение

Другие проблемы

Если у вас возникла проблема с продуктом Azure PowerShell, которая не указана в этой статье, или требуется дополнительная помощь, отправьте запрос на GitHub.