Создание приложений Python с помощью Microsoft Graph и проверки подлинности только для приложений

Статья
Developer (Начальный уровень)
19 мин до завершения

В этом руководстве описано, как создать консольное приложение Python, которое использует API Microsoft Graph для доступа к данным с помощью проверки подлинности только для приложений. Проверка подлинности только для приложений — это хороший выбор для фоновых служб или приложений, которым требуется доступ к данным для всех пользователей в организации.

Примечание.

Сведения о том, как использовать Microsoft Graph для доступа к данным от имени пользователя, см. в этом руководстве по проверке подлинности пользователя (делегированная).

В этом руководстве описан порядок выполнения перечисленных ниже задач.

Перечисление пользователей

Совет

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

Предварительные условия

Перед началом работы с этим руководством на компьютере разработки должны быть установлены Python и pip .

У вас также должна быть рабочая или учебная учетная запись Майкрософт с ролью глобального администратора. Если у вас нет клиента Microsoft 365, вы можете претендовать на него в рамках Программы разработчиков Microsoft 365. Дополнительные сведения см. в разделе Вопросы и ответы. Кроме того, вы можете зарегистрироваться для получения бесплатной пробной версии на 1 месяц или приобрести план Microsoft 365.

Примечание.

Это руководство было написано с python версии 3.10.4 и pip версии 20.0.2. Действия, описанные в этом руководстве, могут работать с другими версиями, но не были протестированы.

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

Осталось 18 мин

В этом упражнении вы зарегистрируете новое приложение в Azure Active Directory, чтобы включить проверку подлинности только для приложений. Вы можете зарегистрировать приложение в Центре администрирования Microsoft Entra или с помощью пакета SDK Для Microsoft Graph PowerShell.

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

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

Центр администрирования Microsoft Entra
PowerShell

Откройте браузер и перейдите в Центр администрирования Microsoft Entra и войдите с помощью учетной записи глобального администратора.
Выберите Идентификатор Microsoft Entra в области навигации слева, разверните узел Удостоверение, Приложения, а затем выберите Регистрация приложений.
Выберите Новая регистрация. Введите имя приложения, например Graph App-Only Auth Tutorial.
Задайте для параметра Поддерживаемые типы учетных записейзначение Учетные записи только в этом каталоге организации.
Оставьте поле URI перенаправления пустым.
Нажмите Зарегистрировать. На странице Обзор приложения скопируйте значение идентификатора приложения (клиента) и идентификатора каталога (клиента) и сохраните их. Эти значения потребуются на следующем шаге.
Выберите Разрешения API в разделе Управление.
Удалите разрешение User.Read по умолчанию в разделе Настроенные разрешения , выбрав многоточие (...) в строке и выбрав Удалить разрешение.
Выберите Добавить разрешение, а затем — Microsoft Graph.
Выберите Разрешения приложения.
Выберите User.Read.All, а затем выберите Добавить разрешения.
Выберите Предоставить согласие администратора для..., а затем нажмите кнопку Да , чтобы предоставить согласие администратора для выбранного разрешения.
Выберите Сертификаты и секреты в разделе Управление, а затем выберите Новый секрет клиента.
Введите описание, выберите длительность и нажмите кнопку Добавить.
Скопируйте секрет из столбца Значение . Он понадобится на следующих шагах.

Важно!

Система никогда не покажет секрет клиента повторно, поэтому убедитесь, что вы скопировали его.

Чтобы использовать PowerShell, вам потребуется пакет SDK Для Microsoft Graph PowerShell. Если у вас его нет, инструкции по установке см. в разделе Установка пакета SDK Для Microsoft Graph PowerShell .

Создайте файл с именем RegisterAppForAppOnlyAuth.ps1 и добавьте следующий код.

param(
  [Parameter(Mandatory=$true,
  HelpMessage="The friendly name of the app registration")]
  [String]
  $AppName,

  [Parameter(Mandatory=$true,
  HelpMessage="The application permission scopes to configure on the app registration")]
  [String[]]
  $GraphScopes,

  [Parameter(Mandatory=$false)]
  [Switch]
  $StayConnected = $false
)

$graphAppId = "00000003-0000-0000-c000-000000000000"

# Requires an admin
Connect-MgGraph -Scopes "Application.ReadWrite.All AppRoleAssignment.ReadWrite.All User.Read" -UseDeviceAuthentication -ErrorAction Stop

# Get context for access to tenant ID
$context = Get-MgContext -ErrorAction Stop
$authTenant = $context.TenantId

# Create app registration
$appRegistration = New-MgApplication -DisplayName $AppName -SignInAudience "AzureADMyOrg" -ErrorAction Stop
Write-Host -ForegroundColor Cyan "App registration created with app ID" $appRegistration.AppId

