透過應用程式角色控制代理程式的存取

應用程式角色定義誰可以存取代理程式及其能做什麼。 使用它們來限制代理程式操作僅限於核准的使用者、群組或用戶端應用程式。

在本文中,您將定義入站存取角色,將其指派給呼叫者,並在代理程式 API 中強制執行。 你在哪裡定義角色,取決於代理程式使用單一實例藍圖還是 fleet。

先決條件

  • 藍圖及其代理程式 API 服務主體。
  • 授權的 Microsoft Graph 管理用戶端用於角色設定。 若要進行委派單一代理程式管理,已登入的使用者必須擁有代理程式身分識別,或具有 代理程式識別管理員 角色。 請參閱 更新 servicePrincipal 以了解適用的 API 權限。
  • 應用程式管理員 或 雲端應用程式管理員 ,用於管理使用者及群組應用程式角色指派。
  • AppRoleAssignment.ReadWrite.All 以及程式化作業所需的適當讀取權限。

在單一實例雲端旅程中,API 的服務主體是 代理身分,而非藍圖主體。 請在本文中的請求裡將其物件 ID 作為 <agent-api-service-principal-object-id> 使用。 單一實例藍圖沒有 blueprint principal。 進階艦隊旅程則改用艦隊的 藍圖主體;其指派適用於整個艦隊。

定義應用程式角色

選擇您的實例模式的定義位置:

實例模式 定義入站角色 將角色指派於
單實例 藍圖應用程式與 Agent ID 服務主體使用相同的角色 GUID 與值。 代理程式 ID 服務主體。
Fleet 藍圖應用程式。 代表車隊 API 的藍圖主體身分。

當所有人擁有相同的存取權限時,請使用單一角色。 例如,對標準任務使用 Agent.User,僅在提供管理任務時才新增 Agent.Admin。 保持角色值穩定,因為你的授權政策會檢查這些值。

在藍圖上宣告角色

在藍圖應用程式的Agent.User集合中定義appRoles。 對於單一執行個體代理程式,請完成下一節,使其代理程式 ID 上能使用相同角色。

先閱讀藍圖現有的 appRoles。 以下請求是針對沒有現有角色的藍圖。 對於現有集合,請包含您打算保留的現有角色定義;更新 appRoles 會取代該集合。 請從請求中省略唯讀 origin 欄位。

以新的 GUID 取代 <agent-user-role-id>,並儲存此 GUID 供後續指派步驟使用:

PATCH https://graph.microsoft.com/beta/applications/<blueprint-object-id>
Content-Type: application/json
Authorization: Bearer <management-access-token>

{
  "@odata.type": "#microsoft.graph.agentIdentityBlueprint",
  "appRoles": [
    {
      "id": "<agent-user-role-id>",
      "allowedMemberTypes": ["User"],
      "description": "Use standard agent features",
      "displayName": "Agent user",
      "isEnabled": true,
      "value": "Agent.User"
    }
  ]
}

單一執行個體的使用者存取

對於單一執行個體代理程式,請直接在代理程式 ID appRoles 集合中發佈相同的使用者角色。 使用與藍圖宣告 相同的 GUID 和值 ,而非第二個角色 GUID。 僅藍圖宣告不會讓該角色在代理程式 ID 上可供指派。 僅限服務主體的定義無法完成本程序所使用的藍圖設定。

請先閱讀 Agent ID 現有的角色,並在更新時保留其定義。 對於沒有現有角色的代理程式 ID,請傳送:

PATCH https://graph.microsoft.com/beta/servicePrincipals/<agent-api-service-principal-object-id>
Content-Type: application/json
Authorization: Bearer <management-access-token>

{
  "appRoles": [
    {
      "id": "<agent-user-role-id>",
      "allowedMemberTypes": ["User"],
      "description": "Use standard agent features",
      "displayName": "Agent user",
      "isEnabled": true,
      "value": "Agent.User"
    }
  ]
}

這是對兩個獨立物件的角色設定,而非權限繼承或下游 API 授權。 不要為單一實例代理建立藍圖主體身分。

服務主體定義 User 支援使用者與群組。 不要在此請求中添加 Application 內容:可指派給用戶端應用程式的角色必須在應用程式物件上定義。 此單一執行個體程序涵蓋輸入使用者存取,不涵蓋僅限應用程式的呼叫者。 請參閱 appRole 資源參考。

