快速入门：在 Python 中使用 Microsoft Entra SDK for AgentID 登录用户并调用下游 API

在本快速入门中，你将使用示例 Web 应用了解如何使用自己的标识登录用户或代理并调用下游 API。示例应用程序使用 Microsoft Entra SDK for AgentID 来验证用于委托访问的用户令牌，并使用应用程序身份进行与下游 API（如 Microsoft Graph）的服务到服务通信。

先决条件

安装 UV 包管理器。 UV 是一个快速的 Python 包安装程序和使用 Rust 编写的解析程序。
安装 Docker Desktop。
拥有有效订阅的 Azure 帐户。如果还没有帐户，请免费创建帐户。
Azure 帐户必须拥有管理应用程序的权限。以下任何Microsoft Entra 角色都包含所需的权限：
- 应用程序管理员
- 应用程序开发人员
工作人员租户。可以使用默认目录或设置新租户。

创建和配置 Microsoft Entra 应用程序

若要完成本快速入门的其余部分，需要首先在 Microsoft Entra ID 中注册应用程序。

创建应用程序注册

按照以下步骤创建应用注册：

至少以应用程序开发人员的身份登录到 Microsoft Entra 管理中心。
如果有权访问多个租户，请使用顶部菜单中的 “设置” 图标切换到要在其中注册应用程序的租户。
浏览到 Entra ID>应用注册 并选择“ 新建注册”。
为应用输入有意义的名称，例如 identity-client-app。应用用户会看到此名称，你可以随时对其进行更改。可以有多个具有相同名称的应用注册。

在 “支持的帐户类型”下，指定谁可以使用该应用程序。 仅针对大多数应用程序选择此组织目录中的帐户。有关每个选项的详细信息，请参阅该表。

支持的帐户类型	Description
仅此组织目录中的帐户	对于单租户应用，仅供租户中的用户（或来宾）使用。
任何组织目录中的帐户	对于多租户应用，你希望任何 Microsoft Entra 租户中的用户能够使用应用程序。非常适合用于要提供给多个组织的服务型软件（SaaS）应用程序。
任何组织目录中的帐户和个人Microsoft帐户	对于支持组织和个人 Microsoft 账户（例如 Skype、Xbox、Live、Hotmail）的多租户应用。
Microsoft 个人帐户	仅适用于个人Microsoft帐户使用的应用（例如 Skype、Xbox、Live、Hotmail）。

选择“注册”以完成应用注册。
将显示应用程序的 “概述 ”页。在应用程序概述页中记录以下值供以后使用：
- 应用程序（客户端）ID
- 目录（租户）ID

添加重定向 URI

Python 示例应用通过基于浏览器的登录流使用交互式身份验证。配置重定向 URI 以处理身份验证响应：

在应用注册中，在 “管理”下，选择“ 身份验证”。
选择添加平台。
选择 “移动”和“桌面应用程序”。
在 “自定义重定向 URI”下，输入 http://localhost。
选择配置。

添加客户端凭据

Microsoft Entra SDK for AgentID 使用客户端凭据对下游 API 进行身份验证和获取令牌。对于本地开发和测试，请使用自签名证书进行身份验证。

生成自签名证书

以管理员身份运行 PowerShell，并使用以下命令生成自签名证书：

# Generate a self-signed certificate
$cert = New-SelfSignedCertificate `
    -Subject "CN=AgentID-Client-Certificate" `
    -CertStoreLocation "Cert:\CurrentUser\My" `
    -KeyExportPolicy Exportable `
    -KeySpec Signature `
    -KeyLength 2048 `
    -KeyAlgorithm RSA `
    -HashAlgorithm SHA256 `
    -NotAfter (Get-Date).AddDays(7)

# Export public key (CER) for upload to Azure
$cerPath = "agentid-client-certificate.cer"
Export-Certificate -Cert $cert -FilePath $cerPath

# Export private key (PFX) for the Agent ID SDK container
$pfxPath = "agentid-client-certificate.pfx"
$certPassword = ConvertTo-SecureString -String "YourSecurePassword123!" -Force -AsPlainText
Export-PfxCertificate -Cert $cert -FilePath $pfxPath -Password $certPassword


Write-Host "Certificate generated successfully!"
Write-Host "CER file (public key): $cerPath"
Write-Host "PFX file (private key): $pfxPath"
Write-Host "Certificate Thumbprint: $($cert.Thumbprint)"
Write-Host "Certificate Password: YourSecurePassword123!"

记录 PowerShell 输出中显示的证书指纹。需要它来验证Microsoft Entra 管理中心中的证书是否与本地安装的证书匹配。

将证书上传到 Microsoft Entra ID

按照以下步骤，将当前目录中创建的.cer文件上传到 Microsoft Entra 管理中心：

