Face に制限付きアクセス トークンを使用する

独立系ソフトウェア ベンダー (ISV) が、通常は限定的な Face 機能へのアクセスを許可するアクセス トークンを発行することで、クライアントの Face API の使用状況を管理する方法について説明します。 これにより、クライアント企業は正式な承認プロセスを経ることなく Face API を使用できます。

このガイドでは、アクセス トークンを生成する方法、承認された ISV の場合、およびクライアントである場合にトークンを使用する方法について説明します。

制限付きアクセス トークン機能は、既存の Azure AI サービス トークン サービスの一部です。 承認されたシナリオで制限付きアクセス ゲートをバイパスする目的で、新しい操作を追加しました。 この機能へのアクセス権が付与されるのは、ゲーティング要件を満たす ISV のみです。

ユース ケースの例

この例の会社では、Azure AI Face サービスを使用してドア アクセス セキュリティ システムを運用するソフトウェアを販売しています。 クライアント、ドア デバイスの個々の製造元は、ソフトウェアをサブスクライブし、自社のデバイスで実行します。 これらのクライアント企業は、顔識別などの制限付きアクセス操作を実行するために、デバイスから Face API 呼び出しを行う必要があります。 ISV からのアクセス トークンを信頼して使用することで、顔識別の正式な承認プロセスをバイパスできます。 既に承認されている ISV は、クライアントに Just-In-Time アクセス トークンを付与できます。

責任の想定

トークン発行 ISV には、トークンが承認された目的にのみ使用されるようにする役割があります。

承認されていない目的でクライアントが LimitedAccessToken を使用していることを ISV が認識した場合、ISV はその顧客用のトークンの生成を停止する必要があります。 Microsoft は LimitedAccessTokens の発行と使用状況を追跡することができ、不正使用への対処が行われない場合、ISV の issueLimitedAccessToken API へのアクセスを取り消す権利を留保します。

[前提条件]

• cURL インストール済み (または HTTP 要求を行うことができる別のツール)。
• ISV には、Azure AI Face リソースまたは Azure AI サービス マルチサービス リソースのいずれかが必要です。
• クライアントには Azure AI Face リソースが必要です。

手順 1: ISV がクライアントの Face リソース ID を取得する

ISV は、(アクセス トークンを生成する) 独自のセキュリティで保護されたクラウド サービスと、クライアントのデバイスで実行されるアプリケーションとの間に通信チャネルを設定する必要があります。 LimitedAccessToken を生成する前に、クライアントの Face リソース ID を認識しておく必要があります。

Face リソース ID の形式は次のとおりです。

/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 のクラウド サービスは、エンド カスタマーの既知の Face リソース ID を使用して 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"]  
}' 

続いて、次の変更を行います。

1. <isv-endpoint> を ISV のリソースのエンドポイントに置き換えます。 たとえば、次のようにします。westus.api.cognitive.microsoft.com。
2. 必要に応じて、expiredTime パラメーターを設定して、トークンの有効期限を秒単位で設定します。 60 から 86400 の範囲である必要があります。 既定値は 3600 (1 時間) です。
3. <client-face-key> をクライアントの Face リソースのキーに置き換えます。
4. <subscription-id> をクライアントの Azure サブスクリプションのサブスクリプション ID に置き換えます。
5. <resource-group-name> をクライアントのリソース グループの名前に置き換えます。
6. <face-resource-name> をクライアントの Face リソースの名前に置き換えます。
7. "featureFlags" を付与するアクセス ロールのセットに設定します。 使用可能なフラグは "Face.Identification"、"Face.Verification"、"LimitedAccess.HighRisk" です。 ISV では、Microsoft によって自身に付与されたアクセス許可のみを付与できます。 たとえば、ISV に顔識別へのアクセスが許可されている場合は、クライアントの Face.Identification 用の LimitedAccessToken を作成できます。 トークンの作成と使用はすべて、使用状況とセキュリティの目的でログに記録されます。