# Create corresponding service principal
$appServicePrincipal = New-MgServicePrincipal -AppId $appRegistration.AppId -ErrorAction SilentlyContinue `
  -ErrorVariable SPError
if ($SPError)
{
  Write-Host -ForegroundColor Red "A service principal for the app could not be created."
  Write-Host -ForegroundColor Red $SPError
  Exit
}

Write-Host -ForegroundColor Cyan "Service principal created"

# Lookup available Graph application permissions
$graphServicePrincipal = Get-MgServicePrincipal -Filter ("appId eq '" + $graphAppId + "'") -ErrorAction Stop
$graphAppPermissions = $graphServicePrincipal.AppRoles

$resourceAccess = @()

foreach($scope in $GraphScopes)
{
  $permission = $graphAppPermissions | Where-Object { $_.Value -eq $scope }
  if ($permission)
  {
    $resourceAccess += @{ Id =  $permission.Id; Type = "Role"}
  }
  else
  {
    Write-Host -ForegroundColor Red "Invalid scope:" $scope
    Exit
  }
}

# Add the permissions to required resource access
Update-MgApplication -ApplicationId $appRegistration.Id -RequiredResourceAccess `
 @{ ResourceAppId = $graphAppId; ResourceAccess = $resourceAccess } -ErrorAction Stop
Write-Host -ForegroundColor Cyan "Added application permissions to app registration"

# Add admin consent
foreach ($appRole in $resourceAccess)
{
  New-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $appServicePrincipal.Id `
   -PrincipalId $appServicePrincipal.Id -ResourceId $graphServicePrincipal.Id `
   -AppRoleId $appRole.Id -ErrorAction SilentlyContinue -ErrorVariable SPError | Out-Null
  if ($SPError)
  {
    Write-Host -ForegroundColor Red "Admin consent for one of the requested scopes could not be added."
    Write-Host -ForegroundColor Red $SPError
    Exit
  }
}
Write-Host -ForegroundColor Cyan "Added admin consent"

# Add a client secret
$clientSecret = Add-MgApplicationPassword -ApplicationId $appRegistration.Id -PasswordCredential `
 @{ DisplayName = "Added by PowerShell" } -ErrorAction Stop

Write-Host
Write-Host -ForegroundColor Green "SUCCESS"
Write-Host -ForegroundColor Cyan -NoNewline "Client ID: "
Write-Host -ForegroundColor Yellow $appRegistration.AppId
Write-Host -ForegroundColor Cyan -NoNewline "Tenant ID: "
Write-Host -ForegroundColor Yellow $authTenant
Write-Host -ForegroundColor Cyan -NoNewline "Client secret: "
Write-Host -ForegroundColor Yellow $clientSecret.SecretText
Write-Host -ForegroundColor Cyan -NoNewline "Secret expires: "
Write-Host -ForegroundColor Yellow $clientSecret.EndDateTime

if ($StayConnected -eq $false)
{
  Disconnect-MgGraph | Out-Null
  Write-Host "Disconnected from Microsoft Graph"
}
else
{
  Write-Host
  Write-Host -ForegroundColor Yellow `
   "The connection to Microsoft Graph is still active. To disconnect, use Disconnect-MgGraph"
}

Сохраните файл.
Откройте PowerShell и измените текущий каталог на расположение RegisterAppForAppOnlyAuth.ps1.

Выполните следующую команду.

.\RegisterAppForAppOnlyAuth.ps1 -AppName "Graph App-Only Auth Tutorial" -GraphScopes "User.Read.All"

Следуйте запросу, чтобы открыть https://microsoft.com/devicelogin в браузере, введите предоставленный код и завершите процесс проверки подлинности.
Скопируйте значения идентификатора клиента, идентификатора клиента и секрета клиента из выходных данных скрипта. Эти значения потребуются на следующем шаге.
```
SUCCESS
Client ID: ae2386e6-799e-4f75-b191-855d7e691c75
Tenant ID: 5927c10a-91bd-4408-9c70-c50bce922b71
Client secret: ...
Secret expires: 10/28/2024 5:01:45 PM
```

Примечание.

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

Создание консольного приложения Python

Осталось 15 мин

Начните с создания файла Python.

Создайте файл с именем main.py и добавьте следующий код.
```
print ('Hello world!')
```
Сохраните файл и выполните следующую команду, чтобы запустить файл.
```
python3 main.py
```
Если это работает, приложение должно вывести .Hello world!

Установка зависимостей

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

Клиентская библиотека удостоверений Azure для Python для проверки подлинности пользователя и получения маркеров доступа.
Пакет SDK Microsoft Graph для Python (предварительная версия) для выполнения вызовов Microsoft Graph.

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

python3 -m pip install azure-identity
python3 -m pip install msgraph-sdk

