Поиск по сайту:

Как использовать Connect-MgGraph - Все параметры

Модуль Microsoft Graph в PowerShell позволяет вам взаимодействовать с различными службами Microsoft 365. Но чтобы использовать этот модуль, сначала необходимо подключиться к Microsoft Graph, используя командлет Connect-MgGraph.

Существует несколько вариантов аутентификации подключения к Microsoft Graph: от интерактивного входа до аутентификации на основе сертификатов и управляемой идентификации. Последний вариант отлично подходит для фоновых операций.

В этой статье мы рассмотрим, как использовать Connect-MgGraph, разные области и методы аутентификации.

Установите модуль Microsoft Graph

Перед тем как мы перейдем к тому, как подключиться к Microsoft Graph, нам сначала нужно убедиться, что у вас установлен модуль в PowerShell. Модуль на самом деле называется Microsoft Graph PowerShell SDK.

Рекомендуется использовать PowerShell 7 для Microsoft Graph, но вы также можете установить и использовать модуль в более старой версии PowerShell 5.1. Если вы хотите узнать, как установить или обновить свой PowerShell, убедитесь, что вы прочитали эту статью.

Вы можете проверить, установлен ли у вас модуль, с помощью следующей команды:

Get-InstalledModule Microsoft.Graph

Для установки модуля мы будем использовать командлет Install-Module. Самый простой способ — установить его только для текущего пользователя, но вы также можете установить его для всех пользователей:

Install-Module Microsoft.Graph -Scope CurrentUser

Если вы хотите узнать больше о том, как установить Microsoft Graph, например, как установить только конкретный модуль или beta-версию, тогда обязательно прочитайте эту статью.

Подключите методы MgGraph

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

  • Делегированный доступ – Команды выполняются от имени вошедшего пользователя. Вам потребуется использовать области определения, чтобы указать, какие операции может выполнять командлет.
  • Доступ только через приложение – Аутентификация основана на (видах) токена доступа, позволяя Microsoft Graph получать доступ к ресурсам без входа пользователя. Разрешения (области) определены в токене доступа.

Для делегированного доступа мы можем использовать следующие методы:

  • Интерактивная аутентификация – Вам будет предложено войти в свою учетную запись.
  • Код устройства – Используется для аутентификации на другом устройстве.
  • Собственный токен доступа - Аутентификация с вашим собственным токеном доступа.
  • Пользовательское приложение – Позволяет использовать приложение Azure AD и ограничивать вход только для определённых пользователей или групп.

Существуют также различные методы, которые вы можете использовать для доступа только к приложению:

  • На основе сертификата – Позволяет использовать самоподписанный сертификат
  • Управляемая Идентификация – Используется, например, в Azure Runbooks.
  • Секрет клиента – Использует секрет клиента из приложения Azure. Идеально подходит для фоновых задач.

Области

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

Существует два метода, чтобы узнать, какие разрешения требуются для выполнения команды cmdlet: вы можете ознакомиться с документацией или использовать cmdlet Find-MgGraphCommand. В качестве примера возьмем cmdlet Get-MgUserAuthenticationMethod.

Если мы посмотрим в документацию, то часто увидим таблицу разрешений в описании. Когда разрешения не указаны, мы можем использовать командлет Find-MgGraphCommand или командлет Find-MgGraphPermission.

Find-MgGraphCommand -Command "Get-MgUserAuthenticationMethod" | select -ExpandProperty Permissions | Select -Unique name

Or 
Find-MgGraphPermission AuthenticationMethod

Еще один вариант - использовать Graph Explorer, подробнее об этом методе можно прочитать в этой статье.

Делегированный доступ

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

Интерактивная аутентификация

Самым распространённым методом аутентификации является интерактивная аутентификация. Это метод по умолчанию, поэтому нам нужно только определить области, для которых мы хотим предоставить разрешения. Например, чтобы получить всех пользователей и группы, вам необходимо использовать области User.Read.All и Group.Read.All:

Connect to MgGraph with user and group read permissions
and suppress the welcome message