在 Microsoft Entra 管理中心打开应用注册
在“管理”下，选择“证书和机密”。
在“ 证书 ”选项卡中，选择“ 上传证书”。
选择您生成的.cer文件（例如agentid-client-cert.cer）。
提供说明（例如，“AgentID 本地开发证书”）。
选择 并添加。
记录显示的证书指纹（它应与证书生成中的指纹匹配）。

注释

对于生产环境，请使用受信任的证书颁发机构（CA）颁发的证书，并将其存储在具有托管标识访问权限的 Azure Key Vault 中。仅对本地开发和测试使用自签名证书。

配置 API 权限

按照以下步骤配置Microsoft Graph 的委派权限。使用这些权限，客户端应用程序可以代表已登录用户执行作，例如读取其电子邮件。

在应用注册的管理下，选择API 权限>，然后单击添加权限>，选择Microsoft Graph。
选择“委托权限”。 Microsoft Graph 公开了许多权限，最常用的权限显示在列表顶部。
在 “选择权限”下，选择并添加 User.Read。

配置应用程序权限

若要测试仅应用程序流，其中 AgentID SDK 使用自己的标识（没有用户上下文）调用 API，请配置应用程序权限：

在 API 权限页中，选择“MicrosoftGraph>”。
选择“应用程序权限”。
在 “选择权限”下，搜索并选择 “User.Read.All”。
选择“添加权限”。
为 [你的租户] 选择“授予管理员同意”，然后确认。

注释

应用程序权限需要管理员同意。未进行此步骤时，在测试部分中应用程序专用终结点将失败。

公开 API（用于令牌验证测试）

若要使用专门为应用程序（使用/validate范围）颁发的令牌调用 AgentID SDK 的api://<application-client-id>/access_as_user终结点，必须完成此步骤。如果只是使用委派权限测试Microsoft Graph 方案，则可以跳过本部分。按照以下步骤公开包含所需范围的 API：

在“管理”下，选择“公开 API” 。
在页面顶部，选择“添加”按钮，该按钮位于“应用程序 ID URI”旁边。此值默认为 api://<application-client-id>. 应用 ID URI 充当你将在 API 代码中引用的范围的前缀，它必须是全局唯一的。选择“保存”。
选择 “添加范围 ”，如下所示：
接下来，在 “添加范围 ”窗格中指定作用域的属性，如下所示：
- 范围名称：access_as_user
- 谁可以同意：管理员和用户
- 管理员同意显示名称：以用户身份访问 AgentID SDK
- 管理员同意说明：允许以已登录用户身份访问 AgentID SDK API
- 状态：已启用
选择添加作用域。

启动适用于 AgentID 的 Microsoft Entra SDK

Microsoft Entra SDK for AgentID 是一种容器化 Web 服务，用于处理令牌获取、验证和安全下游 API 调用。它作为配套容器与应用程序一起运行，使你可以将标识逻辑卸载到专用服务。

创建配置文件

AgentID SDK 需要一个配置文件才能连接到 Microsoft Entra 应用程序。为配置创建新目录并创建 appsettings.json 文件：

# Create a directory for the AgentID SDK configuration
New-Item -ItemType Directory -Path "agentid-config" -Force
cd agentid-config

# Create the appsettings.json file
New-Item -ItemType File -Path "appsettings.json"

在首选文本编辑器中打开 appsettings.json 并添加以下配置，将占位符值替换为Microsoft Entra 应用程序详细信息：

{
    "AzureAd": {
        "Instance": "https://login.microsoftonline.com/",
        "TenantId": "YOUR_TENANT_ID_HERE",
        "ClientId": "YOUR_CLIENT_ID_HERE",
        "ClientCredentials": [
            {
                "SourceType": "Path",
                "CertificateStorePath": "agentid-client-certificate.pfx",
                "CertificateDistinguishedName": "YourSecurePassword123!"
            }
        ]
    },
    "DownstreamApis": {
        "me": {
            "BaseUrl": "https://graph.microsoft.com/v1.0/",
            "RelativePath": "me",
            "Scopes": [ "User.Read" ]
        }
    },
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft.AspNetCore": "Warning"
        }
    },
    "AllowedHosts": "*"
}

拉取并运行 AgentID SDK 容器

AgentID SDK 可作为 Microsoft 容器注册表（MCR）的预构建的容器映像获取。在拉取容器映像之前，请验证 Docker Desktop 是否正在运行。如果 Docker 未运行，请打开 Docker Desktop 并等待状态显示“Docker Desktop 正在运行”。

导航到配置目录并运行以下命令：

# Navigate to your config directory
cd agentid-config

# Pull the AgentID SDK container image from MCR
docker pull mcr.microsoft.com/entra-sdk/auth-sidecar:1.0.0-rc.2-azurelinux3.0-distroless

