Создание скриптов PowerShell с помощью Microsoft Graph и проверки подлинности только для приложений
В этом руководстве описано, как создать скрипт PowerShell, который использует API Microsoft Graph для доступа к данным с помощью проверки подлинности только для приложений. Проверка подлинности только для приложений — это хороший выбор для фоновых служб или приложений, которым требуется доступ к данным для всех пользователей в организации.
Примечание.
Сведения о том, как использовать Microsoft Graph для доступа к данным от имени пользователя, см. в этом руководстве по проверке подлинности пользователя (делегированная).
В этом руководстве описан порядок выполнения перечисленных ниже задач.
Совет
Кроме того, вы можете скачать или клонировать репозиторий GitHub и следовать инструкциям в файле README, чтобы зарегистрировать приложение и настроить проект.
Предварительные условия
Перед началом работы с этим руководством на компьютере разработки должен быть установлен PowerShell . PowerShell 5.1 является минимальным требованием, но рекомендуется использовать PowerShell 7.
У вас также должна быть рабочая или учебная учетная запись Майкрософт с ролью глобального администратора. Если у вас нет клиента Microsoft 365, вы можете претендовать на него в рамках Программы разработчиков Microsoft 365. Дополнительные сведения см. в разделе Вопросы и ответы. Кроме того, вы можете зарегистрироваться для получения бесплатной пробной версии на 1 месяц или приобрести план Microsoft 365.
Примечание.
Это руководство было написано с помощью PowerShell 7.2.2 и пакета SDK Для Microsoft Graph PowerShell версии 1.9.5. Действия, описанные в этом руководстве, могут работать с другими версиями, но не были протестированы.
Регистрация приложения на портале
В этом упражнении вы зарегистрируете новое приложение в Microsoft Entra, чтобы включить проверку подлинности только для приложений.
Создание самозаверяющего сертификата
Пакету SDK Для Microsoft Graph PowerShell требуется сертификат для проверки подлинности только для приложений. Для разработки достаточно самозаверяющего сертификата. Вам потребуется сертификат с закрытым ключом, установленным на локальном компьютере, и открытым ключом, экспортируемым в . CER, . PEM или . CRT-файл.
В Windows для создания сертификата можно использовать модуль PKI PowerShell .
$cert = New-SelfSignedCertificate -Subject "CN=PowerShell App-Only" -CertStoreLocation `
"Cert:\CurrentUser\My" -KeyExportPolicy Exportable -KeySpec Signature -KeyLength 2048 `
-KeyAlgorithm RSA -HashAlgorithm SHA256
Export-Certificate -Cert $cert -FilePath "./PowerShellAppOnly.cer"
Регистрация приложения для проверки подлинности только для приложений
В этом разделе описано, как зарегистрировать приложение, которое будет поддерживать проверку подлинности только для приложений с помощью потока учетных данных клиента.
Откройте браузер и перейдите в Центр администрирования Microsoft Entra и войдите с помощью учетной записи глобального администратора.
Выберите Идентификатор Microsoft Entra в области навигации слева, разверните узел Удостоверение, Приложения, а затем выберите Регистрация приложений.
Выберите Новая регистрация. Введите имя приложения, например
Graph App-Only Auth Tutorial
.Задайте для параметра Поддерживаемые типы учетных записейзначение Учетные записи только в этом каталоге организации.
Оставьте поле URI перенаправления пустым.
Нажмите Зарегистрировать. На странице Обзор приложения скопируйте значение идентификатора приложения (клиента) и идентификатора каталога (клиента) и сохраните их. Эти значения потребуются на следующем шаге.
Выберите Разрешения API в разделе Управление.
Удалите разрешение User.Read по умолчанию в разделе Настроенные разрешения , выбрав многоточие (...) в строке и выбрав Удалить разрешение.
Выберите Добавить разрешение, а затем — Microsoft Graph.
Выберите Разрешения приложения.
Выберите User.Read.All, а затем выберите Добавить разрешения.
Выберите Предоставить согласие администратора для..., а затем нажмите кнопку Да , чтобы предоставить согласие администратора для выбранного разрешения.
Выберите Сертификаты и секреты в разделе Управление, а затем — Сертификаты.
Выберите Отправить сертификат. Отправьте файл PowerShellAppOnly.cer или powershell.crt , созданный на предыдущем шаге, а затем нажмите кнопку Добавить.
Примечание.
Обратите внимание, что в отличие от действий при регистрации для проверки подлинности пользователей в этом разделе вы настроили разрешения Microsoft Graph для регистрации приложения. Это связано с тем, что проверка подлинности только для приложений использует поток учетных данных клиента, который требует настройки разрешений на регистрацию приложения. Дополнительные сведения см . в разделе Область по умолчанию .
Добавление проверки подлинности только для приложений
В этом разделе вы будете использовать проверку подлинности только для приложений с пакетом SDK Для Microsoft Graph PowerShell.
Подключение с помощью проверки подлинности только для приложений
Отключите все существующие подключения к Microsoft Graph с помощью следующей команды.
Disconnect-MgGraph
Откройте PowerShell и используйте следующую команду, чтобы задать
$clientID
переменную сеанса, заменив <your-client-id> идентификатором клиента для регистрации приложения.$clientId = <your-client-id>
Задайте переменную сеанса
$tenantId
, заменив <идентификатор вашего клиента> идентификатором клиента вашей организации.$tenantId = <your-tenant-id>
Задайте для переменной
$certificate
сеанса тему сертификата, созданного на предыдущем шаге.$certificate = "CN=PowerShell App-Only"
Используйте команду для
Connect-MgGraph
проверки подлинности с помощью сертификата из предыдущего шага.Connect-MgGraph -ClientId $clientId -TenantId $tenantId -CertificateName $certificate
Используйте
Get-MgContext
, чтобы убедиться, что вы прошли проверку подлинности только для приложений. Убедитесь, что authType имеет значениеAppOnly
.PS > Get-MgContext ClientId : 2fb1652f-a9a0-4db9-b220-b224b8d9d38b TenantId : 601faea3-be45-4960-898f-92b379b17cd9 CertificateThumbprint : Scopes : {User.Read.All} AuthType : AppOnly AuthProviderType : ClientCredentialProvider CertificateName : CN=PowerShell App-Only Account : AppName : PowerShell Graph Tutorial ContextScope : Process Certificate : PSHostVersion : 2022.4.1 ClientTimeout : 00:05:00
Перечисление пользователей
В этом разделе вы получите список всех пользователей в Azure Active Directory, использующих проверку подлинности только для приложений.
В сеансе PowerShell, прошедшем проверку подлинности, выполните следующую команду, чтобы получить список пользователей.
Get-MgUser -Select "displayName,id,mail" -Top 25 -OrderBy "displayName"
Просмотрите выходные данные.
Id DisplayName Mail UserPrincipalName UserType -- ----------- ---- ----------------- -------- 05fb57bf-2653-4396-846d-2f210a91d9cf Adele Vance AdeleV@contoso.com a36fe267-a437-4d24-b39e-7344774d606c Alex Wilber AlexW@contoso.com 54cebbaa-2c56-47ec-b878-c8ff309746b0 Allan Deyoung AllanD@contoso.com 9cb2ad7c-8e69-46a6-a947-a02c255048de Automate Bot 9a7dcbd0-72f0-48a9-a9fa-03cd46641d49 Bianca Pisani a8989e40-be57-4c2e-bf0b-7cdc471e9cc4 Brian Johnson (TAILSPIN) BrianJ@contoso.com 9e2d4937-44ee-4af4-bd56-77a12cc3ecc4 Cameron White 8990227d-31dc-4120-a38e-f652576974f4 Christie Cline ChristieC@contoso.com ...
Описание кода
Рассмотрим команду, используемую для вывода списка пользователей.
- Он использует
-Select
для запроса определенных свойств - Он использует
-Top
для ограничения числа возвращенных пользователей - Он использует
-OrderBy
для сортировки ответа
Необязательно: добавление собственного кода
В этом разделе вы будете использовать собственные команды пакета SDK Для Microsoft Graph PowerShell. Это может быть фрагмент кода из документации Microsoft Graph или обозревателя Graph или созданный вами код. Этот раздел является необязательным.
Выбор API
Найдите API в Microsoft Graph, который вы хотите попробовать. Например, API групп списка . Вы можете использовать один из примеров, приведенных в документации по API, настроить запрос API в Graph Explorer и использовать созданный фрагмент кода или использовать Find-MgGraphCommand
команду для поиска соответствующей команды.
Например, конечная точка API для групп списка — GET /groups
. Его можно использовать для поиска соответствующей команды PowerShell.
PS > Find-MgGraphCommand -Uri "/groups" -Method "GET"
APIVersion: v1.0
Command Module Method URI OutputType Permissions
------- ------ ------ --- ---------- -----------
Get-MgGroup Groups GET /groups IMicrosoftGraphGroup {Directory.Read.All, Directory.ReadWrite.All, Group.Read.All, G…
APIVersion: beta
Command Module Method URI OutputType Permissions
------- ------ ------ --- ---------- -----------
Get-MgGroup Groups GET /groups IMicrosoftGraphGroup1 {Directory.Read.All, Directory.ReadWrite.All, Group.Read.All, …
Выходные данные указывают, что Get-MgGroup
команда является соответствующей командой.
Настройка разрешений
Ознакомьтесь с разделом Разрешения справочной документации по выбранному API, чтобы узнать, какие методы проверки подлинности поддерживаются. Некоторые API не поддерживают только приложения, например.
Чтобы вызвать API с проверкой подлинности только для приложений (если API поддерживает ее), добавьте требуемую область разрешений в Центре администрирования Azure AD. Не забудьте отключиться и повторно подключиться с помощью разрешения только для приложений.
Совет
-ForceRefresh
Использование параметра с командой Connect-MgGraph
гарантирует, что будут применены только что настроенные разрешения.
Выполнение команды
Теперь, когда у вас есть необходимые разрешения, выполните выбранную команду.
Поздравляем!
Вы завершили работу с учебником powerShell Microsoft Graph только для приложений. Теперь, когда у вас есть рабочее приложение, которое вызывает Microsoft Graph, вы можете экспериментировать и добавлять новые функции.
- Узнайте, как использовать проверку подлинности пользователя (делегированная) с помощью пакета SDK Для Microsoft Graph PowerShell.
- Просмотрите обзор Microsoft Graph , чтобы просмотреть все данные, к которым можно получить доступ с помощью Microsoft Graph.
Возникла проблема с этим разделом? Если это так, отправьте нам отзыв, чтобы мы исправили этот раздел.