Connect-MgGraph -Scopes "User.Read.All", "Group.Read.All" -NoWelcome

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

Код устройства

Когда вы не можете пройти аутентификацию на устройстве, на котором выполняется команда Connect-MgGraph, вы также можете использовать поток кода устройства. Это позволяет вам завершить процесс аутентификации на другом компьютере, открыв веб-страницу https://microsoft.com/devicelogin.

Connect-MgGraph -Scopes "User.Read.All", "Group.ReadWrite.All" -UseDeviceAuthentication

Токен доступа

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

Затем вы можете скопировать токен доступа из вкладки Токен доступа. Скопируйте токен и вставьте его в командлет Connect-MgGraph:

Connect-MgGraph -Accesstoken <paste-your-token-here>

Кастомное приложение Azure

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

  1. Откройте Microsoft Entra > Регистрация приложений

  2. Создать новую регистрацию

    • Название – Ограниченный доступ MgGraph Limited
    • Типы аккаунтов – Аккаунты только в этом организационном каталоге (одиночный арендатор)
    • URI перенаправления – Публичный клиент/нативный > http://localhost
    • Регистрация
  3. Откройте Корпоративные приложения > Выберите ваше новое приложение
  4. Нажмите на Свойства – Включить требование о назначении
  5. Откройте Пользователи и группы – добавьте пользователей или группы, которым разрешено использовать это приложение.

Используйте следующий метод подключения в вашем скрипте для подключения к Microsoft Graph:

Connect-MgGraph -ClientId <your-app-id> -TenantId <tenant-id>

Доступ только через приложение

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

На основе сертификата

Лучший способ аутентифицировать локально запланированный скрипт PowerShell - использовать метод аутентификации на основе сертификатов. Этот метод использует самоподписанный сертификат, который мы можем создать в PowerShell.

Шаг 1 — Создание самоподписанного сертификата

Первый шаг - создать самоподписанный сертификат. Вы можете создать сертификат на своем локальном компьютере, но убедитесь, что вы установили его в доверенное хранилище машины, на которой вы хотите запланировать выполнение скрипта.

Чтобы создать сертификат, мы будем использовать командлет New-SelfSigendCertificate. Укажите осмысленное имя и тему, чтобы вы знали, для чего нужен сертификат. По умолчанию срок действия сертификата составляет один год:

$cert = New-SelfSignedCertificate -FriendlyName "PSMsGraph" -Subject "Test Cert PowerShell MsGraph" -CertStoreLocation "Cert:\CurrentUser\My"

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

Export-Certificate -Cert $cert -FilePath "c:\temp\PSMsGraph.cer"

Шаг 2 — Создание приложения Azure AD

С созданным сертификатом мы теперь можем создать приложение Azure AD. Здесь мы загрузим сертификат и установим необходимые разрешения. Разрешение требует согласия администратора, поэтому убедитесь, что у вас есть правильные разрешения.

  1. Откройте Центр администрирования Microsoft Entra
  2. Раскройте Приложения и нажмите на Регистрация приложений
  3. Выберите Новую регистрацию

  1. Введите имя для приложения
  2. Выберите Только учетные записи в этом организационном каталоге
  3. Нажмите на Зарегистрироваться (нам не нужно вводить URI перенаправления)

Шаг 3 - Настройка разрешений

Создав приложение, нам теперь нужно настроить разрешения Microsoft Graph, которые нам необходимы для нашего скрипта. Разрешения аналогичны областям (scopes), поэтому если вы хотите узнать, какое разрешение установить, вы можете использовать тот же метод для поиска областей.

  1. Откройте разрешения API
  2. Нажмите на Добавить разрешения
  3. Выберите Microsoft Graph

  1. Выберите разрешение приложения
  2. Выберите разрешение, которое вы хотите добавить
  3. Нажмите на Грант администратора на согласие для <tenantname>

Шаг 4 - Загрузить сертификат

