使用 Microsoft Graph 为代理创建标识(预览版)

注册代理,以便它可以通过Microsoft Entra ID进行身份验证,并请求访问 API。 此设置为代理创建一个标识,由其安装或副本共享。

此过程使用 Microsoft Graph beta 版。 对于云代理,请为其运行时配置凭据。 对于安装在最终用户设备上的代理,请使用没有凭据的公共客户端重定向配置。 呼叫教程标识所需的部分。

Important

单实例代理标识以预览版提供。 此预览版在没有服务级别协议的情况下提供,不建议用于生产工作负荷。 某些功能可能不受支持或功能受限。 有关详细信息,请参阅 联机服务的通用许可条款。

Prerequisites

  • 在 Microsoft Graph 中启用了单实例预配的 Microsoft Entra 租户 在开始之前,请与Microsoft代表确认预览版可用性和租户启用。 若要在设置后请求令牌,还确认已启用单实例身份验证;单独启用预配和身份验证。
  • 有权创建和更新代理标识蓝图和代理标识的帐户,例如 代理 ID 管理员。
  • 一个单独的单租户公共管理应用,已获得管理员同意,可使用委派的 Microsoft Graph 权限 AgentIdentityBlueprint.ReadWrite.All 和 AgentIdentity.ReadWrite.All,或有权设置管理客户端。
  • 可以向管理应用的 Graph 权限授予许可的管理员。
  • 可分配为蓝图发起人的用户的对象 ID。 这些示例还将该用户分配为所有者。
  • 对于交互式登录,适用于客户端类型的重定向 URI。 对于基于浏览器的管理员同意,即使代理仅在运行时使用客户端凭据,也需要一个 web 重定向 URI。
  • 对于本地机密客户端测试,需要 X.509 证书及其私钥的安全存储。 Azure托管代理可以改用托管标识联合凭据。 仅公共客户端不需要凭据。
  • 对于 API 访问,您需要提供资源应用程序的客户端 ID,以及代理所需的委派权限或应用角色的 ID。

按如下所述通过 Microsoft Graph PowerShell 运行 HTTP 示例,或使用可以发送 JSON 请求正文和标头的 REST 客户端。 在 REST 客户端中,在每个 Graph 请求的 Authorization 标头中将管理令牌作为 Bearer 令牌发送。 切勿将代理的运行时访问令牌用于管理请求。

确认管理员交接

在创建对象之前,请就以下交接达成一致。 管理同意和代理的运行时 API 同意是单独的审批。

谁 Action 何时就绪
租户管理员和Microsoft代表。 确认已启用预览预配和身份验证。 租户支持此设置的注册和令牌请求。
授权管理员。 批准上面列出的管理客户端的两个 Graph 权限。 操作员可以使用两个已获同意的范围权限登录到该客户端。
开发人员或授权操作员。 完成下面的注册步骤。 已记录蓝图对象 ID、代理标识对象 ID 和共享客户端 ID。
API 所有者和同意管理员。 提供 API 标识符并批准调用教程所需的权限。 所需的运行时授权会在首次 API 调用前得到验证。

向管理员发送租户 ID、管理客户端 ID 和请求的 API 权限。 将 标识符工作表 与设置步骤一起保留。

如果遵循本地 HTTPS 教程,请在浏览器登录之前确认计算机上信任开发 HTTPS 证书。 遵循组织的信任过程,而不是禁用 TLS 验证。

设置管理客户端

