快速入門：在 Python 中使用適用於 AgentID 的 Microsoft Entra SDK 登入使用者並呼叫下游 API

在本快速入門中，您會使用範例 Web 應用程式來瞭解如何使用自己的身分識別登入使用者或代理程式，並呼叫下游 API。範例應用程式會使用適用於 AgentID 的 Microsoft Entra SDK 來驗證委派存取的使用者權杖，並使用應用程式身分識別與 Microsoft Graph 等下游 API 進行服務對服務通訊。

先決條件

安裝 UV 套件管理員。 UV 是一個用 Rust 編寫的快速 Python 套件安裝程式和解析器。
安裝 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）。

選取 [註冊] 以完成應用程式註冊。
應用程式的 [ 概觀 ] 頁面隨即顯示。從應用程式概觀頁面記錄下列值，以供日後使用：
- 應用程式（用戶端）識別碼
- 目錄（租戶）識別碼

新增重定向 URI

Python 範例應用程式會使用互動式驗證搭配瀏覽器型登入流程。設定重新導向 URI 以處理驗證回應：

在您的應用程式註冊中，在 [管理] 底下，選取 [驗證]。
選取 [新增平台]。
選取 行動和桌面應用程式。
在 「自訂重新導向 URI」下，輸入 http://localhost。
選取[]，然後設定[]。

新增用戶端認證

適用於 AgentID 的 Microsoft Entra SDK 使用用戶端認證來驗證並取得下游 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 金鑰保存庫中。僅將自我簽署憑證用於本機開發和測試。

設定 API 權限

請遵循下列步驟來設定委派給 Microsoft Graph 的許可權。有了這些權限，您的用戶端應用程式可以代表登入的使用者執行作業，例如讀取其電子郵件。

在您的應用程式註冊中，在 [管理] 底下，選取 [API 權限>] [新增權限>] [Microsoft Graph]。
選取委派的權限。 Microsoft Graph 會公開許多權限，其中最常顯示在清單頂端。
在 [選取許可權] 底下，選取並新增 User.Read。

設定應用程式權限

若要測試 AgentID SDK 使用自己的身分識別（沒有使用者內容）呼叫 API 的僅限應用程式流程，請設定應用程式權限：

從 [API 許可權 ] 頁面中，選取 [ 新增許可權>Microsoft Graph]。
選取應用程式權限。
在 [選取許可權] 底下，搜尋並選取 [User.Read.All]。
選取新增權限。
選取 授予 [您的租用戶] 系統管理員同意 ，然後確認。

備註

應用程式權限需要系統管理員同意。如果沒有此步驟，測試區段中的僅限應用程式的端點會失敗。

公開 API （用於權杖驗證測試）

若要使用專門為您的應用程式發出的權杖呼叫 AgentID SDK 的 /validate 端點（使用 api://<application-client-id>/access_as_user 範圍 ），您必須完成 此步驟。如果您只測試具有委派許可權的 Microsoft Graph 案例，您可以略過本節。請遵循下列步驟來公開包含必要範圍的 API：

在 [管理] 底下，選取 [ 公開 API]。
在頁面頂端，選取 [應用程式識別碼 URI] 旁邊的 [新增]。此值預設為 api://<application-client-id>。應用程式識別碼 URI 會作為您將在 API 程式碼中參考範圍的前置詞，而且必須是全域唯一的值。選取 [儲存]。
選取 [ 新增範圍 ]，如下所示：
接下來，在 [ 新增範圍 ] 窗格中指定範圍的屬性，如下所示：
- 範圍名稱：access_as_user
- 誰可以同意：管理員和使用者
- 管理員同意顯示名稱：以使用者身分存取 AgentID SDK
- 系統管理員同意說明：允許以登入使用者身分存取 AgentID SDK API
- 狀態：已啟用
選取新增範圍。

啟動適用於 AgentID 的 Microsoft Entra SDK

適用於 AgentID 的 Microsoft Entra SDK 是容器化 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 Container Registry （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

確認容器正在運行

您可以呼叫健康情況檢查端點/healthz來驗證 AgentID SDK 容器是否正確執行：

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

此端點會傳回 Healthy，確認 AgentID SDK 已正確執行，並準備好處理要求。測試時請勿終止 AgentID SDK。容器必須繼續在背景執行，來自 Python 應用程式的所有驗證和 API 呼叫才能正常運作。

執行 Python 範例應用程式

Python 範例應用程式示範如何使用適用於 AgentID 的 Microsoft Entra SDK 進行驗證和 API 呼叫。 AgentID SDK 會以本機 Web 服務的形式執行，並充當驗證 Proxy。它會驗證使用者權杖，並代表您呼叫 Microsoft Graph 等下游 API。

此範例包含顯示兩種驗證模式的 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的 /Validate、 /AuthorizationHeader和 /DownstreamApi 端點的HTTP客戶端包裝器。

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 端點來擷取已登入使用者的配置檔。您可以新增具有不同名稱和端點的其他下游 API 組態 appsettings.json ，以呼叫其他 API。

測試適用於 AgentID 的 Microsoft Entra SDK 與 Python 應用程式之間的互動

本快速入門示範三層驗證模式：

使用者驗證：您可以使用適用於 Python 的 MSAL 來取得使用者存取權杖。此令牌可證明使用者的身分。
權杖驗證：AgentID SDK 會驗證使用者權杖，以確保其真實且為您的應用程式發行。
代幣交換：AgentID SDK 使用上代表流程 (OBO) 將用戶代幣交換為範圍為 Microsoft Graph 的新代幣，然後呼叫 API。