車隊存取權

對於艦隊,請使用藍圖宣告,但不進行單一實例的服務主體更新。 在allowedMemberTypes中包含User,供使用者或群組使用,並為用戶端應用程式包含Application。 關於應用程式層級的程序,請參閱 「將應用程式角色新增至應用程式」。 請使用藍圖主體,而非子代理 ID,作為入站指派的資源。

驗證資源主體上的角色

在要求必須具備或指派角色之前,請使用 GET https://graph.microsoft.com/beta/applications/<blueprint-object-id>?$select=appRoles 讀回藍圖,並使用 GET https://graph.microsoft.com/v1.0/servicePrincipals/<agent-api-service-principal-object-id>?$select=appRoles 讀回代理 API 主體。 請使用授權管理用戶端,而非代理程式的執行時令牌。

確認委託人 appRoles 中包含該角色的精確 id 與 value,且 isEnabled 為 true,並且 allowedMemberTypes 包含預定的受指派者類型。

如果有指派回傳 Permission being assigned was not found on application,請檢查資源主體的角色定義以及該指派的 resourceId 和 appRoleId。 對於單一執行個體代理程式,如果您只在藍圖上定義了角色,請完成上述直接定義。 不要建立藍圖主體、替換其他資源,或移除 API 的角色檢查。 僅在預期主體提供該角色後繼續。

要求應用程式角色指派

設定 appRoleAssignmentRequired 在代理 API 服務主體上。 當屬性為 true時,Microsoft Entra ID 僅會為已指派的使用者與應用程式發放代理程式 API 的存取權杖。

PATCH https://graph.microsoft.com/v1.0/servicePrincipals/<agent-api-service-principal-object-id>
Content-Type: application/json
Authorization: Bearer <access-token>

{
  "appRoleAssignmentRequired": true
}

如需更多資訊,請參閱 Microsoft Graph 更新 API 參考資料。

指派應用程式角色

將應用程式角色指派給代理 API 服務主體上的使用者:

POST https://graph.microsoft.com/v1.0/users/<user-object-id>/appRoleAssignments
Content-Type: application/json
Authorization: Bearer <access-token>

{
  "principalId": "<user-object-id>",
  "resourceId": "<agent-api-service-principal-object-id>",
  "appRoleId": "<app-role-id>"
}

使用您定義 Agent.User 為 <app-role-id>時儲存的 GUID。 對於群組,透過該群組的應用程式角色指派建立指派。 對於允許 Application的艦隊角色,請透過該用戶端的服務主體建立用戶端應用程式的指派。 在所有情況下,請將代理 API 服務主體的物件 ID 作為 resourceId 使用。

在代理程式 API 中強制執行應用程式角色

當指派的使用者或應用程式取得代理 API 的存取權杖時,Microsoft Entra ID 會在該權杖roles的聲明中包含指派的應用程式角色值。 代理 API 會在允許所請求的操作之前檢查該宣告。

設定驗證與權杖驗證後,新增需要應用程式角色的授權原則:

在 Program.cs 中,將政策註冊合併至 builder.Services.AddAuthorization,並置於 builder.Build() 之前。 將端點對應放在驗證與授權中介軟體之後,且在 app.Run() 之前;在完整應用程式中,此片段的兩個部分並不相鄰。

builder.Services.AddAuthorization(options =>
{
    options.AddPolicy(
        "AgentUser",
        policy => policy.RequireRole("Agent.User"));
});

app.MapPost("/tasks", () => Results.Accepted())
    .RequireAuthorization("AgentUser");

AddAuthorization註冊 ASP.NET Core 授權服務。 RequireRole 檢查已驗證的身分是否具有 Agent.User 角色。 Microsoft。Identity.Web 會在存取權杖聲明roles中識別 Microsoft Entra 應用程式角色。

在中介軟體管線中呼叫 UseAuthentication 之前 UseAuthorization ,如驗證文章所示。 變更指派後申請新的存取權杖。 在疑難排解時,請確認代理 API 服務主體的指派及權杖的 roles 聲明。

使用新的代理 API 代幣及指派 Agent.User 角色後,範例 POST /tasks 會回傳 202 Accepted。 沒有令牌的話,預期 401;如果租戶發出該令牌,則該令牌會被 403 拒絕。 當需要指派時,Microsoft Entra ID 可能會在請求抵達您的 API 前拒絕登入或令牌的發放。