Använda token för begränsad åtkomst för Ansiktsigenkänning

Artikel
10/25/2024

Oberoende programvaruleverantörer kan hantera användningen av ansikts-API:et för sina klienter genom att utfärda åtkomsttoken som ger åtkomst till ansiktsfunktioner som normalt är gated. Detta gör att deras klientföretag kan använda ansikts-API:et utan att behöva gå igenom den formella godkännandeprocessen.

Den här guiden visar hur du genererar åtkomsttoken, om du är en godkänd ISV och hur du använder tokens om du är en klient.

Funktionen för begränsad åtkomsttoken är en del av den befintliga Azure AI Services-tokentjänsten. Vi har lagt till en ny åtgärd i syfte att kringgå gaten för begränsad åtkomst för godkända scenarier.

Viktigt!

Endast ISV:er som uppfyller gating-kraven får åtkomst till den här funktionen. Kontakta om du vill begära godkännande azureface@microsoft.com.

Exempel på användningsfall

Ett exempelföretag säljer programvara som använder Azure AI Face-tjänsten för att använda säkerhetssystem för dörråtkomst. Deras kunder, enskilda tillverkare av dörrenheter, prenumererar på programvaran och kör den på sina enheter. Dessa klientföretag vill göra ansikts-API-anrop från sina enheter för att utföra begränsade åtkomståtgärder som ansiktsidentifiering. Genom att förlita sig på åtkomsttoken från ISV kan de kringgå den formella godkännandeprocessen för ansiktsidentifiering. ISV, som redan har godkänts, kan bevilja klienten just-in-time-åtkomsttoken.

Förväntningar på ansvar

Den tokenutfärdande ISV:en ansvarar för att säkerställa att token endast används för det godkända ändamålet.

Om ISV får veta att en klient använder LimitedAccessToken för icke-godkända ändamål bör ISV sluta generera token för den kunden. Microsoft kan spåra utfärdande och användning av LimitedAccessTokens och vi förbehåller oss rätten att återkalla en ISV-åtkomst till problemetLimitedAccessToken API om missbruk inte åtgärdas.

Förutsättningar

cURL installerat (eller ett annat verktyg som kan göra HTTP-begäranden).
ISV måste ha antingen en Azure AI Face-resurs eller en Azure AI-tjänstresurs med flera tjänster .
Klienten måste ha en Azure AI Face-resurs .

Steg 1: ISV hämtar klientens ansiktsresurs-ID

ISV:n bör konfigurera en kommunikationskanal mellan sin egen säkra molntjänst (som genererar åtkomsttoken) och deras program som körs på klientens enhet. Klientens ansiktsresurs-ID måste vara känt innan du genererar LimitedAccessToken.

Ansiktsresurs-ID:t har följande format:

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

Till exempel:

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

Steg 2: ISV genererar en token

ISV:ns molntjänst, som körs i en säker miljö, anropar problemetLimitedAccessToken API med hjälp av slutkundens kända ansiktsresurs-ID.

Om du vill anropa issueLimitedAccessToken API kopierar du följande cURL-kommando till en textredigerare.

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

Gör sedan följande ändringar:

Ersätt <isv-endpoint> med slutpunkten för ISV-resursen. Till exempel westus.api.cognitive.microsoft.com.
Du kan också ange parametern expiredTime för att ange förfallotiden för token i sekunder. Det måste vara mellan 60 och 86400. Standardvärdet är 3600 (en timme).
Ersätt <isv-face-key> med nyckeln för ISV:s Ansiktsresurs.
Ersätt <subscription-id> med prenumerations-ID:t för klientens Azure-prenumeration.
Ersätt <resource-group-name> med namnet på klientens resursgrupp.
Ersätt <face-resource-name> med namnet på klientens ansiktsresurs.
Ange "featureFlags" till den uppsättning åtkomstroller som du vill bevilja. De tillgängliga flaggorna är "Face.Identification", "Face.Verification"och "LimitedAccess.HighRisk". En ISV kan endast bevilja behörigheter som den har beviljats av Microsoft. Om till exempel ISV:en har beviljats åtkomst till ansiktsidentifiering kan den skapa en LimitedAccessToken för Face.Identification för klienten. Alla tokenskapanden och användningar loggas i användnings- och säkerhetssyfte.

Klistra sedan in kommandot i ett terminalfönster och kör det.

API:et bör returnera ett 200 svar med token i form av en JSON-webbtoken (application/jwt). Om du vill inspektera LimitedAccessToken kan du göra det med JWT.

Steg 3: Klientprogrammet använder token

ISV:ns program kan sedan skicka den begränsade åtkomsttoken som ett HTTP-begärandehuvud för framtida Ansikts-API-begäranden för klientens räkning. Detta fungerar oberoende av andra autentiseringsmekanismer, så ingen personlig information om klientens läcker någonsin till ISV.

Varning

Klienten behöver inte vara medveten om tokenvärdet eftersom det kan skickas i bakgrunden. Om klienten skulle använda ett webbövervakningsverktyg för att fånga upp trafiken skulle de kunna visa huvudet LimitedAccessToken. Men eftersom token upphör att gälla efter en kort tidsperiod är de begränsade i vad de kan göra med den. Den här risken är känd och anses acceptabel.

Det är upp till varje ISV att bestämma exakt hur den skickar token från molntjänsten till klientprogrammet.

REST-API
C#

Ett exempel på en ansikts-API-begäran med hjälp av åtkomsttoken ser ut så här:

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

Kommentar

Slutpunkts-URL:en och ansiktsnyckeln tillhör klientens Ansiktsresurs, inte ISV-resursen. <token> Skickas som ett HTTP-begärandehuvud.

Följande kodfragment visar hur du använder en åtkomsttoken med Face SDK för C#.

I följande klass används en åtkomsttoken för att skapa ett HttpPipelineSynchronousPolicy-objekt som kan användas för att autentisera ett ansikts-API-klientobjekt. Den lägger automatiskt till åtkomsttoken som en rubrik i varje begäran som ansiktsklienten kommer att göra.

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

I programmet på klientsidan kan hjälpklassen användas som i det här exemplet:

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

Dela via