Освоение потока управляемой идентичности с PowerShell и Microsoft Graph

By Mirko Peters · 2026-08-28

Добро пожаловать обратно в блог подкаста! Если вам когда-либо мешали жёстко заданные в коде пароли, громоздкое управление секретами клиентов или тревога о том, что учётные данные утекут из автоматизированных скриптов…

Automatically translated with AI from the original post. Read the English original

Добро пожаловать обратно в блог подкаста! Если вам когда-либо мешали жёстко заданные в коде пароли, громоздкое управление секретами клиентов или тревога о том, что учётные данные утекут из автоматизированных скриптов, вы попали по адресу. Автоматизация в облаке требует пересмотра подхода к безопасности. Прошли те времена, когда администраторы могли спокойно прятать учётные данные в конфигурационных файлах с открытым текстом или в переменных среды, не оглядываясь через плечо. Сегодня мы подробно разберём аутентификацию, ориентированную на облако, и рассмотрим, как использовать управляемые идентификаторы Azure в ваших скриптах PowerShell, чтобы безопасно проходить аутентификацию в Microsoft Graph без хранения конфиденциальных учётных данных.

Автоматизация среды Microsoft 365 уже давно перестала быть полезным дополнением; это абсолютная операционная необходимость. Однако сочетание PowerShell с API Microsoft Graph иногда напоминает блуждание по лабиринту из запросов на разрешения, ограничений скорости запросов и сложных потоков получения токенов. Перейдя к современному подходу, ориентированному на идентификацию, мы можем полностью отказаться от управления учётными данными для рабочих нагрузок, работающих в Azure. В этой статье мы разберём основные компоненты аутентификации, ориентированной на облако: предварительные требования, регистрации приложений в Azure AD, потоки получения токенов и оптимизацию скриптов. Если вы хотите глубже изучить именно этот сценарий, обязательно послушайте наш сопутствующий эпизод подкаста: Use Managed Identity with PowerShell for Microsoft Graph.

Предварительные требования для PowerShell + Graph API

Прежде чем начать автоматизировать задачи Microsoft 365 с помощью PowerShell и Graph API, необходимо должным образом подготовить систему и среду. Такая подготовка обеспечивает корректное выполнение и безопасный доступ к ресурсам Microsoft Graph.

Установка модулей PowerShell

Для взаимодействия с API Microsoft Graph нужно установить подходящие модули PowerShell. Microsoft Graph PowerShell SDK предоставляет все необходимые командлеты для этой интеграции. Чтобы избежать ошибок, проверьте, что ваша система соответствует минимальным требованиям:

Обновить PowerShellGet можно командой Install-Module PowerShellGet -Force, а политику выполнения задать командой Set-ExecutionPolicy RemoteSigned. После этого установите модуль Microsoft Graph с помощью:

Install-Module Microsoft.Graph -Scope CurrentUser

Эта команда загружает последнюю стабильную версию модуля, что позволяет легко вызывать конечные точки Microsoft Graph.

Настройка среды Microsoft 365

Правильная настройка среды Microsoft 365 имеет решающее значение для автоматизации. Чтобы начать, выполните следующие шаги:

1. Убедитесь, что система соответствует требованиям: PowerShell 7.2 или выше, .NET Framework 4.7.2 или новее и последняя версия модуля PowerShellGet.
2. Установите модуль Microsoft Graph PowerShell, как показано выше.
3. Подключитесь к клиенту Microsoft 365, импортировав модуль и выполнив аутентификацию с необходимыми областями доступа. Например:

Connect-MgGraph -Scopes "User.ReadWrite.All","Directory.ReadWrite.All"

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

Понимание разрешений и областей доступа

Разрешения и области доступа определяют, что ваши скрипты могут просматривать или изменять в Microsoft 365. API Microsoft Graph использует два основных типа разрешений:

• Делегированные разрешения: Они применяются, когда вы запускаете скрипты от имени вошедшего пользователя. Такие разрешения ограничивают доступ к данным, которыми владеет пользователь или к которым он может получить доступ.
• Разрешения приложения: Они позволяют вашему приложению или скрипту получать доступ к данным во всей организации без участия вошедшего пользователя. Это типично для фоновой автоматизации и сценариев с управляемой идентификацией.