# Run the container
docker run -d `
    --name agentid-sdk `
    -p 5178:8080 `
    -e ASPNETCORE_ENVIRONMENT=Development `
    mcr.microsoft.com/entra-sdk/auth-sidecar:1.0.0-rc.2-azurelinux3.0-distroless

# Copy configuration files into the container
docker cp appsettings.json agentid-sdk:/app/appsettings.json
docker cp agentid-client-certificate.pfx agentid-sdk:/app/agentid-client-certificate.pfx

# Restart the container to apply the configuration
docker restart agentid-sdk

注释

对于 Windows 主机，请使用 Windows 容器变体： mcr.microsoft.com/entra-sdk/auth-sidecar:1.0.0-rc.2-windows

可以使用以下 Docker 命令管理代理 ID SDK 容器：

查看容器日志： docker logs agentid-sdk
查看实时日志： docker logs -f agentid-sdk
停止容器： docker stop agentid-sdk
再次启动容器： docker start agentid-sdk
删除容器： docker rm agentid-sdk

验证容器是否正在运行

可以通过调用运行状况检查终结点来验证 AgentID SDK 容器是否正常运行：/healthz：

Invoke-RestMethod -Uri "http://localhost:5178/healthz" -ErrorAction SilentlyContinue

此终结点返回 Healthy，该终结点确认 AgentID SDK 正在运行，并且已准备好处理请求。测试时不要终止 AgentID SDK。容器必须继续在后台运行，才能运行来自 Python 应用的所有身份验证和 API 调用。

运行 Python 示例应用

Python 示例应用演示如何使用 Microsoft Entra SDK for AgentID 进行身份验证和 API 调用。 AgentID SDK 作为本地 Web 服务运行，并充当身份验证代理。它代表你验证用户令牌并调用下游 API，例如 Microsoft Graph。

此示例包括显示两种身份验证模式的 Python 脚本：

委托的权限：AgentID SDK 验证用户令牌，并代表已登录用户调用 API。
应用程序权限：AgentID SDK 使用自己的标识来调用没有用户上下文的 API。

此方法将令牌管理和 API 访问集中到应用程序可以通过简单的 HTTP 请求使用的单个服务中。

克隆或下载 Python 示例应用

下载 Python 示例应用并将其解压缩到本地目录。或者，通过打开命令提示符、导航到所需项目位置并运行以下命令来克隆存储库：

git clone https://github.com/AzureAD/microsoft-identity-web.git
cd microsoft-identity-web/tests/DevApps/SidecarAdapter/python

示例应用包含以下 Python 脚本：

get_token.py – 通过Microsoft身份验证库（MSAL）获取用户访问令牌。
main.py – 调用 AgentID SDK 终结点并显示 JSON 响应的命令行接口。
MicrosoftIdentityWebSidecarClient.py– AgentID SDK 的 HTTP 客户端包装器，用于/Validate、/AuthorizationHeader和/DownstreamApi终结点。

Python 脚本在调用 AgentID SDK 终结点时使用参数 me 。此参数引用 AgentID SDK appsettings.json中名为“me”的下游 API 配置：

"DownstreamApis": {
    "me": {
        "BaseUrl": "https://graph.microsoft.com/v1.0/",
        "RelativePath": "me",
        "Scopes": [ "User.Read" ]
    }
}

使用 me 参数调用 AgentID SDK 终结点时，SDK 使用配置中的基 URL 和相对路径来构造完整的 API 终结点，请求指定的作用域，并调用 Microsoft Graph /me 终结点来检索已登录用户的配置文件。您可以使用不同的名称和终结点来添加额外的appsettings.json下游 API 配置，以调用其他 API。

测试 Microsoft Entra SDK for AgentID 与 Python 应用之间的交互

本快速入门演示了三层身份验证模式：

用户身份验证：使用 MSAL for Python 获取用户访问令牌。此令牌证明用户的标识。
令牌验证：AgentID SDK 会验证用户令牌，以确保其验证并颁发给应用程序。
令牌交换：AgentID SDK 使用 On-Behalf-Of（OBO）流，将用户令牌交换为一个范围限定为 Microsoft Graph 的新令牌，然后调用 API。

对于仅限应用程序的方案，AgentID SDK 会绕过用户身份验证，并使用自己的客户端凭据直接获取令牌。 SDK 集中了此身份验证逻辑，因此 Python 应用程序只需进行简单的 HTTP 请求，而无需管理复杂的 OAuth 流。

获取用户访问令牌

在测试 AgentID SDK 终结点之前，请获取有效的访问令牌。该 get_token.py 脚本使用适用于 Python 的 MSAL 通过基于浏览器的登录流以交互方式获取令牌。

令牌范围和受众：

请求的范围确定令牌的受众（aud 声明），该声明必须与要调用的终结点匹配：