Загрузка параметров приложения

В этом разделе вы добавите в проект сведения о регистрации приложения.

Создайте файл в том же каталоге, что и main.pyс именем config.cfg , и добавьте следующий код.
```
[azure]
clientId = YOUR_CLIENT_ID_HERE
clientSecret = YOUR_CLIENT_SECRET_HERE
tenantId = YOUR_TENANT_ID_HERE
```

Обновите значения в соответствии со следующей таблицей.

Параметр	Значение
`clientId`	Идентификатор клиента для регистрации приложения
`clientSecret`	Секрет клиента для регистрации приложения
`tenantId`	Идентификатор клиента вашей организации

Совет

При необходимости эти значения можно задать в отдельном файле с именем config.dev.cfg.

Проектирование приложения

В этом разделе вы создадите простое меню на основе консоли.

Создайте файл с именем graph.py и добавьте в этот файл следующий код.
```
# Temporary placeholder
class Graph:
    def __init__(self, config):
        self.settings = config
```
Этот код является заполнителем. Класс будет реализован Graph в следующем разделе.

Откройте main.py и замените все его содержимое следующим кодом.

import asyncio
import configparser
from msgraph.generated.models.o_data_errors.o_data_error import ODataError
from graph import Graph

async def main():
    print('Python Graph App-Only Tutorial\n')

    # Load settings
    config = configparser.ConfigParser()
    config.read(['config.cfg', 'config.dev.cfg'])
    azure_settings = config['azure']

    graph: Graph = Graph(azure_settings)

    choice = -1

    while choice != 0:
        print('Please choose one of the following options:')
        print('0. Exit')
        print('1. Display access token')
        print('2. List users')
        print('3. Make a Graph call')

        try:
            choice = int(input())
        except ValueError:
            choice = -1

        try:
            if choice == 0:
                print('Goodbye...')
            elif choice == 1:
                await display_access_token(graph)
            elif choice == 2:
                await list_users(graph)
            elif choice == 3:
                await make_graph_call(graph)
            else:
                print('Invalid choice!\n')
        except ODataError as odata_error:
            print('Error:')
            if odata_error.error:
                print(odata_error.error.code, odata_error.error.message)

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

async def display_access_token(graph: Graph):
    # TODO
    return

async def list_users(graph: Graph):
    # TODO
    return

async def make_graph_call(graph: Graph):
    # TODO
    return

Добавьте следующую строку для вызова main в конце файла.
```
# Run main
asyncio.run(main())
```

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

Добавление проверки подлинности только для приложений

Осталось 10 мин

В этом разделе вы добавите в приложение проверку подлинности только для приложений. Это необходимо для получения необходимого маркера доступа OAuth для вызова Microsoft Graph. На этом шаге вы интегрируете клиентную библиотеку удостоверений Azure для Python в приложение и настроите проверку подлинности для пакета SDK Microsoft Graph для Python (предварительная версия).

Библиотека удостоверений Azure предоставляет ряд классов, которые реализуют потоки маркеров TokenCredential OAuth2. Пакет SDK для Microsoft Graph использует эти классы для проверки подлинности вызовов Microsoft Graph.

Настройка клиента Graph для проверки подлинности только для приложений

В этом разделе вы будете ClientSecretCredential использовать класс для запроса маркера доступа с помощью потока учетных данных клиента.

Откройте graph.py и замените все его содержимое следующим кодом.

from configparser import SectionProxy
from azure.identity.aio import ClientSecretCredential
from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder

class Graph:
    settings: SectionProxy
    client_credential: ClientSecretCredential
    app_client: GraphServiceClient

    def __init__(self, config: SectionProxy):
        self.settings = config
        client_id = self.settings['clientId']
        tenant_id = self.settings['tenantId']
        client_secret = self.settings['clientSecret']

        self.client_credential = ClientSecretCredential(tenant_id, client_id, client_secret)
        self.app_client = GraphServiceClient(self.client_credential) # type: ignore

Этот код объявляет два частных свойства: ClientSecretCredential объект и GraphServiceClient объект . Функция __init__ создает новый экземпляр ClientSecretCredential, а затем использует его для создания нового экземпляра GraphServiceClient. Каждый раз, когда вызов API выполняется в Microsoft Graph через app_client, он будет использовать предоставленные учетные данные для получения маркера доступа.

Добавьте следующую функцию в graph.py.

async def get_app_only_token(self):
    graph_scope = 'https://graph.microsoft.com/.default'
    access_token = await self.client_credential.get_token(graph_scope)
    return access_token.token

Замените пустую display_access_token функцию в main.py на следующую.

async def display_access_token(graph: Graph):
    token = await graph.get_app_only_token()
    print('App-only token:', token, '\n')