次に、コマンドをターミナル ウィンドウに貼り付けて実行します。

API は、トークンを含む 200 応答を、JSON Web トークン (application/jwt) の形式で返すはずです。 LimitedAccessToken を調べる場合は、JWT を使用して行うことができます。

手順 3: クライアント アプリケーションでトークンを使用する

ISV のアプリケーションでは、将来の Face API 要求の HTTP 要求ヘッダーとして制限付きアクセス トークンをクライアントに代わって渡すことができます。 これは他の認証メカニズムに関係なく機能するため、クライアントの個人情報が ISV に漏洩することはありません。

注意

クライアントは、バックグラウンドで渡すことができるため、トークンの値を認識する必要はありません。 クライアントが Web 監視ツールを使用してトラフィックをインターセプトする場合は、LimitedAccessToken ヘッダーを表示できます。 ただし、トークンは短期間で期限切れになるため、トークンを使用して実行できる操作は制限されます。 このリスクは既知であり、受容できるものと見なされます。

自身のクラウド サービスからクライアント アプリケーションにトークンをどの程度正確に渡すかは、各 ISV が決定します。

REST API

アクセス トークンを使用した Face 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  
}'

Note

エンドポイント URL と Face キーは、ISV のリソースではなく、クライアントの Face リソースに属しています。 <token>は HTTP 要求ヘッダーとして渡されます。

C#

次のコード スニペットでは、Face SDK for C# でアクセス トークンを使用する方法を示しています。

次のクラスでは、アクセス トークンを使用して、Face API クライアント オブジェクトの認証に使用できる ServiceClientCredentials オブジェクトを作成します。 Face クライアントが行うすべての要求で、アクセス トークンがヘッダーとして自動的に追加されます。

public class LimitedAccessTokenWithApiKeyClientCredential : ServiceClientCredentials 
{
    /// <summary> 
    /// Creates a new instance of the LimitedAccessTokenWithApiKeyClientCredential class 
    /// </summary> 
    /// <param name="apiKey">API Key for the Face API or CognitiveService endpoint</param> 
    /// <param name="limitedAccessToken">LimitedAccessToken to bypass the limited access program, requires ISV sponsership.</param> 

    public LimitedAccessTokenWithApiKeyClientCredential(string apiKey, string limitedAccessToken) 
    { 
        this.ApiKey = apiKey; 
        this.LimitedAccessToken = limitedAccessToken; 
    }

    private readonly string ApiKey; 
    private readonly string LimitedAccesToken; 

    /// <summary> 
    /// Add the Basic Authentication Header to each outgoing request 
    /// </summary> 
    /// <param name="request">The outgoing request</param>
    /// <param name="cancellationToken">A token to cancel the operation</param> 
    public override Task ProcessHttpRequestAsync(HttpRequestMessage request, CancellationToken cancellationToken) 
    { 
        if (request == null) 
            throw new ArgumentNullException("request"); 
        request.Headers.Add("Ocp-Apim-Subscription-Key", ApiKey); 
        request.Headers.Add("LimitedAccessToken", $"Bearer {LimitedAccesToken}");

        return Task.FromResult<object>(null); 
    } 
} 

クライアント側アプリケーションでは、ヘルパー クラスを次の例のように使用できます。

static void Main(string[] args) 
{ 
    // create Face client object
    var faceClient = new FaceClient(new LimitedAccessTokenWithApiKeyClientCredential(apiKey: "<client-face-key>", limitedAccessToken: "<token>")); 

    faceClient.Endpoint = "https://mytest-eastus2.cognitiveservices.azure.com"; 

    // use Face client in an API call
    using (var stream = File.OpenRead("photo.jpg")) 
    {
        var result = faceClient.Face.DetectWithStreamAsync(stream, detectionModel: "Detection_03", recognitionModel: "Recognition_04", returnFaceId: true).Result; 

        Console.WriteLine(JsonConvert.SerializeObject(result)); 
    }
}