Verwenden von eingeschränkten Zugriffstoken für die Gesichtserkennung

Artikel
03/07/2024

Erfahren Sie, wie unabhängige Softwareanbieter (ISVs) die Nutzung der Gesichtserkennungs-API ihrer Clients verwalten können, indem sie Zugriffstoken ausgeben, die Zugriff auf Gesichtserkennungsfeatures erteilen, die normalerweise geschützt sind. Dadurch können ihre Clientunternehmen die Gesichtserkennungs-API verwenden, ohne den formalen Genehmigungsprozess durchlaufen zu müssen.

In diesem Leitfaden erfahren Sie, wie Sie die Zugriffstoken generieren, wenn Sie ein genehmigter ISV sind, und wie Sie die Token verwenden, wenn Sie ein Client sind.

Das Feature für eingeschränkte Zugriffstoken ist Teil des vorhandenen Azure KI Services-Tokendiensts. Wir haben einen neuen Vorgang hinzugefügt, mit dem das Gate für eingeschränkten Zugang für genehmigte Szenarien umgangen werden kann. Nur ISVs, die die Gatinganforderungen erfüllen, erhalten Zugriff auf dieses Feature.

Beispiel eines Anwendungsfalls

Ein Beispielunternehmen verkauft Software, die den Azure KI-Gesichtserkennungsdienst zum Betrieb von Sicherheitssystemen für Türzugänge verwendet. Seine Kunden, einzelne Hersteller von Türschließanlagen, abonnieren die Software und führen sie auf ihren Geräten aus. Diese Clientunternehmen möchten Aufrufe der Gesichtserkennungs-API von ihren Geräten aus vornehmen, um Vorgänge mit eingeschränktem Zugriff wie Gesichtserkennung auszuführen. Indem sie Zugriffstoken vom ISV nutzen, können sie den formalen Genehmigungsprozess für die Gesichtserkennung umgehen. Der ISV, der bereits genehmigt wurde, kann dem Client Just-in-Time-Zugriffstoken gewähren.

Erwartung der Zuständigkeit

Der tokenausstellende ISV ist dafür verantwortlich, sicherzustellen, dass die Token nur für den genehmigten Zweck verwendet werden.

Wenn der ISV erfährt, dass ein Client das LimitedAccessToken für nicht genehmigte Zwecke verwendet, sollte der ISV die Generierung von Token für diesen Kunden beenden. Microsoft kann die Ausstellung und Nutzung von LimitedAccessTokens nachverfolgen, und wir behalten uns das Recht vor, den Zugriff eines ISV auf die IssueLimitedAccessToken-API zu widerrufen, wenn der Missbrauch nicht abgestellt wird.

Voraussetzungen

cURL installiert (oder ein anderes Tool, das HTTP-Anforderungen ausgeben kann).
Der ISV muss entweder über eine Azure KI-Gesichtserkennungsressource oder eine Azure KI Services-Multi-Service-Ressource verfügen.
Der Client benötigt eine Ressource für die Azure KI-Gesichtserkennung.

Schritt 1: Der ISV ruft die Gesichtserkennungsressourcen-ID des Clients ab

Der ISV sollte einen Kommunikationskanal zwischen dem eigenen sicheren Clouddienst (der das Zugriffstoken generiert) und seiner Anwendung einrichten, die auf dem Gerät des Clients ausgeführt wird. Die Gesichtserkennungsressourcen-ID des Clients muss vor dem Generieren des LimitedAccessToken bekannt sein.

Die Gesichtserkennungsressourcen-ID hat das folgende Format:

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

Beispiel:

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

Schritt 2: Der ISV generiert ein Token

Der Clouddienst des ISV, der in einer sicheren Umgebung ausgeführt wird, ruft die issueLimitedAccessToken-API mithilfe der bekannten Gesichtserkennungsressourcen-ID des Endkunden auf.

Zum Aufrufen der issueLimitedAccessToken-API kopieren Sie den folgenden cURL-Befehl in einen Text-Editor.

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