對於僅限應用程式的案例，AgentID SDK 會略過使用者驗證，並使用自己的用戶端認證直接取得權杖。 SDK 集中了此身份驗證邏輯，因此您的 Python 應用程式只需要提出簡單的 HTTP 請求，而無需管理複雜的 OAuth 流程。

取得使用者存取權杖

在測試 AgentID SDK 端點之前，請取得有效的存取權杖。腳本會使用適用於 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

當您執行 acquire token 命令時，指令碼會起始互動式瀏覽器型登入流程。此瀏覽器驗證只會在第一次執行時發生。驗證成功後，令牌會快取在本機以供後續使用。然後，存取權杖會列印到主控台，並儲存在 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"
  }
}

此回應確認：

代幣格式正確（Bearer token）
憑證是由預期的授權單位發出
受眾（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. 透過適用於 AgentID 的 Microsoft Entra SDK 呼叫 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 的新令牌
呼叫 /me Microsoft Graph 上的端點
傳回使用者設定檔資料

4. 覆寫預設範圍並提供請求主體

您可以透過覆寫 appsettings.json 中配置的預設範圍，或提供用於寫入操作的請求主體，來自訂 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

此端點：

使用 AgentID SDK 的用戶端認證（應用程式身分識別）進行驗證。
取得 Microsoft Graph 的僅限應用存取權杖
傳回授權標頭

以不使用使用者內容的方式呼叫 Microsoft Graph

使用此端點，使用 AgentID SDK 身分識別直接呼叫 Microsoft Graph：

uv run --with requests main.py --base-url $side_car_url invoke-downstream-unauth me

此範例示範服務對服務通訊，其中：

驗證流程中不涉及任何使用者
AgentID SDK 會使用自己的用戶端識別碼和憑證進行驗證
API 呼叫會使用應用程式權限，而不是委派權限
此模式非常適合背景服務、批次處理或自動化任務

了解回應

Token 驗證回應結構

驗證回應提供有關憑證的詳細資訊：

領域	Description
`protocol`	驗證方案（對於 OAuth 2.0 權杖一律使用 "Bearer"）
`token`	原始存取權杖（範例中會截斷）
`claims`	從令牌有效負載擷取的鍵值對
`claims.aud`	目標對象（您的客戶識別碼）
`claims.iss`	權杖簽發者（Microsoft Entra ID）
`claims.name`	已登入使用者的顯示名稱
`claims.upn`	使用者主體名稱（電子郵件地址）

Microsoft Graph 呼叫回應結構

領域	Description
`statusCode`	來自 Microsoft Graph 的 HTTP 狀態碼（200 = 成功）
`headers`	來自 API 呼叫的回應標頭
`content`	Microsoft Graph 傳回的實際資料
`content.displayName`	目錄中使用者的顯示名稱
`content.mail`	使用者的電子郵件地址
`content.userPrincipalName`	使用者的 UPN

疑難排解常見問題

如果您在測試適用於 AgentID 端點的 Microsoft Entra SDK 時遇到錯誤，請檢查常見問題的下列解決方案：

問題	Solution
「連線被拒絕」錯誤	確認 AgentID SDK 容器正在執行： `docker ps -a`。如果容器狀態顯示「已結束」，請檢查記錄： `docker logs agentid-sdk`。重新啟動容器： `docker start agentid-sdk` 並測試健康情況端點： `Invoke-RestMethod -Uri "http://localhost:5178/healthz"`。
容器傳回 500 內部伺服器錯誤	檢視容器日誌以取得詳細錯誤： `docker logs agentid-sdk`。常見原因：中 `appsettings.json`無效的 JSON、憑證路徑不正確、憑證密碼錯誤或遺失 TenantId/ClientId 值。
找不到憑證錯誤	請確定 PFX 檔案已正確複製： `docker exec agentid-sdk ls -la /app/agentid-client-certificate.pfx`。如果遺失，請重新複製： `docker cp agentid-client-certificate.pfx agentid-sdk:/app/agentid-client-certificate.pfx` 並重新啟動： `docker restart agentid-sdk`。
「無效的令牌」或「受眾驗證失敗」錯誤	請確保您的憑證的使用者（`aud` 宣告）與您的客戶ID相符。針對 `/validate` 端點，請使用 scope `api://<client-id>/access_as_user` 。針對 Microsoft Graph 呼叫，請使用 `User.Read`。清除令牌快取： `Remove-Item -Path "$env:USERPROFILE\.msal_token_cache.bin" -ErrorAction SilentlyContinue`。
appsettings.json 未載入	確認檔案已複製到容器中： `docker exec agentid-sdk cat /app/appsettings.json`。確保 JSON 有效（沒有註釋，語法正確）。如果檔案遺失或不正確，請再次複製並重新啟動容器。
容器不會在設定變更後啟動	停止並取出容器： `docker stop agentid-sdk && docker rm agentid-sdk`。按照「提取並執行 AgentID SDK 容器」一節，使用更新的組態檔再次執行容器。

後續步驟

代理身分識別：瞭解如何使用 Microsoft Entra SDK，搭配服務主體與受控身分識別，透過 --agent-identity 和 --agent-username 參數進行測試。
自訂 API：新增更多下游 API 組態，以 appsettings.json 呼叫您自己的受保護 API
生產部署：設定適用於 AgentID 的 Microsoft Entra SDK 以使用受控識別，而不是憑證

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-11-14