Použití omezených přístupových tokenů pro Face

Nezávislí dodavatelé softwaru (ISV) můžou spravovat využití Face API svých klientů tím, že vydávají přístupové tokeny, které udělují přístup k funkcím rozpoznávání tváře, jež jsou normálně omezené. 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ů Azure AI Services. Přidali jsme novou operaci pro účely obejití brány s omezeným přístupem pro schválené scénáře.

Důležité

Přístup k této funkci budou mít pouze nezávislí výrobci softwaru, kteří splňují přístupové požadavky. Pokud chcete požádat o schválení, kontaktujte azureface@microsoft.com.

Požadavky

• Nainstalovaný cURL (nebo jiný nástroj, který může provádět požadavky HTTP).
• Poskytovatel softwaru musí mít buď prostředek Azure AI Face nebo prostředek Azure AI Services Multi-service.
• Klient musí mít prostředek Azure AI Face .

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 v reálném čase.

Očekávání odpovědnosti

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

Pokud ISV zjistí, že klient používá LimitedAccessToken pro neschválené účely, měl by dodavatel softwaru však přestat generovat tokeny pro tohoto zákazníka. Microsoft může sledovat vydávání a používání LimitedAccessTokens a vyhrazujeme si právo odebrat přístup ISV k API issueLimitedAccessToken, pokud se zneužití nevyřeší.

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 Face má následující formát:

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

Příklad:

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

Krok 2: IsV vygeneruje token

Cloudová služba nezávislého výrobce softwaru spuštěná v zabezpečeném prostředí volá issueLimitedAccessToken API pomocí známého ID prostředku Face koncového zákazníka.

Chcete-li zavolat API issueLimitedAccessToken, zkopírujte následující příkaz cURL do textového editoru.

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

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

1. Nahraďte <isv-endpoint> koncovým bodem zdroje 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 <isv-face-key> klíčem prostředku isV pro rozpoznávání tváře.
4. Nahraďte <subscription-id> ID 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 Face resource 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 pouze ta oprávnění, která mu byla udělena samotným Microsoftem. 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 odpověď 200 s tokenem ve formě JSON webového tokenu (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 služby Face API jménem klienta. Funguje to nezávisle na jiných ověřovacích mechanismech, takže nikdy nedochází k úniku osobních údajů klienta k nezávislému dodavateli softwaru.

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 na každém ISV, aby se rozhodlo, 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 Face key patří do prostředku Face klienta, nikoli do prostředku ISV. <token> je předáno jako hlavička 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 HttpPipelineSynchronousPolicy , 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 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}");
    }
}

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