Korlátozott hozzáférési jogkivonatok használata a Face-hoz

A független szoftvergyártók (ISV-k) kezelhetik ügyfeleik Face API-használatát olyan hozzáférési jogkivonatok kibocsátásával, amelyek hozzáférést biztosítanak a Face-funkciókhoz, amelyek általában kapuval vannak elzárva. Így az ügyfélvállalatok anélkül használhatják a Face API-t, hogy végig kellene menniük a hivatalos jóváhagyási folyamaton.

Ez az útmutató bemutatja, hogyan hozhatja létre a hozzáférési jogkivonatokat, ha Ön jóváhagyott ISV- és hogyan használhatja a jogkivonatokat ügyfélként.

A korlátozott hozzáférési jogkivonat-szolgáltatás a meglévő Azure AI-szolgáltatások jogkivonat-szolgáltatásának része. Új műveletet adtunk hozzá a korlátozott hozzáférésű kapu megkerülése céljából a jóváhagyott forgatókönyvek esetében. Ehhez a funkcióhoz csak azok az ISV-k férhetnek hozzá, amelyek megfelelnek a hozzáférési követelményeknek.

Példa használati esetre

Egy példavállalat olyan szoftvereket értékesít, amelyek az Azure AI Face szolgáltatást használják az ajtóhozzáférési biztonsági rendszerek üzemeltetésére. Ügyfeleik, az ajtóeszközök egyéni gyártói, feliratkoznak a szoftverre, és futtatják az eszközeiken. Ezek az ügyfélvállalatok face API-hívásokat szeretnének kezdeményezni az eszközeikről, hogy korlátozott hozzáférésű műveleteket hajtsanak végre, például arcfelismerést. Az ISV hozzáférési jogkivonataira támaszkodva megkerülhetik a hivatalos jóváhagyási folyamatot az arcfelismeréshez. A már jóváhagyott ISV képes az ügyfél számára az igény szerint hozzáférési jogkivonatokat biztosítani.

A felelősség elvárása

A jogkivonat-kiállító isv feladata annak biztosítása, hogy a jogkivonatok csak a jóváhagyott célra legyenek felhasználva.

Ha az ISV megtudja, hogy egy ügyfél nem jóváhagyott célokra használja a LimitedAccessTokent, az ISV-nek le kell állítania a jogkivonatok előállítását az adott ügyfél számára. A Microsoft nyomon tudja követni a LimitedAccessTokens kiállítását és használatát, és fenntartjuk a jogot, hogy visszavonjuk az ISV hozzáférését a problémalimitedAccessToken API-hoz, ha a visszaélést nem kezelik.

Előfeltételek

• a cURL telepítve van (vagy egy másik eszköz, amely HTTP-kéréseket tud küldeni).
• Az ISV-nek azure AI Face-erőforrássalvagy többszolgáltatásos Azure AI-szolgáltatással kell rendelkeznie.
• Az ügyfélnek rendelkeznie kell egy Azure AI Face-erőforrással .

1. lépés: Az ISV lekérte az ügyfél Face erőforrás-azonosítóját

Az ISV-nek létre kell hoznia egy kommunikációs csatornát a saját biztonságos felhőszolgáltatása (amely létrehozza a hozzáférési jogkivonatot) és az ügyfél eszközén futó alkalmazás között. A LimitedAccessToken létrehozása előtt ismernie kell az ügyfél Face erőforrás-azonosítóját.

A Face erőforrás-azonosító formátuma a következő:

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

Példa:

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

2. lépés: Az ISV létrehoz egy jogkivonatot

Az ISV felhőszolgáltatása, amely biztonságos környezetben fut, meghívja a ProblémaLimitedAccessToken API-t a végfelhasználó ismert Face-erőforrás-azonosítójával.

A ProblémaLimitedAccessToken API meghívásához másolja a következő cURL parancsot egy szövegszerkesztőbe.

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

Ezután végezze el a következő módosításokat:

1. Cserélje le <isv-endpoint> az ISV-erőforrás végpontjára. Például westus.api.cognitive.microsoft.com.
2. Ha szeretné, állítsa be a paramétert expiredTime a jogkivonat lejárati idejének másodpercben történő beállításához. Ennek 60 és 86400 közöttinek kell lennie. Az alapértelmezett érték 3600 (egy óra).
3. Cserélje le <client-face-key> az ügyfél Face-erőforrásának kulcsára.
4. Cserélje le <subscription-id> az ügyfél Azure-előfizetésének előfizetés-azonosítójára.
5. Cserélje le <resource-group-name> az ügyfél erőforráscsoportjának nevére.
6. Cserélje le <face-resource-name> az ügyfél Face erőforrásának nevére.
7. Állítsa be "featureFlags" a megadni kívánt hozzáférési szerepköröket. Az elérhető jelzők a következők "Face.Identification": , "Face.Verification"és "LimitedAccess.HighRisk". Az ISV csak olyan engedélyeket adhat meg, amelyeket a Microsoft adott magának. Ha például az ISV hozzáférést kapott az arcazonosításhoz, létrehozhat egy LimitedAccessTokent a Face.Identification számára az ügyfél számára. A rendszer minden jogkivonat-létrehozást és -felhasználást naplóz használati és biztonsági célokra.

Ezután illessze be a parancsot egy terminálablakba, és futtassa.

Az API-nak JSON webes jogkivonatapplication/jwt () formájában kell visszaadnia 200 a jogkivonattal rendelkező választ. Ha meg szeretné vizsgálni a LimitedAccessTokent, ezt a JWT használatával teheti meg.

3. lépés: Az ügyfélalkalmazás a jogkivonatot használja

Az ISV-alkalmazás ezután az ügyfél nevében továbbíthatja a korlátozott hozzáférési jogkivonatot HTTP-kérés fejléceként a jövőbeli Face API-kérésekhez. Ez más hitelesítési mechanizmusoktól függetlenül működik, így az ügyfél személyes adatai soha nem szivárognak ki az ISV-be.

Figyelemfelhívás

Az ügyfélnek nem kell tisztában lennie a jogkivonat értékével, mivel a háttérben átadható. Ha az ügyfél egy webes monitorozási eszközt használ a forgalom elfogásához, megtekintheti a LimitedAccessToken fejlécet. Mivel azonban a jogkivonat rövid idő elteltével lejár, korlátozott mértékben tudják elvégezni a vele kapcsolatos műveleteket. Ez a kockázat ismert és elfogadhatónak tekinthető.

Minden isV-nek el kell döntenie, hogy pontosan hogyan továbbítja a jogkivonatot a felhőszolgáltatásból az ügyfélalkalmazásnak.

REST API

Egy példa Face API-kérés a hozzáférési jogkivonat használatával a következőképpen néz ki:

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

Feljegyzés

A végpont URL-címe és a Face-kulcs az ügyfél Face-erőforrásához tartozik, nem pedig az ISV erőforrásához. Az <token> átadás HTTP-kérelemfejlécként történik.

C#

Az alábbi kódrészletek bemutatják, hogyan használhat hozzáférési jogkivonatot a C#-hoz készült Face SDK-val.

Az alábbi osztály egy hozzáférési jogkivonatot használ egy ServiceClientCredentials-objektum létrehozásához, amely a Face API-ügyfélobjektumok hitelesítésére használható. Automatikusan hozzáadja a hozzáférési jogkivonatot fejlécként minden olyan kéréshez, amelyet a Face-ügyfél létrehoz.

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

Az ügyféloldali alkalmazásban a segédosztály az alábbi példához hasonlóan használható:

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

Következő lépések

• LimitedAccessToken API-referencia