Używanie ograniczonych tokenów dostępu na potrzeby rozpoznawania twarzy

Niezależni dostawcy oprogramowania (ISV) mogą zarządzać użyciem interfejsu API rozpoznawania twarzy swoich klientów, wystawiając tokeny dostępu, które udzielają dostępu do funkcji rozpoznawania twarzy, które są zwykle bramowane. Dzięki temu ich firmy klienckie mogą korzystać z interfejsu API rozpoznawania twarzy bez konieczności wykonywania formalnego procesu zatwierdzania.

W tym przewodniku pokazano, jak wygenerować tokeny dostępu, jeśli jesteś zatwierdzonym dostawcą oprogramowania i jak używać tokenów, jeśli jesteś klientem.

Funkcja ograniczonego tokenu dostępu jest częścią istniejącej usługi tokenu usług Azure AI Services. Dodaliśmy nową operację w celu pomijania bramy ograniczonego dostępu dla zatwierdzonych scenariuszy. Tylko niezależnych dostawców oprogramowania, które spełniają wymagania dotyczące gating, będą mieć dostęp do tej funkcji.

Przykładowy przypadek użycia

Przykładowa firma sprzedaje oprogramowanie korzystające z usługi Rozpoznawanie twarzy platformy Azure w celu obsługi systemów zabezpieczeń dostępu do drzwi. Ich klienci, indywidualni producenci urządzeń drzwiowych, subskrybują oprogramowanie i uruchamiają je na swoich urządzeniach. Te firmy klienckie chcą wykonywać wywołania interfejsu API rozpoznawania twarzy z urządzeń, aby wykonywać operacje ograniczonego dostępu, takie jak identyfikacja twarzy. Korzystając z tokenów dostępu od niezależnego dostawcy oprogramowania, mogą pominąć formalny proces zatwierdzania na potrzeby identyfikacji twarzy. Niezależnego dostawcy oprogramowania, który został już zatwierdzony, może udzielić klientowi tokenów dostępu just in time.

Oczekiwanie na odpowiedzialność

Niezależnego dostawcy oprogramowania wystawiającego tokeny odpowiada za zapewnienie, że tokeny są używane tylko do zatwierdzonego celu.

Jeśli niezależnego dostawcy oprogramowania dowiesz się, że klient używa tokenu LimitedAccessToken do celów niezatwierdzonych, niezależnego dostawcy oprogramowania powinien przestać generować tokeny dla tego klienta. Firma Microsoft może śledzić wystawianie i użycie funkcji LimitedAccessTokens, a my zastrzegamy sobie prawo do odwołania dostępu niezależnego dostawcy oprogramowania do problemuLimitedAccessToken API, jeśli nadużycie nie zostało rozwiązane.

Wymagania wstępne

• Zainstalowano bibliotekę cURL (lub inne narzędzie, które może wysyłać żądania HTTP).
• Niezależnego dostawcy oprogramowania musi mieć zasób rozpoznawania twarzy platformy Azure lub zasób wielosługi usług Azure AI.
• Klient musi mieć zasób rozpoznawania twarzy w usłudze Azure AI .

Krok 1. Dostawca oprogramowania uzyskuje identyfikator zasobu rozpoznawania twarzy klienta

Niezależnego dostawcy oprogramowania powinien skonfigurować kanał komunikacyjny między własną bezpieczną usługą w chmurze (która wygeneruje token dostępu) i aplikacją działającą na urządzeniu klienta. Identyfikator zasobu rozpoznawania twarzy klienta musi być znany przed wygenerowaniem tokenu LimitedAccessToken.

Identyfikator zasobu rozpoznawania twarzy ma następujący format:

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

Na przykład:

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

Krok 2. Generowanie tokenu przez niezależnego dostawcę oprogramowania

Usługa w chmurze niezależnego dostawcy oprogramowania, działająca w bezpiecznym środowisku, wywołuje interfejs API IssueLimitedAccessToken przy użyciu znanego identyfikatora zasobu rozpoznawania twarzy klienta końcowego.