Распространённые разрешения включают *.Read.All для доступа только на чтение и *.ReadWrite.All для полного доступа на чтение и запись. Например, SecurityActions.Read.All позволяет просматривать действия безопасности, а SecurityActions.ReadWrite.All разрешает их изменять.

Разрешения приложения требуют согласия администратора. Администратор клиента должен одобрить эти разрешения, чтобы обеспечить безопасность. Кроме того, пользователям нужны соответствующие роли Microsoft Entra, например Security Reader, для доступа к конфиденциальным данным. Такой доступ на основе ролей добавляет дополнительный уровень защиты.

При подключении с помощью Microsoft Graph PowerShell SDK указывайте только те области (scopes), которые нужны вашему скрипту. Этот подход соответствует принципу наименьших привилегий и снижает риски для безопасности. Имейте в виду, что разрешения, предоставленные вашему приложению, применяются ко всем пользователям этого приложения, поэтому регулярно их проверяйте и управляйте ими.

Идентификация приложений в Azure AD

Регистрация нового приложения

Чтобы автоматизировать задачи Microsoft 365 с помощью PowerShell и Graph API, сначала нужно зарегистрировать приложение в Azure Active Directory (Azure AD). Это приложение выступает в роли идентификатора, который ваши скрипты используют для безопасного доступа к Microsoft Graph. Выполните следующие шаги, чтобы зарегистрировать приложение:

1. Откройте портал Azure и перейдите в Azure Active Directory > Регистрации приложений > Новая регистрация.
2. Дайте приложению понятное имя, например «My Graph Automation App».
3. Выберите поддерживаемые типы учётных записей:
   • Одиночный клиент: войти могут только пользователи вашего клиента Azure AD.
   • Многоклиентская: войти могут пользователи любого клиента Azure AD.
   • Многоклиентская и личные учётные записи: включает пользователей Azure AD и личные учётные записи Microsoft.
4. Укажите Redirect URI в зависимости от типа приложения:
   • Для веб-приложений используйте URL вида https://yourapp.com/auth/callback.
   • Для одностраничных приложений используйте https://yourapp.com.
   • Для мобильных или настольных приложений используйте https://login.microsoftonline.com/common/oauth2/nativeclient.
5. Нажмите Зарегистрировать, чтобы создать приложение.

В результате в вашем клиенте создаётся уникальная идентификация приложения. Она используется для запроса токенов и вызовов Microsoft Graph API.

Настройка разрешений API

После регистрации приложения необходимо настроить разрешения API, которые ему нужны. Эти разрешения определяют, к каким данным в Microsoft 365 приложение может получать доступ или которые может изменять. Чтобы задать разрешения:

1. В регистрации приложения перейдите в Разрешения API > Добавить разрешение > Microsoft Graph.
2. Выберите Разрешения приложения, если скрипт работает без интерфейса или в контексте управляемой идентификации, либо Делегированные разрешения, если он работает в интерактивном режиме.
3. Выберите конкретные разрешения, которые нужны приложению, например User.Read.All или Directory.Read.All.
4. Нажмите Добавить разрешения, чтобы их применить.

⚠️ Всегда применяйте принцип наименьших привилегий. Назначайте только те разрешения, которые нужны приложению, чтобы снизить риски для безопасности.

Некоторые разрешения требуют согласия администратора до того, как приложение сможет их использовать. Вы можете предоставить это согласие, нажав Предоставить согласие администратора для [имя клиента] на портале Azure. Регулярно проверяйте разрешения, чтобы не выдавать приложению избыточных прав.

Создание клиентского секрета или сертификата

Вашему приложению нужны учетные данные для безопасной аутентификации в Azure AD, если вы не используете управляемое удостоверение. Можно использовать либо секрет клиента, либо сертификат. Оба способа подтверждают идентичность вашего приложения при запросе токенов.