С установленными разрешениями мы теперь можем загрузить сертификат. Сертификат используется для аутентификации соединения.

  1. Нажмите на Сертификаты и секреты
  2. Выберите Сертификаты и нажмите на Загрузить сертификат
  3. Загрузите .cer файл, который мы экспортировали ранее

Шаг 5 — Подключите MgGraph с помощью сертификата

Теперь мы создали приложение и сертификат, которые необходимы для подключения к MgGraph с помощью сертификата. Существует 3 способа подключения к MgGraph с использованием сертификата, но для всех методов нам необходимы ClientId Azure App и Tenant ID.

Вы можете найти оба в приложении Обзор в центре администрирования Microsoft Entra > Регистрация приложений > <ваше приложение>

Первый метод подключения к MgGraph с помощью сертификата - это использование отпечатка сертификата.

Connect-MgGraph -ClientId "d24d7358-12ab-2356-aabbn-asd131asb" -TenantId "11e55098-12ab-2356-aabbn-asd34fgdsav2" -CertificateThumbprint "2BF6BDD0286EF8A0AS2341NLSDH1L234C"

Вы можете найти отпечаток сертификата в Microsoft Entra > Регистрация приложений в разделе Сертификаты приложения. Или вы можете использовать следующую команду PowerShell, чтобы просмотреть все ваши самоподписанные сертификаты:

Get-ChildItem Cert:\CurrentUser\My

Result
Thumbprint                                Subject
----------                                -------
2BF6BDD0286EF8A0AS2341NLSDH1L234C         CN=Test Cert PowerShell MsGraph

Также возможно использовать имя субъекта сертификата для подключения, но вам нужно будет добавить cn= к имени субъекта, как они перечислены в команде выше.

Connect-MgGraph -ClientId "d24d7358-12ab-2356-aabbn-asd131asb" -TenantId "11e55098-12ab-2356-aabbn-asd34fgdsav2" -CertificateSubjectName "CN=Test Cert PowerShell MsGraph"

Последний вариант - использовать сертификат в команде connect-mggraph:

$Cert = Get-ChildItem Cert:\LocalMachine\My\$CertThumbprint
Connect-MgGraph -ClientId "d24d7358-12ab-2356-aabbn-asd131asb" -TenantId "11e55098-12ab-2356-aabbn-asd34fgdsav2" -Certificate $Cert

Управляемая идентичность

При использовании соединения Microsoft Graph внутри Runbook Azure вы можете использовать метод управляемой идентификации для аутентификации. Это позволит получить токен доступа от ресурса Azure, что является самым удобным способом использования MgGraph внутри Runbook.

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

Чтобы подключиться к MgGraph с управляемой идентичностью, вы можете просто указать параметр -Identity:

Connect-MgGraph -Identity

Секрет клиента

Последний вариант подключения к Microsoft Graph с доступом только для приложений - использовать учетные данные клиентского секрета. Для этого метода вам также потребуется создать приложение Azure AD, просто следуйте шагам 2 и 3 из метода аутентификации на основе сертификатов.

  1. В Azure AD App откройте Сертификаты и секреты
  2. Нажмите на Секреты клиента > Новый секрет клиента
  3. Введите описание и нажмите Добавить

  1. Скопируйте значение (вы можете видеть значение только сразу после его создания)
  2. Используйте Get-Credential, чтобы создать объект учетных данных и подключиться к MgGraph:
Credential = Application Client ID
$ClientSecretCredential = Get-Credential -Credential "d24d7358-12ab-2356-aabbn-asd131asb"

Connect to MgGraph using the client secret
Connect-MgGraph -TenantId "11e55098-12ab-2356-aabbn-asd34fgdsav2" -ClientSecretCredential $ClientSecretCredential

Важно отметить, что идентификатор клиента, который используется для создания объекта удостоверения, является идентификатором клиента приложения (а не идентификатором секретов!)

Заключение

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

Убедитесь, что вы определили правильные области/разрешения для подключения, иначе вы не сможете использовать необходимые вам cmdlet.

Надеюсь, вы нашли эту статью полезной. Если у вас есть вопросы, просто оставьте комментарий ниже.