对于令牌验证测试，使用 api://<client-id>/access_as_user 来测试 /validate 终结点
为了 Microsoft Graph 测试，请获取一个具有User.Read范围的新令牌，用于测试/authorizationheader/downstreamapi终结点

使用以下命令设置配置变量并获取令牌：

# Set your configuration
$clientId = "YOUR_CLIENT_ID_HERE"
$tenantId = "YOUR_TENANT_ID_HERE"
$authority = "https://login.microsoftonline.com/$tenantId"

# For testing AgentID SDK APIs (if you exposed the API)
$scope = "api://$clientId/access_as_user"

# Or for testing Microsoft Graph directly
# $scope = "User.Read"

# Acquire token
$token = uv run --with msal get_token.py --client-id $clientId --authority $authority --scope $scope

运行获取令牌命令时，脚本将启动基于浏览器的交互式登录流。此浏览器身份验证仅在首次运行时发生。身份验证成功后，令牌会缓存在本地以供后续使用。然后，访问令牌将打印到控制台，并存储在 PowerShell 变量中 $token ，以便在后续命令中使用。

使用委派权限测试 Microsoft Entra SDK 的 AgentID 终结点

获取有效的用户令牌后，可以测试 AgentID SDK 核心终结点。这些操作使用委托权限，因此 SDK 以已登录用户的身份执行操作。

首先，设置 SDK 的基本 URL：

$side_car_url = "http://localhost:5178"

1.验证用户令牌

用于 api://<client-id>/access_as_user 范围的应用程序必须使用专门为其颁发的令牌来访问终结点 /validate。在测试令牌验证之前，请确保完成“公开 API”部分中的步骤。使用以下命令调用 /validate 终结点。

uv run --with requests main.py --base-url $side_car_url --authorization-header "Bearer $token" validate

预期响应：

终结点 /validate 检查令牌是否有效并提取索赔信息：

{
  "protocol": "Bearer",
  "token": "eyJ0eXAiOiJKV1QiLCJub25jZSI6...",
  "claims": {
    "aud": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "iss": "https://login.microsoftonline.com/...",
    "name": "Your Name",
    "upn": "your.email@domain.com"
  }
}

此响应确认：

令牌格式正确（持有者令牌）
令牌由预期颁发机构颁发
受众（aud）与您的应用匹配
用户标识声明存在且有效

2. 获取 Microsoft Graph 的授权标头

终结点 /authorizationheader 检索格式正确的授权标头以调用下游 API：

uv run --with requests main.py --base-url $side_car_url --authorization-header "Bearer $token" get-auth-header me

此终结点：

验证传入的用户令牌
代表用户获取 Microsoft Graph 的新令牌
返回格式化的授权标头

3. 通过 Microsoft Entra SDK for AgentID 调用 Microsoft Graph

/downstreamapi终结点直接调用 Microsoft Graph 并返回响应：

uv run --with requests main.py --base-url $side_car_url --authorization-header "Bearer $token" invoke-downstream me

预期响应：

{
  "statusCode": 200,
  "headers": {...},
  "content": {
    "displayName": "Your Name",
    "mail": "your.email@domain.com",
    "userPrincipalName": "your.email@domain.com"
  }
}

该 me 参数对应于你在其中 appsettings.json定义的下游 API 配置。 The AgentID SDK:

验证用户令牌
使用委托（OBO）流获取 Microsoft Graph 的新令牌
调用 Microsoft Graph 上的 /me 终结点
返回用户配置文件数据

4.重写默认范围并提供请求正文

可以通过重写appsettings.json中配置的默认范围（scopes），或为写入操作提供请求正文来自定义 API 调用。

uv run --with requests main.py --base-url $side_car_url --authorization-header "Bearer $token" --scope <scopes> invoke-downstream <api-name> --body-file <path-to-file>

此方法在以下情况下非常有用：

测试不同的权限级别。例如，可以指定不同的范围，例如 --scope User.Read Mail.Read 以请求其他权限
下游 API 需要使用未在默认情况下配置的范围
需要动态请求其他权限
调用需要请求正文（例如创建或更新资源）的 API 时，可以添加一个用于 POST/PUT 操作的可选--body-file 参数。

测试仅限应用程序的终结点

适用于 AgentID 的 Microsoft Entra SDK 还支持仅限应用程序的流。在这些流中，AgentID SDK 使用其自身的应用身份，而不是作为用户代理执行作业。这些终结点不需要用户授权标头。

注释

仅应用程序流要求在 Microsoft Entra ID 中的应用注册具有 应用程序权限 （例如 User.Read.All），而不仅仅是委托权限。管理员必须先授予对这些权限的同意，然后才能测试这些终结点。

在没有用户上下文的情况下获取授权标头

使用此终结点检索使用 AgentID SDK 自己的标识调用 Microsoft Graph 的授权标头：

uv run --with requests main.py --base-url $side_car_url get-auth-header-unauth me