管理客户端登录管理员或授权操作员以创建代理的注册。 它独立于代理的运行时标识。 现有的Azure CLI登录不建立此管理上下文。

  1. 在同一租户中注册应用程序。 选择仅限此组织目录中的帐户选项。 在“身份验证”下,添加http://localhost平台,并使用重定向 URI 。

  2. 在 API 权限下,添加以下Microsoft Graph>委派权限:

    • AgentIdentityBlueprint.ReadWrite.All。
    • AgentIdentity.ReadWrite.All。
  3. 拥有授权的管理员授予对这些权限的同意。 有关管理员同意的信息,请参阅Microsoft 标识平台 中的权限和同意。

  4. 安装 Microsoft Graph PowerShell 身份验证模块,并使用管理应用登录。 Connect-MgGraph 打开已登录用户的浏览器:

    Install-Module Microsoft.Graph.Authentication -Scope CurrentUser
    
    Connect-MgGraph `
      -ClientId "<management-app-client-id>" `
      -TenantId "<tenant-id>" `
      -Scopes "AgentIdentityBlueprint.ReadWrite.All", "AgentIdentity.ReadWrite.All" `
      -ContextScope Process
    
    $context = Get-MgContext
    if (-not $context -or -not $context.Account) {
        throw "Microsoft Graph sign-in didn't establish a delegated management context. Stop before creating objects."
    }
    $context | Select-Object Account, TenantId, ClientId, Scopes
    

    确认Account并TenantIdClientId标识预期的操作员、租户和管理应用,并包括这两个Scopes权限。 如果范围缺失或再次请求同意,请停止并让授权管理员在继续之前验证应用注册和同意。

在 Windows 上,如果 Connect-MgGraph 在登录前因 必须配置窗口句柄 而失败,请对自定义管理客户端使用 文档记录的浏览器登录选项:

Set-MgGraphOption -DisableLoginByWAM $true

再次运行相同的 Connect-MgGraph 命令。 这会更改身份验证 UI,而不是租户的访问要求;请以授权操作员身份完成登录,不要绕过因合规性被拒绝的限制。 该设置在不同 PowerShell 会话之间持续生效。 如果在此更改之前启用了 WAM,完成后请使用 Set-MgGraphOption -DisableLoginByWAM $false 将其还原。

使用 Invoke-MgGraphRequest 运行 HTTP 示例,而无需复制或显示访问令牌。 例如,将 JSON 正文从 “创建蓝图 ”复制到该蓝图中 $body,替换发起人占位符:

$body = @'
<JSON-request-body>
'@

