你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

对人脸使用受限访问令牌

项目
12/04/2024

独立软件供应商 (ISV) 可以通过颁发访问令牌来管理其客户的人脸 API 使用情况，这些令牌可授予对通常关闭的人脸功能的访问权限。这让他们的客户公司可以使用人脸 API，而无需经过正式的审批流程。

本指南介绍作为已获得批准的 ISV，如何生成访问令牌，以及作为客户，如何使用令牌。

有限访问令牌功能是现有的 Azure AI 服务令牌服务的一部分。我们添加了一个新操作，用于绕过已批准方案的受限访问门。

重要

只有满足门控要求的 ISV 才能访问此功能。要请求批准，请联系 azureface@microsoft.com。

示例用例

一家示例公司销售使用 Azure AI 人脸服务来操作门禁安全系统的软件。他们的客户（门设备的个体制造商）订阅了该软件并在其设备上运行。这些客户公司希望从他们的设备进行人脸 API 调用，以执行人脸识别等受限访问操作。通过依赖 ISV 的访问令牌，他们可以绕过人脸识别的正式审批流程。已获批准的 ISV 可以向客户授予实时访问令牌。

责任预期

颁发令牌的 ISV 负责确保令牌仅用于批准的目的。

如果 ISV 得知客户将 LimitedAccessToken 用于未批准的用途，则应停止为该客户生成令牌。 Microsoft 可以跟踪 LimitedAccessTokens 的颁发和使用情况，如果未解决滥用问题，我们保留撤销 ISV 对 issueLimitedAccessToken API 的访问权限的权利。

先决条件

已安装 cURL（或可以发出 HTTP 请求的其他工具）。
ISV 需要具有 Azure AI 人脸资源或 Azure AI 服务多服务资源。
客户需要具有 Azure AI 人脸资源。

步骤 1：ISV 获取客户的人脸资源 ID

ISV 应该在自己的安全云服务（将生成访问令牌）以及其在客户设备上运行的应用程序之间建立一个通信通道。在生成 LimitedAccessToken 之前，必须知道客户的人脸资源 ID。

人脸资源 ID 采用以下格式：

/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.CognitiveServices/accounts/<face-resource-name>

例如：

/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/client-rg/providers/Microsoft.CognitiveServices/accounts/client-face-api

步骤 2：ISV 生成令牌

ISV 的云服务在安全环境中运行，使用其最终客户已知的人脸资源 ID 调用 issueLimitedAccessToken API。

若要调用 issueLimitedAccessToken API，请将以下 cURL 命令复制到文本编辑器。

curl -X POST 'https://<isv-endpoint>/sts/v1.0/issueLimitedAccessToken?expiredTime=3600' \  
-H 'Ocp-Apim-Subscription-Key: <isv-face-key>' \  
-H 'Content-Type: application/json' \  
-d '{  
    "targetAzureResourceId": "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.CognitiveServices/accounts/<face-resource-name>",  
    "featureFlags": ["Face.Identification", "Face.Verification"]  
}'

然后，进行以下更改：

将 <isv-endpoint> 替换为 ISV 资源的终结点。例如 westus.api.cognitive.microsoft.com。
（可选）设置 expiredTime 参数以设置令牌的到期时间（以秒为单位）。该值必须介于 60 和 86400 之间。默认值为 3600（1 小时）。
将 <isv-face-key> 替换为 ISV 人脸资源的密钥。
将 <subscription-id> 替换为客户 Azure 订阅的订阅 ID。
将 <resource-group-name> 替换为客户资源组的名称。
将 <face-resource-name> 替换为客户人脸资源的名称。
将 "featureFlags" 设置为要授予的访问角色集。可用标志为 "Face.Identification"、"Face.Verification" 和 "LimitedAccess.HighRisk"。 ISV 只能授予 Microsoft 向其授予的权限。例如，如果 ISV 已被授予人脸识别的访问权限，则可以为客户创建一个 LimitedAccessToken for Face.Identification。出于使用和安全目的，记录所有令牌创建和使用。