Aby wywołać problemLimitedAccessToken API, skopiuj następujące polecenie cURL do edytora tekstów.

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

Następnie wprowadź następujące zmiany:

1. Zastąp <isv-endpoint> element punktem końcowym zasobu niezależnego dostawcy oprogramowania. Na przykład westus.api.cognitive.microsoft.com.
2. Opcjonalnie ustaw parametr , expiredTime aby ustawić czas wygaśnięcia tokenu w sekundach. Musi należeć do przedziału od 60 do 86400. Wartość domyślna to 3600 (jedna godzina).
3. Zastąp <client-face-key> ciąg kluczem zasobu rozpoznawania twarzy klienta.
4. Zastąp element <subscription-id> identyfikatorem subskrypcji platformy Azure klienta.
5. Zastąp <resource-group-name> ciąg nazwą grupy zasobów klienta.
6. Zastąp <face-resource-name> ciąg nazwą zasobu rozpoznawania twarzy klienta.
7. Ustaw "featureFlags" zestaw ról dostępu, które chcesz udzielić. Dostępne flagi to "Face.Identification", "Face.Verification"i "LimitedAccess.HighRisk". Niezależnego dostawcy oprogramowania może udzielać tylko uprawnień, które zostały mu przyznane przez firmę Microsoft. Jeśli na przykład niezależnych dostawców oprogramowania udzielono dostępu do identyfikacji twarzy, może utworzyć element LimitedAccessToken dla aplikacji Face.Identification dla klienta. Wszystkie tworzenie i używanie tokenów są rejestrowane w celach użycia i zabezpieczeń.

Następnie wklej polecenie w oknie terminalu i uruchom je.

Interfejs API powinien zwrócić 200 odpowiedź z tokenem w postaci tokenu internetowego JSON (application/jwt). Jeśli chcesz sprawdzić token LimitedAccessToken, możesz to zrobić przy użyciu JWT.

Krok 3. Aplikacja kliencka używa tokenu

Aplikacja niezależnego dostawcy oprogramowania może następnie przekazać ograniczony token dostępu jako nagłówek żądania HTTP dla przyszłych żądań interfejsu API rozpoznawania twarzy w imieniu klienta. Działa to niezależnie od innych mechanizmów uwierzytelniania, więc żadne dane osobowe klienta nigdy nie wyciekły do niezależnego dostawcy oprogramowania.

Uwaga

Klient nie musi mieć informacji o wartości tokenu, ponieważ może zostać przekazany w tle. Gdyby klient używał narzędzia do monitorowania sieci Web do przechwytywania ruchu, będzie mógł wyświetlić nagłówek LimitedAccessToken. Jednak ponieważ token wygasa po krótkim czasie, są one ograniczone do tego, co mogą z nim zrobić. To ryzyko jest znane i uznawane za dopuszczalne.

Jest przeznaczony dla każdego niezależnego dostawcy oprogramowania, aby zdecydować, jak dokładnie przekazuje token z usługi w chmurze do aplikacji klienckiej.

Interfejs API REST

Przykładowe żądanie interfejsu API rozpoznawania twarzy przy użyciu tokenu dostępu wygląda następująco:

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

Uwaga

Adres URL punktu końcowego i klucz rozpoznawania twarzy należą do zasobu rozpoznawania twarzy klienta, a nie do zasobu niezależnego dostawcy oprogramowania. Element <token> jest przekazywany jako nagłówek żądania HTTP.

C#

Poniższe fragmenty kodu pokazują, jak używać tokenu dostępu z zestawem SDK rozpoznawania twarzy dla języka C#.

Poniższa klasa używa tokenu dostępu do tworzenia obiektu ServiceClientCredentials , który może służyć do uwierzytelniania obiektu klienta interfejsu API rozpoznawania twarzy. Automatycznie dodaje token dostępu jako nagłówek w każdym żądaniu, które zostanie wykonane przez klienta rozpoznawania twarzy.

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

W aplikacji po stronie klienta klasę pomocnika można użyć w następujący przykład:

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

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