使用 Microsoft Graph 和仅限应用的身份验证生成 Python 应用

项目
Developer (初级)
19 分钟可完成

本教程介绍如何生成一个 Python 控制台应用，该应用使用 Microsoft 图形 API通过仅限应用的身份验证访问数据。对于需要访问组织中所有用户的数据的后台服务或应用程序，仅应用身份验证是一个不错的选择。

重要

适用于 Python 的 Microsoft Graph SDK 目前处于预览状态，不应在生产环境中使用。在此期间，预计会发生中断性变更。本教程使用版本 1.0.0a2 编写。

注意

若要了解如何使用 Microsoft Graph 代表用户访问数据，请参阅此用户 (委托) 身份验证教程。

在本教程中，你将：

List users

提示

作为本教程的替代方法，可以下载或克隆 GitHub 存储库，并按照 README 中的说明注册应用程序并配置项目。

先决条件

在开始本教程之前，应在开发计算机上安装 Python 和 pip 。

你还应拥有具有全局管理员角色的 Microsoft 工作或学校帐户。如果没有 Microsoft 帐户，可以注册 Microsoft 365 开发人员计划以获取免费的 Microsoft 365 订阅。

注意

本教程使用 Python 版本 3.10.4 和 pip 版本 20.0.2 编写。本指南中的步骤可能适用于其他版本，但尚未测试。

在门户中注册该应用

剩余 18 分钟

在本练习中，你将在 Azure Active Directory 中注册一个新应用程序，以启用仅限应用的身份验证。可以使用 Azure Active Directory 管理中心或使用 Microsoft Graph PowerShell SDK 注册应用程序。

重要

适用于 Python 的 Microsoft Graph SDK 目前处于预览状态，不应在生产环境中使用。在此期间，预计会发生中断性变更。本教程使用版本 1.0.0a2 编写。

注册应用程序进行仅限应用的身份验证

在本部分中，你将注册一个支持使用客户端凭据流进行用户身份验证的应用程序。

Azure AD 管理中心
PowerShell

打开浏览器并导航到 Azure Active Directory 管理中心，并使用全局管理员帐户登录。
选择左侧导航栏中的“Azure Active Directory”，再选择“管理”下的“应用注册”。
选择“新注册”。输入应用程序的名称，例如 Python App-Only Graph Tutorial。
将 “支持的帐户类型 ”设置为 “仅此组织目录中的帐户”。
保留“重定向 URI”为空。
选择“注册”。在应用程序的 “概述 ”页上，复制 “应用程序 (客户端) ID ”和 “目录 (租户) ID ”的值并保存它们，下一步将需要这些值。
在“管理”下选择 “API 权限”。
删除“配置权限”下的默认 User.Read 权限，方法是在其行中选择省略号 (...) 并选择“删除权限”。
依次选择 “添加权限”、“ Microsoft Graph”。
选择“应用程序权限”。
选择 “User.Read.All”，然后选择“ 添加权限”。
选择“ 授予管理员同意...”，然后选择“ 是 ”，为所选权限提供管理员同意。
选择“管理”下的“证书和机密”，然后选择“新建客户端密码”。
输入说明，选择持续时间，然后选择 “添加”。
复制 “值 ”列中的机密，后续步骤中将需要它。

重要

此客户端密码不会再次显示，所以请务必现在就复制它。

若要使用 PowerShell，需要 Microsoft Graph PowerShell SDK。如果没有，请参阅安装 Microsoft Graph PowerShell SDK 了解安装说明。