$blueprint = Invoke-MgGraphRequest -Method POST `
    -Uri "https://graph.microsoft.com/beta/applications" `
    -Headers @{ "OData-Version" = "4.0" } `
    -ContentType "application/json" -Body $body

$blueprintObjectId = $blueprint.id
$agentClientId = $blueprint.appId

对于以后的请求,请使用每个 HTTP 示例中所示的方法、完整 URI、标头和 JSON 正文。 对于 GET 请求,省略 -Body。 该模块提供授权标头。 有关命令语法,请参阅 Invoke-MgGraphRequest。

如果注册或管理员同意被拒绝,请让租户管理员完成此设置。 不要向代理授予这些管理权限,以解决授权错误。

创建蓝图

蓝图是保存代理的身份验证设置和凭据的注册信息。

  1. 创建蓝图,并将 isSingleInstance 设置为 true。 将 <sponsor-user-object-id> 替换为发起人的对象 ID。 需要赞助人;所有者分配是可选的。

    在本教程中保留 isSingleInstance: true:它为代理创建一个标识,包括其安装或副本。 创建后无法更改此属性。

    POST https://graph.microsoft.com/beta/applications
    OData-Version: 4.0
    Content-Type: application/json
    
    {
      "@odata.type": "Microsoft.Graph.AgentIdentityBlueprint",
      "displayName": "Contoso Operations Agent",
      "signInAudience": "AzureADMyOrg",
      "isSingleInstance": true,
      "sponsors@odata.bind": [
        "https://graph.microsoft.com/v1.0/users/<sponsor-user-object-id>"
      ],
      "owners@odata.bind": [
        "https://graph.microsoft.com/v1.0/users/<sponsor-user-object-id>"
      ]
    }
    
  2. 从 201 Created 响应中保存以下值:

    • id:蓝图的对象 ID,用于在Microsoft Graph中对其进行寻址。
    • appId:OAuth 请求中使用的应用程序(客户端)ID。

该示例创建一个将 设置为 的单租户蓝图。

预配代理标识

独立于其蓝图注册创建标识。 按照以下请求直接执行;此设置不需要蓝图主体身份。

  1. 创建代理 ID。 将agentIdentityBlueprintId设置为蓝图的对象 ID,而不是其appId。

    POST https://graph.microsoft.com/beta/servicePrincipals/microsoft.graph.agentIdentity
    OData-Version: 4.0
    Content-Type: application/json
    
    {
      "displayName": "Contoso Operations Agent",
      "agentIdentityBlueprintId": "<blueprint-object-id>",
      "sponsors@odata.bind": [
        "https://graph.microsoft.com/v1.0/users/<sponsor-user-object-id>"
      ]
    }
    
  2. 从id响应中保存标识的201 Created。 这是代理标识的对象 ID,而不是蓝图对象 ID 或 OAuth 客户端 ID。

  3. 读取标识以验证结果:

    GET https://graph.microsoft.com/beta/servicePrincipals/<agent-identity-object-id>?$select=id,appId,displayName,agentIdentityBlueprintId,instanceMode
    

    检查返回的值:

    Property 预期值
    @odata.type #microsoft.graph.agentIdentity。
    appId 蓝图的 appId.
    agentIdentityBlueprintId 蓝图的对象 ID。
    instanceMode singleInstance。

不要为每个安装、进程或用户会话预配新标识。 它们使用相同的客户端 ID。

配置重定向 URI

对于授权代码流,请在与客户端匹配的平台下注册重定向 URI。 机密客户端使用 web;公共客户端使用 publicClient。

基于浏览器的管理员同意过程还需要web重定向 URI,即使对于仅在运行时使用客户端凭据的代理也是如此。 重定向 URI 处理同意回调,而不是客户端凭据令牌请求。 仅当既不需要授权代码流,也不需要基于浏览器的管理员同意时,才跳过本部分。

  1. 读取当前重定向配置:

    GET https://graph.microsoft.com/beta/applications/<blueprint-object-id>?$select=id,appId,web,publicClient
    
  2. 更新相应的重定向集合。 以下示例显示了这两种客户端类型;仅包含代理程序使用的平台。 保留仍需要的所有现有重定向 URI。

    PATCH https://graph.microsoft.com/beta/applications/<blueprint-object-id>
    OData-Version: 4.0
    Content-Type: application/json
    
    {
      "@odata.type": "#microsoft.graph.agentIdentityBlueprint",
      "web": {
        "redirectUris": [
          "https://agent.contoso.com/signin"
        ]
      },
      "publicClient": {
        "redirectUris": [
          "http://localhost"
        ]
      }
    }
    

    成功的更新返回 204 No Content。 重定向 URI 集合会被替换,而不是追加。 请勿用此示例覆盖现有配置而不保留其 URI。

同一蓝图可以注册两个平台。 每个授权请求都使用其客户端类型对应的重定向 URI。 即使机密组件在同一蓝图上使用证书,公共客户端也不会发送凭据。 不要更改 isFallbackPublicClient 来在这些授权代码方案之间切换。

为机密客户端添加证书

对于本地机密客户端测试,请仅在应用清单上注册公共证书。 运行时保留用于身份验证的私钥。

对于纯公共客户端,请跳过此部分。 对于使用托管标识联合的Azure托管代理,请改为配置联合凭据,然后继续声明 API 权限。

对于Windows开发计算机,可以创建自签名证书并导出其公共证书和受密码保护的 PFX。 将 PFX 保留在源树之外。 请使用用于下方 key 的 Base64 编码 DER 公共证书,而不是 PFX 或 PEM 文件的页眉和页脚。 例如:

$publicCertificate = Get-PfxCertificate -FilePath "<absolute-path-to-public-cer>"
$publicCertificateBase64 = [Convert]::ToBase64String($publicCertificate.RawData)

粘贴 $publicCertificateBase64 到注册请求中。 公共值不是凭据;而 PFX 及其密码才是凭据。 对于非Windows开发或生产,请使用组织的证书颁发和私钥存储过程。

  1. 读取当前证书集合:

    GET https://graph.microsoft.com/beta/applications/<blueprint-object-id>?$select=id,appId,keyCredentials
    
  2. 在保留仍需要的任何现有密钥凭据的同时添加公共证书。 以下请求显示没有现有证书的初始注册:

    PATCH https://graph.microsoft.com/beta/applications/<blueprint-object-id>
    OData-Version: 4.0
    Content-Type: application/json
    
    {
      "@odata.type": "#microsoft.graph.agentIdentityBlueprint",
      "keyCredentials": [
        {
          "type": "AsymmetricX509Cert",
          "usage": "Verify",
          "key": "<base64-encoded-DER-certificate>",
          "displayName": "Contoso Operations Agent certificate"
        }
      ]
    }
    

    成功的更新返回 204 No Content。 切勿上传私钥,也不要将其随公共客户端分发。

有关证书格式和客户端断言指南,请参阅Microsoft 标识平台证书凭据。

声明 API 权限

仅声明代理所需的权限。 使用 Scope 表示委派权限,使用 Role 表示应用程序权限。 resourceAccess 中的这些值是资源应用程序公开的权限 ID,而不是权限名称。

  1. 读取当前声明:

    GET https://graph.microsoft.com/beta/applications/<blueprint-object-id>?$select=id,appId,requiredResourceAccess
    
  2. 添加资源和权限条目,保留仍然需要的现有声明。 该示例显示了一个委派权限和一个应用程序权限;如果你的代理不需要其中之一,请删除任一条目。

    PATCH https://graph.microsoft.com/beta/applications/<blueprint-object-id>
    OData-Version: 4.0
    Content-Type: application/json
    
    {
      "@odata.type": "#microsoft.graph.agentIdentityBlueprint",
      "requiredResourceAccess": [
        {
          "resourceAppId": "<resource-app-id>",
          "resourceAccess": [
            {
              "id": "<delegated-permission-id>",
              "type": "Scope"
            },
            {
              "id": "<app-role-id>",
              "type": "Role"
            }
          ]
        }
      ]
    }
    

    成功的更新返回 204 No Content。

这些声明不授予访问权限。 用户或管理员同意会授予委派权限,管理员授予应用程序权限。 这些授权直接属于代理 ID。

如果代理还接收来自前端应用程序的请求,请 在蓝图上公开标识符 URI 和委托范围。 保留任何现有 API 范围,并将 requestedAccessTokenVersion 设置为 2。 前端请求该作用域以获取其受众为共享客户端 ID 的令牌。

Graph 请求疑难解答

如果请求失败,请在更改权限或重试操作之前检查 HTTP 状态和 Graph 错误响应。

Response 检查
400 Bad Request 读取 error.code 和 error.message。 检查终结点的请求架构、所需的发起人引用、对象 ID 和属性值。
401 Unauthorized 获取 Microsoft Graph 的有效访问令牌,并在 Authorization 标头中发送它。
403 Forbidden 确认管理应用已具有所需的委派权限并已获得管理员同意、已登录用户有权执行该操作,并且租户已启用预览。

有关详细信息,请参阅Microsoft Graph错误响应。 联系管理员或 Microsoft 支持人员时,请提供 HTTP 状态、错误代码和 request-id 响应标头。 不要包含访问令牌或其他凭据。

后续步骤

返回到引导你来到这里的教程:

有关直接 OAuth 请求以及此设置背后的身份模型,请参阅 验证代理身份 和 代理身份蓝图实例模式。