Выполните сборку и запуск приложения. Введите 1 при появлении запроса на выбор параметра. Приложение отображает маркер доступа.
```
Python Graph App-Only Tutorial

Please choose one of the following options:
0. Exit
1. Display access token
2. List users
3. Make a Graph call
1
App-only token: eyJ0eXAiOiJKV1QiLCJub25jZSI6IlVDTzRYOWtKYlNLVjVkRzJGenJqd2xvVUcwWS...
```
Совет

Только для проверки и отладки можно декодировать маркеры доступа только для приложений с помощью средства синтаксического анализа токенов Майкрософт в сети по адресу https://jwt.ms. Это может быть полезно, если при вызове Microsoft Graph возникают ошибки маркера. Например, убедитесь, что role утверждение в маркере содержит ожидаемые области разрешений Microsoft Graph.

Перечисление пользователей

Осталось 7 мин

В этом разделе вы добавите возможность вывода списка всех пользователей в Azure Active Directory с помощью проверки подлинности только для приложений.

Добавьте следующую функцию в graph.py.

async def get_users(self):
    query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
        # Only request specific properties
        select = ['displayName', 'id', 'mail'],
        # Get at most 25 results
        top = 25,
        # Sort by display name
        orderby= ['displayName']
    )
    request_config = UsersRequestBuilder.UsersRequestBuilderGetRequestConfiguration(
        query_parameters=query_params
    )

    users = await self.app_client.users.get(request_configuration=request_config)
    return users

Замените пустую list_users функцию в main.py на следующую.

async def list_users(graph: Graph):
    users_page = await graph.get_users()

    # Output each users's details
    if users_page and users_page.value:
        for user in users_page.value:
            print('User:', user.display_name)
            print('  ID:', user.id)
            print('  Email:', user.mail)

        # If @odata.nextLink is present
        more_available = users_page.odata_next_link is not None
        print('\nMore users available?', more_available, '\n')

Запустите приложение и выберите вариант 2, чтобы получить список пользователей.

Please choose one of the following options:
0. Exit
1. Display access token
2. List users
3. Make a Graph call
2
User: Adele Vance
  ID: 05fb57bf-2653-4396-846d-2f210a91d9cf
  Email: AdeleV@contoso.com
User: Alex Wilber
  ID: a36fe267-a437-4d24-b39e-7344774d606c
  Email: AlexW@contoso.com
User: Allan Deyoung
  ID: 54cebbaa-2c56-47ec-b878-c8ff309746b0
  Email: AllanD@contoso.com
User: Bianca Pisani
  ID: 9a7dcbd0-72f0-48a9-a9fa-03cd46641d49
  Email: None
User: Brian Johnson (TAILSPIN)
  ID: a8989e40-be57-4c2e-bf0b-7cdc471e9cc4
  Email: BrianJ@contoso.com

...

More users available? True

Описание кода

Рассмотрим код в get_users функции.

Он получает коллекцию пользователей
Он использует $select для запроса определенных свойств
Он использует $top для ограничения числа возвращенных пользователей
Он использует $orderBy для сортировки ответа

Необязательно: добавление собственного кода

Осталось 5 мин

В этом разделе вы добавите в приложение собственные возможности Microsoft Graph. Это может быть фрагмент кода из документации Microsoft Graph или обозревателя Graph или созданный вами код. Этот раздел является необязательным.

Обновите приложение

Добавьте следующую функцию в graph.py.

async def make_graph_call(self):
    # INSERT YOUR CODE HERE
    return

Замените пустую list_inbox функцию в main.py на следующую.
```
async def make_graph_call(graph: Graph):
    await graph.make_graph_call()
```

Выбор API

Найдите API в Microsoft Graph, который вы хотите попробовать. Например, API создания событий . Вы можете использовать один из примеров из документации по API или создать собственный запрос API.

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

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

Чтобы вызвать API с проверкой подлинности пользователя (если API поддерживает проверку подлинности пользователя (делегированная) проверка подлинности, см. руководство по проверке подлинности пользователя (делегированная).
Чтобы вызвать API с проверкой подлинности только для приложений (если API поддерживает ее), добавьте требуемую область разрешений в Центре администрирования Azure AD.

Добавление кода

Скопируйте код в функцию make_graph_call в graph.py.

Поделиться через

Создание приложений Python с помощью Microsoft Graph и проверки подлинности только для приложений

Предварительные условия

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

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

Создание консольного приложения Python

Установка зависимостей

Загрузка параметров приложения

Проектирование приложения

Добавление проверки подлинности только для приложений

Настройка клиента Graph для проверки подлинности только для приложений

Перечисление пользователей

Описание кода

Необязательно: добавление собственного кода

Обновите приложение

Выбор API

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

Добавление кода

Поздравляем!

Примеры Python