Устранение неполадок с модулем 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
[email protected]. 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: из-за изменения конфигурации, внесенного администратором

При входе в Azure с использованием пароля используется поток паролей владельца ресурса (ROPC). Этот метод проверки подлинности не поддерживает 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.

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

Если у вас есть доступ к нескольким клиентам, и для одного из них требуется 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 использует API Microsoft Graph. Для администрирования или управления ресурсами в Azure с помощью модуля Az PowerShell требуются те же разрешения, что и для выполнения идентичной задачи с портала Azure или любого другого средства командной строки Azure. По конкретным вопросам о разрешениях смотрите справочник по разрешениям Microsoft Graph.

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

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

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

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

Это сообщение отображается, если в одной системе Windows установлены оба модуля Az и AzureRM PowerShell, которые указаны в переменной $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, требующего URI AppId в приложениях с одним арендатором для использования схемы по умолчанию или проверенных доменов, необходимо обновить модуль 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.