Beperkte toegangstokens gebruiken voor Face

Onafhankelijke softwareleveranciers (ISV's) kunnen het Face-API-gebruik van hun clients beheren door toegangstokens uit te geven die toegang verlenen tot Face-functies die normaal gesproken worden gated. Hierdoor kunnen hun clientbedrijven de Face-API gebruiken zonder dat ze het formele goedkeuringsproces hoeven te doorlopen.

Deze handleiding laat zien hoe u de toegangstokens genereert, als u een goedgekeurde ISV bent en hoe u de tokens gebruikt als u een client bent.

De functie voor beperkte toegangstokens maakt deel uit van de bestaande Azure AI Services-tokenservice. We hebben een nieuwe bewerking toegevoegd voor het omzeilen van de beperkte toegangspoort voor goedgekeurde scenario's.

Belangrijk

Alleen ISV's die voldoen aan de gatvereisten krijgen toegang tot deze functie. Als u goedkeuring wilt aanvragen, neemt u contact op met azureface@microsoft.com.

Vereisten

• cURL geïnstalleerd (of een ander hulpprogramma dat HTTP-aanvragen kan indienen).
• De ISV moet beschikken over een Azure AI Face-resource of een Azure AI-services-resource voor meerdere services .
• De client moet een Azure AI Face-resource hebben.

Voorbeeld van een toepassing

Een voorbeeldbedrijf verkoopt software die gebruikmaakt van de Azure AI Face-service om toegangsbeveiligingssystemen voor deurtoegang te gebruiken. Hun klanten, individuele fabrikanten van deurapparaten, abonneren zich op de software en voeren deze uit op hun apparaten. Deze clientbedrijven willen Face-API-aanroepen uitvoeren vanaf hun apparaten om bewerkingen met beperkte toegang uit te voeren, zoals gezichtsidentificatie. Door te vertrouwen op toegangstokens van de ISV, kunnen ze het formele goedkeuringsproces voor gezichtsidentificatie omzeilen. De ISV, die al is goedgekeurd, kan de client Just-In-Time-toegangstokens verlenen.

Verwachting van verantwoordelijkheid

De tokenuitgevende ISV is verantwoordelijk voor het garanderen dat de tokens alleen worden gebruikt voor het goedgekeurde doel.

Als de ISV ontdekt dat een client het LimitedAccessToken gebruikt voor niet-goedgekeurde doeleinden, moet de ISV stoppen met het genereren van tokens voor die klant. Microsoft kan de uitgifte en het gebruik van LimitedAccessTokens bijhouden en we behouden ons het recht voor om de toegang van een ISV tot de issueLimitedAccessToken-API in te trekken als misbruik niet is opgelost.

Stap 1: ISV verkrijgt de Face-resource-id van de client

De ISV moet een communicatiekanaal instellen tussen hun eigen beveiligde cloudservice (waarmee het toegangstoken wordt gegenereerd) en hun toepassing die wordt uitgevoerd op het apparaat van de client. De Face-resource-id van de client moet bekend zijn voordat het LimitedAccessToken wordt gegenereerd.

De Face-resource-id heeft de volgende indeling:

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

Voorbeeld:

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

Stap 2: ISV genereert een token

De cloudservice van de ISV, die wordt uitgevoerd in een beveiligde omgeving, roept de issueLimitedAccessToken-API aan met behulp van de bekende Face-resource-id van de eindgebruiker.

Als u de issueLimitedAccessToken-API wilt aanroepen, kopieert u de volgende cURL-opdracht naar een teksteditor.

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

Breng vervolgens de volgende wijzigingen aan:

1. Vervang door <isv-endpoint> het eindpunt van de resource van de ISV. Bijvoorbeeld westus.api.cognitive.microsoft.com.
2. Stel desgewenst de expiredTime parameter in om de verlooptijd van het token in seconden in te stellen. Het moet tussen 60 en 86400 zijn. De standaardwaarde is 3600 (één uur).
3. Vervang door <isv-face-key> de sleutel van de Face-resource van de ISV.
4. Vervang door <subscription-id> de abonnements-id van het Azure-abonnement van de client.
5. Vervang door <resource-group-name> de naam van de resourcegroep van de client.
6. Vervang door <face-resource-name> de naam van de Face-resource van de client.
7. Stel "featureFlags" deze in op de set toegangsrollen die u wilt verlenen. De beschikbare vlaggen zijn "Face.Identification", "Face.Verification"en "LimitedAccess.HighRisk". Een ISV kan alleen machtigingen verlenen die deze zelf is verleend door Microsoft. Als de ISV bijvoorbeeld toegang heeft gekregen tot gezichtsidentificatie, kan deze een LimitedAccessToken maken voor Face.Identification voor de client. Alle tokencreaties en -toepassingen worden vastgelegd voor gebruiks- en beveiligingsdoeleinden.

Plak vervolgens de opdracht in een terminalvenster en voer deze uit.

De API moet een 200 antwoord retourneren met het token in de vorm van een JSON-webtoken (application/jwt). Als u het LimitedAccessToken wilt inspecteren, kunt u dit doen met behulp van JWT.

Stap 3: Clienttoepassing maakt gebruik van het token

De toepassing van de ISV kan vervolgens het beperkte toegangstoken doorgeven als een HTTP-aanvraagheader voor toekomstige Face-API-aanvragen namens de client. Dit werkt onafhankelijk van andere verificatiemechanismen, dus er worden nooit persoonlijke gegevens van de client gelekt naar de ISV.

Let op

De client hoeft zich niet bewust te zijn van de tokenwaarde, omdat deze op de achtergrond kan worden doorgegeven. Als de client een webbewakingsprogramma zou gebruiken om het verkeer te onderscheppen, kunnen ze de LimitedAccessToken-header bekijken. Omdat het token echter na een korte periode verloopt, zijn ze beperkt in wat ze ermee kunnen doen. Dit risico is bekend en wordt als acceptabel beschouwd.

Het is voor elke ISV om te bepalen hoe het token precies wordt doorgegeven van de cloudservice aan de clienttoepassing.

REST API

Een voorbeeld van een Face-API-aanvraag met behulp van het toegangstoken ziet er als volgt uit:

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

Notitie

De eindpunt-URL en de Face-sleutel behoren tot de Face-resource van de client, niet tot de resource van de ISV. De <token> aanvraag wordt doorgegeven als een HTTP-aanvraagheader.

C#

De volgende codefragmenten laten zien hoe u een toegangstoken gebruikt met de Face SDK voor C#.

In de volgende klasse wordt een toegangstoken gebruikt om een HttpPipelineSynchronousPolicy-object te maken dat kan worden gebruikt om een Face API-clientobject te verifiëren. Het toegangstoken wordt automatisch toegevoegd als een header in elke aanvraag die door de Face-client wordt gemaakt.

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

In de toepassing aan de clientzijde kan de helperklasse worden gebruikt, zoals in dit voorbeeld:

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