應用程式角色定義誰可以存取代理程式及其能做什麼。 使用它們來限制代理程式操作僅限於核准的使用者、群組或用戶端應用程式。
在本文中,您將定義入站存取角色,將其指派給呼叫者,並在代理程式 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 前拒絕登入或令牌的發放。