Nehmen Sie dann folgende Änderungen vor:

Ersetzen Sie <isv-endpoint> durch den Endpunkt der Ressource des ISV. Beispielsweise westus.api.cognitive.microsoft.com.
Legen Sie optional den Parameter expiredTime fest, um die Ablaufzeit des Tokens in Sekunden anzugeben. Sie muss zwischen 60 und 86400 liegen. Der Standardwert beträgt 3600 (eine Stunde).
Ersetzen Sie <client-face-key> durch den Schlüssel der Gesichtserkennungsressource des Clients.
Ersetzen Sie <subscription-id> durch die Abonnement-ID des Azure-Abonnements des Clients.
Ersetzen Sie <resource-group-name> durch den Namen der Ressourcengruppe des Clients.
Ersetzen Sie <face-resource-name> durch den Namen der Gesichtserkennungsressource des Clients.
Legen Sie "featureFlags" auf die Gruppe der Zugriffsrollen fest, die Sie erteilen möchten. Die verfügbaren Flags sind "Face.Identification", "Face.Verification" und "LimitedAccess.HighRisk". Ein ISV kann nur Berechtigungen erteilen, die ihm von Microsoft erteilt wurden. Wenn dem ISV beispielsweise Zugriff auf die Gesichtserkennung erteilt wurde, kann er ein LimitedAccessToken für Face.Identification für den Client erstellen. Alle Tokenerstellungen und -verwendungen werden zu Nutzungs- und Sicherheitszwecken protokolliert.

Fügen Sie dann den Befehl in ein Terminalfenster ein, und führen Sie ihn aus.

Die API sollte eine 200-Antwort mit dem Token in Form eines JSON-Webtokens (application/jwt) zurückgeben. Wenn Sie den LimitedAccessToken überprüfen möchten, können Sie dies mithilfe von JWT tun.

Schritt 3: Die Clientanwendung verwendet das Token

Die Anwendung des ISV kann dann das eingeschränkte Zugriffstoken als HTTP-Anforderungsheader für zukünftige Gesichtserkennungs-API-Anforderungen im Auftrag des Clients übergeben. Dies funktioniert unabhängig von anderen Authentifizierungsmechanismen, sodass keine personenbezogenen Informationen des Clients an den ISV weitergegeben werden.

Achtung

Der Client muss den Tokenwert nicht kennen, da er im Hintergrund übergeben werden kann. Wenn der Client ein Webüberwachungstool verwenden würde, um den Datenverkehr abzufangen, könnte er den LimitedAccessToken-Header anzeigen. Da das Token jedoch nach kurzer Zeit abläuft, ist er eingeschränkt in Bezug auf das, was er damit tun kann. Dieses Risiko ist bekannt und wird als akzeptabel angesehen.

Jeder ISV muss entscheiden, wie genau er das Token von seinem Clouddienst an die Clientanwendung übergibt.

REST-API
C#

Eine Beispielanforderung für die Gesichtserkennungs-API mit dem Zugriffstoken sieht wie folgt aus:

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

Hinweis

Die Endpunkt-URL und der Gesichtserkennungsschlüssel gehören zur Gesichtserkennungsressource des Clients, nicht zur Ressource des ISV. Das <token> wird als HTTP-Anforderungsheader übergeben.

Die folgenden Codeschnipsel zeigen, wie Sie ein Zugriffstoken mit dem Face SDK für C# verwenden.

Die folgende Klasse verwendet ein Zugriffstoken, um ein ServiceClientCredentials-Objekt zu erstellen, das zum Authentifizieren eines Clientobjekts der Gesichtserkennungs-API verwendet werden kann. Sie fügt das Zugriffstoken automatisch als Header in jede Anforderung ein, die vom Gesichtserkennungsclient vorgenommen wird.

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

In der clientseitigen Anwendung kann die Hilfsklasse wie in diesem Beispiel verwendet werden:

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

Nächste Schritte

LimitedAccessToken-API-Referenz

Share via