使用臉部的有限存取權杖

發行項
09/04/2024

獨立軟體廠商 (ISV) 可以核發存取權杖以授與通常受管制的臉部功能存取權，界以管理用戶端的臉部 API 使用。這可讓其用戶端公司使用臉部 API，而無須進行正式核准程序。

本指南說明如果您是已核准的 ISV，要如何產生存取權杖；如果您是用戶端，要如何使用權杖。

LimitedAccessToken 功能是現有 Azure AI 服務權杖服務的一部分。為了略過已核准案例的有限存取閘道，我們新增了新的作業。只有通過管制需求的 ISV 才會獲得此功能的存取權。

使用案例範例

有一家範例公司銷售軟體，使用 Azure AI 臉部服務來操作門禁安全性系統。其用戶端、大門裝置的個別製造商，都會訂閱軟體並在其裝置上執行。這些用戶端公司想要從其裝置進行臉部 API 呼叫，以執行有限存取作業，例如臉部識別。藉由依賴 ISV 的存取權杖，他們可以略過臉部識別的正式核准程序。已核准的 ISV 可以授與用戶端 Just-In-Time 存取權杖。

期望責任

發行權杖的 ISV 負責確保權杖僅用於核准目的。

如果 ISV 發現用戶端使用 LimitedAccessToken 進行非核准用途，則 ISV 應該停止為該客戶產生權杖。 Microsoft 可以追蹤 LimitedAccessTokens 的發行和使用方式，如果未解決濫用，我們保留撤銷 ISV 對 issueLimitedAccessToken API 存取權的權利。

必要條件

cURL 安裝 (或可進行 HTTP 要求的其他工具)。
ISV 必須有 Azure AI 臉部資源或 Azure AI 服務多服務資源。
用戶端必須有 Azure AI 臉部資源。

步驟 1：ISV 取得用戶端的臉部資源識別碼

ISV 應該在自己的安全雲端服務 (該服務會產生存取權杖) 與用戶端裝置上所執行的應用程式之間，設定通訊通道。產生 LimitedAccessToken 之前，必須先知道用戶端的臉部資源識別碼。

臉部資源識別碼具有下列格式：

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

例如：

/subscriptions/dc4d27d9-ea49-4921-938f-7782a774e151/resourceGroups/client-rg/providers/Microsoft.CognitiveServices/accounts/client-face-api

步驟 2：ISV 產生權杖

ISV 的雲端服務 (在安全的環境中執行) 會使用其終端客戶的已知臉部資源識別碼呼叫 issueLimitedAccessToken API。

若要呼叫 issueLimitedAccessToken API，請將下列 cURL 命令複製到文字編輯器。

curl -X POST 'https://<isv-endpoint>/sts/v1.0/issueLimitedAccessToken?expiredTime=3600' \  
-H 'Ocp-Apim-Subscription-Key: <client-face-key>' \  
-H 'Content-Type: application/json' \  
-d '{  
    "resourceId": "/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 (一小時)。
將 <client-face-key> 取代為用戶端臉部資源的金鑰。
將 <subscription-id> 取代為用戶端 Azure 訂用帳戶的訂用帳戶識別碼。
將 <resource-group-name> 取代為用戶端資源群組的名稱。
將 <face-resource-name> 取代為用戶端臉部資源的名稱。
將 "featureFlags" 設定為您想要授與的存取角色集。可用的旗標為 "Face.Identification"、"Face.Verification" 和 "LimitedAccess.HighRisk"。 ISV 只能授與 Microsoft 已授與他們本身的權限。例如，如果 ISV 已獲得臉部識別的存取權，可以為用戶端的 Face.Identification 建立 LimitedAccessToken。系統會針對使用方式和安全性目的，記錄所有權杖建立和使用方式。

然後，將命令貼到終端機視窗並加以執行。

API 應該以 JSON Web 權杖的形式 (application/jwt) 傳回 200 回應。如果您想要檢查 LimitedAccessToken，您可以使用 JWT 來執行此動作。

步驟 3：用戶端應用程式使用權杖

ISV 的應用程式接著可以代表用戶端傳遞有限存取權杖，作為未來臉部 API 要求的 HTTP 要求標頭。這與其他驗證機制無關，因此用戶端的個人資訊不會外洩給 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));
    }
}

共用方式為