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-funkció a meglévő Azure AI Services-jogkivonat-szolgáltatás 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.

Fontos

Ehhez a funkcióhoz csak azok az ISV-k férhetnek hozzá, amelyek megfelelnek a hozzáférési követelményeknek. Ha jóváhagyást szeretne kérni, lépjen kapcsolatba a () szolgáltatással azureface@microsoft.com

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ással vagy 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: <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"]  
}' 

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 <isv-face-key> az ISV 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 HttpPipelineSynchronousPolicy objektum létrehozásához, amely egy Face API-ügyfélobjektum 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 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}");
    }
}

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