Menggunakan token akses terbatas untuk Face

Vendor perangkat lunak independen (ISV) dapat mengelola penggunaan Face API klien mereka dengan mengeluarkan token akses yang memberikan akses ke fitur Face yang biasanya terjaga. Ini memungkinkan perusahaan klien mereka untuk menggunakan Face API tanpa harus melalui proses persetujuan formal.

Panduan ini menunjukkan kepada Anda cara membuat token akses, jika Anda adalah ISV yang disetujui, dan cara menggunakan token jika Anda adalah klien.

Fitur token akses terbatas adalah bagian dari layanan token layanan Azure AI yang ada. Kami telah menambahkan operasi baru untuk tujuan melewati gerbang Akses Terbatas untuk skenario yang disetujui. Hanya ISV yang melewati persyaratan pembatasan yang akan diberikan akses ke fitur ini.

Contoh kasus penggunaan

Contoh perusahaan menjual perangkat lunak yang menggunakan layanan Azure AI Face untuk mengoperasikan sistem keamanan akses pintu. Klien mereka, produsen individu perangkat pintu, berlangganan perangkat lunak dan menjalankannya di perangkat mereka. Perusahaan klien ini ingin melakukan panggilan Face API dari perangkat mereka untuk melakukan operasi Akses Terbatas seperti identifikasi wajah. Dengan mengandalkan token akses dari ISV, mereka dapat melewati proses persetujuan formal untuk identifikasi wajah. ISV, yang telah disetujui, dapat memberikan token akses just-in-time klien.

Harapan tanggung jawab

ISV penerbit token bertanggung jawab untuk memastikan bahwa token hanya digunakan untuk tujuan yang disetujui.

Jika ISV mengetahui bahwa klien menggunakan LimitedAccessToken untuk tujuan yang tidak disetujui, ISV harus berhenti menghasilkan token untuk pelanggan tersebut. Microsoft dapat melacak penerbitan dan penggunaan LimitedAccessTokens, dan kami berhak untuk mencabut akses ISV ke API issueLimitedAccessToken jika penyalahgunaan tidak diatasi.

Prasyarat

• cURL diinstal (atau alat lain yang dapat membuat permintaan HTTP).
• ISV harus memiliki sumber daya Azure AI Face atau sumber daya multi-layanan layanan Azure AI.
• Klien harus memiliki sumber daya Azure AI Face .

Langkah 1: ISV mendapatkan ID sumber daya Face klien

ISV harus menyiapkan saluran komunikasi antara layanan cloud aman mereka sendiri (yang akan menghasilkan token akses) dan aplikasi mereka yang berjalan di perangkat klien. ID sumber daya Face klien harus diketahui sebelum membuat LimitedAccessToken.

ID sumber daya Face memiliki format berikut:

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

Contohnya:

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

Langkah 2: ISV menghasilkan token

Layanan cloud ISV, yang berjalan di lingkungan yang aman, memanggil ISSUELimitedAccessToken API menggunakan ID sumber daya Face yang diketahui pelanggan akhir mereka.

Untuk memanggil issueLimitedAccessToken API, salin perintah cURL berikut ke editor teks.

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

Kemudian, buat perubahan berikut:

1. Ganti <isv-endpoint> dengan titik akhir sumber daya ISV. Misalnya, westus.api.cognitive.microsoft.com.
2. Secara opsional atur expiredTime parameter untuk mengatur waktu kedaluwarsa token dalam hitungan detik. Harus antara 60 dan 86400. Nilai defaultnya adalah 3600 (satu jam).
3. Ganti <client-face-key> dengan kunci sumber daya Face klien.
4. Ganti <subscription-id> dengan ID langganan langganan Azure klien.
5. Ganti <resource-group-name> dengan nama grup sumber daya klien.
6. Ganti <face-resource-name> dengan nama sumber daya Face klien.
7. Atur "featureFlags" ke kumpulan peran akses yang ingin Anda berikan. Bendera yang tersedia adalah "Face.Identification", "Face.Verification", dan "LimitedAccess.HighRisk". ISV hanya dapat memberikan izin bahwa ISV telah diberikan sendiri oleh Microsoft. Misalnya, jika ISV telah diberikan akses ke identifikasi wajah, ISV dapat membuat LimitedAccessToken untuk Face.Identification untuk klien. Semua pembuatan dan penggunaan token dicatat untuk tujuan penggunaan dan keamanan.

Kemudian, tempelkan perintah ke jendela terminal dan jalankan.

API harus mengembalikan 200 respons dengan token dalam bentuk token web JSON (application/jwt). Jika Anda ingin memeriksa LimitedAccessToken, Anda dapat melakukannya menggunakan JWT.

Langkah 3: Aplikasi klien menggunakan token

Aplikasi ISV kemudian dapat meneruskan token akses terbatas sebagai header permintaan HTTP untuk permintaan Face API di masa mendatang atas nama klien. Ini bekerja secara independen dari mekanisme autentikasi lain, sehingga tidak ada informasi pribadi klien yang pernah bocor ke ISV.

Perhatian

Klien tidak perlu mengetahui nilai token, karena dapat diteruskan di latar belakang. Jika klien menggunakan alat pemantauan web untuk mencegat lalu lintas, mereka akan dapat melihat header LimitedAccessToken. Namun, karena token kedaluwarsa setelah waktu yang singkat, mereka terbatas pada apa yang dapat mereka lakukan dengannya. Risiko ini diketahui dan dianggap dapat diterima.

Ini untuk setiap ISV untuk memutuskan bagaimana tepatnya meneruskan token dari layanan cloud-nya ke aplikasi klien.

REST API

Contoh permintaan Face API menggunakan token akses terlihat seperti ini:

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

Catatan

URL titik akhir dan Kunci wajah milik sumber daya Face klien, bukan sumber daya ISV. diteruskan <token> sebagai header permintaan HTTP.

C#

Cuplikan kode berikut menunjukkan kepada Anda cara menggunakan token akses dengan Face SDK untuk C#.

Kelas berikut menggunakan token akses untuk membuat objek ServiceClientCredentials yang dapat digunakan untuk mengautentikasi objek klien Face API. Ini secara otomatis menambahkan token akses sebagai header di setiap permintaan yang akan dibuat klien Face.

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

Di aplikasi sisi klien, kelas pembantu dapat digunakan seperti dalam contoh ini:

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

Langkah berikutnya

• Referensi API LimitedAccessToken