Použití omezených přístupových tokenů pro rozpoznávání tváře

Nezávislí dodavatelé softwaru (ISV) můžou spravovat využití rozhraní API pro rozpoznávání tváře svých klientů tak, že vystavují přístupové tokeny, které udělují přístup k funkcím rozpoznávání tváře, které jsou normálně brány. To umožňuje svým klientským společnostem používat rozhraní API pro rozpoznávání tváře, aniž by musely projít formálním procesem schvalování.

V této příručce se dozvíte, jak vygenerovat přístupové tokeny, pokud jste schválený výrobce softwaru a jak tyto tokeny používat, pokud jste klient.

Funkce omezeného přístupového tokenu je součástí stávající služby tokenů služeb Azure AI. Přidali jsme novou operaci pro účely obejití brány s omezeným přístupem pro schválené scénáře. Přístup k této funkci budou mít pouze nezávislí výrobci softwaru, kteří splňují požadavky na gating.

Příklad případu použití

Příklad společnosti prodává software, který používá službu Azure AI Face k provozování systémů zabezpečení přístupu k dveřím. Jejich klienti, jednotliví výrobci dveřních zařízení, se přihlásí k odběru softwaru a spustí ho na svých zařízeních. Tyto klientské společnosti chtějí ze svých zařízení volat rozhraní API pro rozpoznávání tváře, aby prováděly operace s omezeným přístupem, jako je identifikace tváře. Spoléháním na přístupové tokeny od nezávislých výrobců softwaru můžou obejít formální proces schvalování pro identifikaci tváře. IsV, který už byl schválen, může klientovi udělit přístupové tokeny za běhu.

Očekávání odpovědnosti

Výrobce softwaru, který vydává tokeny, zodpovídá za zajištění, že se tokeny používají pouze pro schválený účel.

Pokud isV zjistí, že klient používá LimitedAccessToken pro neschváliné účely, měl by výrobce softwaru přestat generovat tokeny pro tohoto zákazníka. Microsoft může sledovat vystavování a používání LimitedAccessTokens a vyhrazujeme si právo odvolat přístup nezávislých výrobců softwaru k tomuto problému, pokud se zneužití nevyřeší.

Požadavky

• Nainstalovaný cURL (nebo jiný nástroj, který může provádět požadavky HTTP).
• Poskytovatel softwaru musí mít prostředek Azure AI face nebo prostředek služby Azure AI s více službami .
• Klient musí mít prostředek Azure AI Face .

Krok 1: IsV získá ID prostředku tváře klienta.

Poskytovatel internetových služeb by měl nastavit komunikační kanál mezi vlastní zabezpečenou cloudovou službou (která vygeneruje přístupový token) a aplikací spuštěnou na zařízení klienta. Id prostředku rozpoznávání tváře klienta musí být známo před generováním LimitedAccessTokenu.

ID prostředku tváře má následující formát:

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

Příklad:

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

Krok 2: IsV vygeneruje token

Cloudová služba nezávislých výrobců softwaru spuštěná v zabezpečeném prostředí volá rozhraní APILimitedAccessToken pomocí známého ID prostředku face koncového zákazníka.

Pokud chcete volat problémLimitedAccessToken API, zkopírujte do textového editoru následující příkaz 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"]  
}' 

Pak proveďte následující změny:

1. Nahraďte <isv-endpoint> koncovým bodem prostředku isV. Například westus.api.cognitive.microsoft.com.
2. Volitelně můžete parametr nastavit expiredTime tak, aby nastavil dobu vypršení platnosti tokenu v sekundách. Musí být mezi 60 a 86400. Výchozí hodnota je 3600 (jedna hodina).
3. Nahraďte <client-face-key> klíčem prostředku tváře klienta.
4. Nahraďte <subscription-id> ID předplatného předplatného Azure klienta.
5. Nahraďte <resource-group-name> názvem skupiny prostředků klienta.
6. Nahraďte <face-resource-name> názvem prostředku tváře klienta.
7. Nastavte "featureFlags" na sadu přístupových rolí, které chcete udělit. Dostupné příznaky jsou "Face.Identification", "Face.Verification"a "LimitedAccess.HighRisk". IsV může udělit oprávnění, která sama udělila Microsoftu. Pokud má například isV udělený přístup k identifikaci tváře, může pro klienta vytvořit LimitedAccessToken pro Face.Identification . Všechna vytváření a použití tokenů se protokolují pro účely použití a zabezpečení.

Potom příkaz vložte do okna terminálu a spusťte ho.

Rozhraní API by mělo vrátit 200 odpověď s tokenem ve formě webového tokenu JSON (application/jwt). Pokud chcete zkontrolovat LimitedAccessToken, můžete to udělat pomocí JWT.

Krok 3: Klientská aplikace používá token

Aplikace isV pak může předat omezený přístupový token jako hlavičku požadavku HTTP pro budoucí žádosti rozhraní API pro rozpoznávání tváře jménem klienta. Funguje to nezávisle na jiných ověřovacích mechanismech, takže do nezávislého výrobce softwaru nikdy nedochází k úniku osobních údajů o klientovi.

Upozornění

Klient si nemusí být vědom hodnoty tokenu, protože se dá předat na pozadí. Pokud by klient používal nástroj pro monitorování webu k zachycení provozu, mohl by zobrazit hlavičku LimitedAccessToken. Vzhledem k tomu, že platnost tokenu vyprší po krátké době, jsou omezené tím, co s ním můžou dělat. Toto riziko je známo a považováno za přijatelné.

Je určená každému isV, aby se rozhodl, jak přesně předává token ze své cloudové služby do klientské aplikace.

REST API

Příklad požadavku rozhraní API pro rozpoznávání tváře pomocí přístupového tokenu vypadá takto:

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  
}'

Poznámka:

Adresa URL koncového bodu a klíč tváře patří do prostředku tváře klienta, nikoli do prostředku isV. Předá se jako hlavička <token> požadavku HTTP.

C#

Následující fragmenty kódu ukazují, jak používat přístupový token se sadou SDK pro rozpoznávání tváře pro C#.

Následující třída používá přístupový token k vytvoření objektu ServiceClientCredentials , který lze použít k ověření objektu klienta rozhraní API pro rozpoznávání tváře. Automaticky přidá přístupový token jako hlavičku v každém požadavku, který klient rozpoznávání tváře provede.

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); 
    } 
} 

V aplikaci na straně klienta lze pomocnou třídu použít jako v tomto příkladu:

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

    faceClient.Endpoint = "https://willtest-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)); 
    }
}

Další kroky

• Reference k rozhraní API LimitedAccessToken