然后，将命令粘贴到终端窗口并运行它。

API 应返回响应 200，其中包含 JSON Web 令牌形式 (application/jwt) 的令牌。如果要检查 LimitedAccessToken，可以使用 JWT 来执行此操作。

步骤 3：客户应用程序使用令牌

然后，ISV 的应用程序可以代表客户将有限访问令牌作为 HTTP 请求头传递给未来的人脸 API 请求。这独立于其他身份验证机制工作，因此客户的个人信息永远不会泄露给 ISV。

注意

客户不需要知道令牌值，因为它可以在后台传递。如果客户要使用 Web 监视工具来拦截流量，则他们将能够查看 LimitedAccessToken 标头。但是，由于令牌会在短时间后过期，因此他们可以使用的令牌用途有限。此风险是已知的，并且被认为是可以接受的。

由每个 ISV 决定如何将令牌从云服务确切传递到客户应用程序。

REST API
C#

使用访问令牌的示例人脸 API 请求如下所示：

curl -X POST 'https://<client-endpoint>/face/v1.0/identify' \  
-H 'Ocp-Apim-Subscription-Key: <client-face-key>' \  
-H 'LimitedAccessToken: Bearer <token>' \  
-H 'Content-Type: application/json' \  
-d '{  
  "largePersonGroupId": "sample_group",  
  "faceIds": [  
    "c5c24a82-6845-4031-9d5d-978df9175426",  
    "65d083d4-9447-47d1-af30-b626144bf0fb"  
  ],  
  "maxNumOfCandidatesReturned": 1,  
  "confidenceThreshold": 0.5  
}'

注意

终结点 URL 和人脸密钥属于客户的人脸资源，而不是 ISV 的资源。 <token> 作为 HTTP 请求标头传递。

以下代码片段演示如何将访问令牌与适用于 C# 的人脸 SDK 配合使用。

以下类使用访问令牌创建 HttpPipelineSynchronousPolicy 对象，该对象可用于对人脸 API 客户对象进行身份验证。它会在人脸客户将发出的每个请求中自动添加访问令牌作为标头。

public class LimitedAccessTokenPolicy : HttpPipelineSynchronousPolicy
{
    /// <summary>
    /// Creates a new instance of the LimitedAccessTokenPolicy class
    /// </summary>
    /// <param name="limitedAccessToken">LimitedAccessToken to bypass the limited access program, requires ISV sponsership.</param>
    public LimitedAccessTokenPolicy(string limitedAccessToken)
    {
        _limitedAccessToken = limitedAccessToken;
    }

    private readonly string _limitedAccessToken;

    /// <summary>
    /// Add the authentication header to each outgoing request
    /// </summary>
    /// <param name="message">The outgoing message</param>
    public override void OnSendingRequest(HttpMessage message)
    {
        message.Request.Headers.Add("LimitedAccessToken", $"Bearer {_limitedAccessToken}");
    }
}

在客户端应用程序中，可以使用帮助程序类，如以下示例所示：

static void Main(string[] args)
{
    // create Face client object
    var clientOptions = new AzureAIVisionFaceClientOptions();
    clientOptions.AddPolicy(new LimitedAccessTokenPolicy("<token>"), HttpPipelinePosition.PerCall);
    FaceClient faceClient = new FaceClient(new Uri("<client-endpoint>"), new AzureKeyCredential("<client-face-key>"), clientOptions);

    // use Face client in an API call
    using (var stream = File.OpenRead("photo.jpg"))
    {
        var response = faceClient.Detect(BinaryData.FromStream(stream), FaceDetectionModel.Detection03, FaceRecognitionModel.Recognition04, returnFaceId: true);

        Console.WriteLine(JsonConvert.SerializeObject(response.Value));
    }
}

通过