Чтобы создать секрет клиента, откройте Certificates & secrets в регистрации вашего приложения, выберите New client secret, добавьте описание и задайте срок действия. Для сертификатов загрузите действительный файл сертификата в том же разделе.

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

Что такое OAuth 2.0

OAuth 2.0 играет ключевую роль в защите доступа к Microsoft Graph API при использовании PowerShell + Graph API. Он выступает в роли доверенного привратника, который позволяет вашим приложениям безопасно проходить аутентификацию и получать токены доступа. Эти токены служат цифровыми ключами: они дают вашим скриптам право обращаться к конечным точкам Microsoft Graph без прямой передачи учетных данных.

Чтобы использовать OAuth 2.0, сначала необходимо зарегистрировать приложение в Azure Active Directory (Azure AD). Регистрация предоставляет учетные данные клиента, такие как идентификатор приложения и секрет или сертификат. Когда скрипт запрашивает токен доступа, он предъявляет эти учетные данные Azure AD. Azure AD проверяет вашу личность и выдает токен с коротким сроком действия. Скрипт включает этот токен в запросы к API, чтобы подтвердить право на доступ к запрашиваемым ресурсам.

Такой процесс обеспечивает безопасный и контролируемый доступ к данным Microsoft 365. Он также поддерживает детализированные разрешения, поэтому ваши скрипты получают только необходимый доступ. Следуя стандартам OAuth 2.0, вы защищаете среду от несанкционированного доступа и при этом получаете мощную автоматизацию с PowerShell + Graph API.

Использование PowerShell для запросов токенов

Токены доступа можно получить с помощью нескольких сценариев аутентификации, подобранных под разные задачи. Каждый из них по-разному balansирует между безопасностью и удобством. Microsoft Graph API поддерживает следующие распространенные сценарии:

• Device Code Flow: подходит для устройств или скриптов без браузера и средств ввода. Вы проходите аутентификацию на отдельном устройстве, что делает процесс безопасным и удобным для пользователя.
• Certificate-Based Flow: предназначен для автоматизации без участия пользователя (headless). Этот сценарий использует сертификаты вместо паролей, повышая безопасность неинтерактивных скриптов.
• Managed Identity Flow: лучше всего подходит для облачных сред, таких как Azure Functions или виртуальные машины. Сценарий использует управляемые удостоверения Azure, чтобы получать токены без хранения секретов.

Device Code Flow

Device Code Flow хорошо работает, когда вы запускаете скрипты локально или на устройствах без удобных средств ввода. Он позволяет пройти интерактивную аутентификацию на другом устройстве, например в браузере телефона или ПК.

Вот как использовать Device Code Flow с PowerShell:

1. Выполните следующую команду, чтобы запустить аутентификацию с помощью кода устройства:

   Connect-MgGraph -Scopes "User.Read.All" -DeviceCode

2. PowerShell отобразит код и URL-адрес. Откройте URL-адрес в браузере на любом устройстве.
3. Введите код, показанный в PowerShell, и выполните вход с помощью вашей учетной записи Microsoft 365.
4. После успешной аутентификации PowerShell получит токен доступа и подключит вашу сессию.

💡 Device Code Flow сочетает безопасность и удобство. Он не требует встраивать учетные данные в скрипты и хорошо подходит для ручных или полуавтоматических задач.

Сертификатная аутентификация

Certificate-Based Flow подходит для автоматизированных скриптов, которые работают без участия пользователя. Вместо секрета клиента вы используете сертификат, чтобы подтвердить идентичность приложения. Этот метод снижает риски, связанные с утечкой секретов.

Чтобы использовать этот сценарий, выполните следующие шаги:

1. Зарегистрируйте приложение в Azure AD и загрузите сертификат в разделе Certificates & secrets.
2. Храните сертификат безопасно на компьютере, где запускается ваш скрипт.
3. Используйте PowerShell, чтобы запросить токен, указав отпечаток сертификата, идентификатор клиента (client ID) и идентификатор клиента Microsoft Entra (tenant ID).

Ниже простой пример получения токена с помощью сертификата в PowerShell:

$tenantId = "YOUR_TENANT_ID"
$clientId = "YOUR_CLIENT_ID"
$certThumbprint = "YOUR_CERT_THUMBPRINT"
$cert = Get-Item Cert:\CurrentUser\My\$certThumbprint
$body = @{
    grant_type = "client_credentials"
    client_id = $clientId
    scope = "https://graph.microsoft.com/.default"
    client_assertion_type = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
    client_assertion = New-JwtToken -Certificate $cert -TenantId $tenantId -ClientId $clientId
}
$tokenResponse = Invoke-RestMethod -Method Post -Uri "https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token" -Body $body
$accessToken = $tokenResponse.access_token

⚠️ Работа с сертификатами требует осторожности. Защищайте закрытые ключи и регулярно обновляйте сертификаты, чтобы поддерживать безопасность.

Поток Managed Identity

Поток Managed Identity лучше всего работает, когда вы запускаете скрипты PowerShell и Graph API внутри сервисов Azure, таких как Azure Virtual Machines, Azure Functions или Azure Automation. Azure автоматически назначает идентичность вашему ресурсу, поэтому вам не нужно управлять учетными данными вручную.

Чтобы получить токен доступа с помощью Managed Identity, выполните следующие шаги:

1. Включите Managed Identity (системное или пользовательское назначение) для вашего ресурса Azure.
2. Назначьте необходимые разрешения Microsoft Graph API этой идентичности в Azure AD с помощью Microsoft Graph PowerShell или Graph Explorer.
3. Используйте PowerShell, чтобы запросить токен из локальной службы метаданных экземпляра Azure (IMDS).

Пример фрагмента PowerShell для получения токена через Managed Identity:

$resource = "https://graph.microsoft.com"
$tokenAuthUri = "http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=$resource"
$headers = @{ Metadata = "true" }
$response = Invoke-RestMethod -Method Get -Uri $tokenAuthUri -Headers $headers
$accessToken = $response.access_token

🔐 Поток Managed Identity избавляет от необходимости хранить секреты в скриптах. Он обеспечивает безопасную и бесшовную аутентификацию в среде Azure.

Вызовы API с помощью PowerShell + Graph API

Вызовы API с помощью PowerShell + Graph API позволяют эффективно работать с сервисами Microsoft 365. Понимание того, как формировать HTTP-запросы, необходимо для успешного взаимодействия с API.

Формирование HTTP-запросов

При работе с Microsoft Graph API нужно правильно формировать HTTP-запросы. Вот ключевые компоненты HTTP-запроса:

• Получение токена доступа: используйте полученный токен в заголовке.
• Настройка заголовков: задайте необходимые заголовки, включая Content-Type: application/json и Authorization: Bearer $accessToken.
• GET/POST-запрос: явно отправьте запрос к нужной конечной точке Microsoft Graph API.

Использование Invoke-RestMethod

Командлет Invoke-RestMethod упрощает взаимодействие с Microsoft Graph API. Он позволяет отправлять HTTP-запросы и получать ответы в удобном виде. Вот краткий обзор его поведения и ограничений:

Распространённые конечные точки API

Для задач управления Microsoft 365 часто используется несколько конечных точек Microsoft Graph API. Вот некоторые из самых распространённых:

Работа с выводом API

Понимание ответов в формате JSON

При работе с Microsoft Graph API данные возвращаются в формате JSON. JSON (JavaScript Object Notation) легковесен и удобен для чтения. Понимание ответов JSON критически важно для эффективной обработки данных. Типичный ответ JSON выглядит так:

{
  "id": "1",
  "displayName": "John Doe",
  "mail": "john.doe@example.com"
}

Преобразование JSON в объекты PowerShell

Чтобы работать с данными JSON в PowerShell, их нужно преобразовать в объекты PowerShell. Такое преобразование позволяет легко манипулировать данными. Для этого используется командлет ConvertFrom-Json. Вот как это работает:

$jsonData = '{"id": "1", "displayName": "John Doe", "mail": "john.doe@example.com"}'
$powerShellObject = $jsonData | ConvertFrom-Json

Теперь в $powerShellObject содержатся свойства, к которым можно обратиться напрямую, например $powerShellObject.displayName.