创建名为 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 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)
{
  $appServicePrincipal
  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
  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 "Python App-Only Graph Tutorial" -GraphScopes "User.Read.All"

按照提示在浏览器中打开 https://microsoft.com/devicelogin ，输入提供的代码，然后完成身份验证过程。

从脚本输出复制“客户端 ID”、“租户 ID”和“客户端机密”值。在下一步中，你将需要这些值。

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 权限。这是因为仅应用身份验证使用客户端凭据流，这需要在应用注册上配置权限。有关详细信息，请参阅 .default 范围。

创建 Python 控制台应用

剩余 15 分钟

首先创建新的 Python 文件。

重要

适用于 Python 的 Microsoft Graph SDK 目前处于预览状态，不应在生产环境中使用。在此期间，预计会发生中断性变更。本教程使用版本 1.0.0a2 编写。

创建名为 main.py 的新文件，并添加以下代码。
```
print ('Hello world!')
```
保存文件并使用以下命令运行该文件。
```
python3 main.py
```
如果有效，应用应输出 Hello world!。

安装依赖项

在继续操作之前，请添加稍后将使用的一些附加依赖项。

用于 Python 的 Azure 标识客户端库，用于对用户进行身份验证并获取访问令牌。
Microsoft Graph SDK for Python (预览) 调用 Microsoft Graph。

在 CLI 中运行以下命令以安装依赖项。

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

加载应用程序设置

在本部分中，你将向项目添加应用注册的详细信息。

在名为 config.cfg的 main.py 目录中创建一个文件，并添加以下代码。

[azure]
clientId = YOUR_CLIENT_ID_HERE
clientSecret = YOUR_CLIENT_SECRET_HERE
tenantId = YOUR_TENANT_ID_HERE

根据下表更新值。

设置值

clientId 应用注册的客户端 ID

clientSecret 应用注册的客户端密码

tenantId 组织的租户 ID

提示

（可选）可以在名为 config.dev.cfg 的单独文件中设置这些值。

设置	值
`clientId`	应用注册的客户端 ID
`clientSecret`	应用注册的客户端密码
`tenantId`	组织的租户 ID

设计应用

在本部分中，你将创建一个基于控制台的简单菜单。

创建一个名为 graph.py 的新文件，并将以下代码添加到该文件。
```
# Temporary placeholder
class Graph:
    def __init__(self, config):
        self.settings = config
```
此代码是占位符。在下一部分中， Graph 你将实现类。

打开 main.py ，并使用以下代码替换其全部内容。

import asyncio
import configparser
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

        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')

在文件末尾添加以下占位符方法。你将在后面的步骤中实现它们。

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 分钟

在本部分中，将向应用程序添加仅限应用的身份验证。这是获取调用 Microsoft Graph 所需的 OAuth 访问令牌所必需的。在此步骤中，你将将适用于 Python 的 Azure 标识客户端库集成到应用程序中，并为适用于 Python 的 Microsoft Graph SDK 配置身份验证 (预览版) 。

重要

适用于 Python 的 Microsoft Graph SDK 目前处于预览状态，不应在生产环境中使用。在此期间，预计会发生中断性变更。本教程使用版本 1.0.0a2 编写。

Azure 标识库提供了许多 TokenCredential 实现 OAuth2 令牌流的类。 Microsoft Graph SDK 使用这些类对 Microsoft Graph 的调用进行身份验证。

为 Graph 客户端配置仅限应用的身份验证

在本部分中， ClientSecretCredential 你将使用类通过客户端凭据流请求访问令牌。

打开 graph.py ，并将其全部内容替换为以下代码。

from configparser import SectionProxy
from azure.identity.aio import ClientSecretCredential
from kiota_authentication_azure.azure_identity_authentication_provider import (
    AzureIdentityAuthenticationProvider
)
from msgraph import GraphRequestAdapter, GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder

class Graph:
    settings: SectionProxy
    client_credential: ClientSecretCredential
    adapter: GraphRequestAdapter
    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)
        auth_provider = AzureIdentityAuthenticationProvider(self.client_credential) # type: ignore
        self.adapter = GraphRequestAdapter(auth_provider)
        self.app_client = GraphServiceClient(self.adapter)

此代码声明两个 ClientSecretCredential 私有属性：对象和 GraphServiceClient 对象。函数 __init__ 创建的新实例 ClientSecretCredential，然后使用该实例创建的新 GraphServiceClient实例。每次通过 app_client对 Microsoft Graph 进行 API 调用时，都会使用提供的凭据来获取访问令牌。

将以下函数添加到 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

将 main.py 中的空display_access_token函数替换为以下内容。

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...
```
提示

仅出于验证和调试目的，可以使用 Microsoft 的联机令牌分析程序在中https://jwt.ms解码仅限应用的访问令牌。如果在调用 Microsoft Graph 时遇到令牌错误，这很有用。例如，验证令牌中的声明是否 role 包含预期的 Microsoft Graph 权限范围。

列出用户

剩余 7 分钟

在本部分中，你将添加使用仅限应用的身份验证列出 Azure Active Directory 中的所有用户的功能。

重要

适用于 Python 的 Microsoft Graph SDK 目前处于预览状态，不应在生产环境中使用。在此期间，预计会发生中断性变更。本教程使用版本 1.0.0a2 编写。

将以下函数添加到 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

将 main.py 中的空list_users函数替换为以下内容。

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

    # Output each users's details
    if users_page is not None and users_page.value is not None:
        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 资源管理器中的代码片段，也可以是你创建的代码片段。此部分是可选的。

重要

适用于 Python 的 Microsoft Graph SDK 目前处于预览状态，不应在生产环境中使用。在此期间，预计会发生中断性变更。本教程使用版本 1.0.0a2 编写。

更新应用

将以下函数添加到 graph.py。

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

将 main.py 中的空list_inbox函数替换为以下内容。

async def make_graph_call(graph: Graph):
    await graph.make_graph_call()

选择 API

在 Microsoft Graph 中查找想要尝试的 API。例如，创建事件 API。可以使用 API 文档中的示例之一，也可以创建自己的 API 请求。

配置权限

查看所选 API 的参考文档 的“权限” 部分，了解支持哪些身份验证方法。例如，某些 API 不支持仅限应用或个人 Microsoft 帐户。

若要调用具有用户身份验证 (API（如果 API 支持用户 (委托) 身份验证) ），请参阅用户 (委派) 身份验证教程。
若要调用具有仅应用身份验证 (API（如果 API 支持) ），请在 Azure AD 管理中心中添加所需的权限范围。

添加代码

将代码复制到 make_graph_callgraph.py 中的函数中。

使用 Microsoft Graph 和仅限应用的身份验证生成 Python 应用

先决条件

在门户中注册该应用

注册应用程序进行仅限应用的身份验证

创建 Python 控制台应用

安装依赖项

加载应用程序设置

设计应用

添加仅限应用的身份验证

为 Graph 客户端配置仅限应用的身份验证

列出用户

代码说明

可选：添加自己的代码

更新应用

选择 API

配置权限

添加代码

恭喜！

Python 示例