Фильтрация и форматирование данных

Когда данные окажутся в объектах PowerShell, их можно отфильтровать и отформатировать под свои задачи. PowerShell предлагает различные приёмы для уточнения вывода данных. Например, при вызовах API можно использовать параметры запроса OData, чтобы фильтровать результаты непосредственно в Microsoft Graph API.

Экспорт результатов

Экспорт результатов из скриптов PowerShell необходим для эффективного управления данными. Вывод можно сохранить в различных форматах, например CSV, JSON или XML. Например, так можно экспортировать сведения о пользователях:

$users = Get-MgUser -All
$users | Select-Object DisplayName, Mail | Export-Csv -Path "Users.csv" -NoTypeInformation

Лучшие практики и устранение неполадок

Обработка ошибок и ограничений API

При работе с Microsoft Graph API ошибки часто возникают из-за параметров конкретного клиента или проблем с разрешениями. Многие пользователи запускают скрипты, скачанные из интернета, без адаптации к своей среде, и это приводит к сбоям. Кроме того, Microsoft Graph ограничивает частоту запросов, чтобы защитить свои службы. Если скрипт отправляет слишком много запросов за короткое время, API возвращает код состояния 429. Следует учитывать заголовок Retry-After и дождаться указанного времени перед повторной попыткой.

Защита учётных данных

Защита учётных данных имеет критическое значение при автоматизации задач Microsoft 365. Используйте регистрации приложений и управляемые удостоверения, чтобы создать безопасные удостоверения для ваших приложений. По возможности не храните секреты клиента в открытом виде внутри скриптов.

Оптимизация скриптов

Эффективные скрипты экономят время и снижают потребление ресурсов. Запрашивайте только нужные свойства, применяя параметр запроса $select, используйте пакетную обработку и проектируйте циклы автоматизации с корректными обработчиками пагинации.

Освоив потоки управляемых удостоверений с PowerShell и Microsoft Graph API, вы кардинально измените подход к облачной автоматизации. Отказавшись от статических секретов и перейдя к облачно-нативным удостоверениям, вы создадите устойчивые и высокозащищённые рабочие процессы, которые защитят вашу организацию. Чтобы узнать больше об этих стратегиях и послушать практические обсуждения современного администрирования облака, обязательно посмотрите связанный выпуск: Use Managed Identity with PowerShell for Microsoft Graph. Попробуйте эти примеры в своём песочничном клиенте уже сегодня и выведите свою среду автоматизации на новый уровень!

Часто задаваемые вопросы

Что такое PowerShell?

PowerShell — это фреймворк для автоматизации задач от Microsoft, который объединяет командную оболочку и язык сценариев для упрощения управления системами и облачными операциями.

Что такое Microsoft Graph API?

Microsoft Graph API — это единая RESTful-точка доступа к данным и службам Microsoft 365, включая пользователей, группы, почту и конфигурации каталога.

Как установить модуль Microsoft Graph PowerShell?

Модуль можно установить, выполнив Install-Module Microsoft.Graph -Scope CurrentUser в среде PowerShell 7.

Что такое делегированные и application-разрешения?

Делегированные разрешения позволяют приложению действовать от имени вошедшего пользователя, а application-разрешения допускают фоновое выполнение без активного контекста пользователя.

Как обрабатывать ограничения частоты запросов API?

Всегда проверяйте в заголовках ответа значение Retry-After при получении кода состояния 429 и реализуйте в своих скриптах логику повторных запросов с экспоненциальной задержкой.

Что такое OAuth 2.0?

OAuth 2.0 — это платформа авторизации, которая позволяет приложениям безопасно получать токены доступа для вызова защищённых API без раскрытия учётных данных пользователя.

Можно ли использовать PowerShell в Linux?

Да! PowerShell полностью кроссплатформенный и работает нативно в Windows, macOS и Linux.

Как экспортировать данные из PowerShell?

Структурированные данные можно легко экспортировать с помощью командлетов вроде Export-Csv или ConvertTo-Json — в зависимости от требований к формату отчётности.