Utiliser des jetons d’accès limité pour Visage

Les éditeurs de logiciels indépendants (ISV) peuvent gérer l’utilisation de l’API Visage de leurs clients en émettant des jetons d’accès qui accordent un accès aux fonctionnalités Visage qui sont normalement contrôlées. Cela permet à leurs entreprises clientes d’utiliser l’API Visage sans avoir à passer par le processus d’approbation formel.

Ce guide vous montre comment générer les jetons d’accès, si vous êtes un éditeur de logiciels indépendants approuvé, et comment utiliser les jetons si vous êtes client.

La fonctionnalité de jeton d’accès limité fait partie du service de jetons Azure AI services existant. Nous avons ajouté une nouvelle opération dans le but de contourner la porte d’accès limité pour des scénarios approuvés. Seuls les éditeurs de logiciels indépendants qui répondent aux exigences de contrôle ont accès à cette fonctionnalité.

Exemple de cas d’usage

Un exemple d’entreprise vend des logiciels qui utilisent le service Azure AI Visage pour faire fonctionner des systèmes de sécurité d’accès aux portes. Leurs clients, fabricants individuels d’appareils de porte, s’abonnent au logiciel et l’exécutent sur leurs appareils. Ces entreprises clientes souhaitent effectuer des appels à API Visage à partir de leurs appareils pour effectuer des opérations d’accès limité telles que l’identification de visages. En s’appuyant sur les jetons d’accès de l’éditeur de logiciels indépendants, elles peuvent contourner le processus d’approbation formel pour l’identification des visages. L’éditeur de logiciels indépendants, qui a déjà été approuvé, peut accorder au client des jetons d’accès juste-à-temps.

Attentes en matière de responsabilité

L’éditeur ISV émetteur de jetons est chargé de veiller à ce que les jetons soient utilisés uniquement dans le but approuvé.

Si l’éditeur de logiciels indépendants apprend qu’un client utilise LimitedAccessToken à des fins non approuvées, il doit cesser de générer des jetons pour ce client. Microsoft peut suivre l’émission et l’utilisation de LimitedAccessTokens et nous nous réservons le droit de révoquer l’accès d’un éditeur de logiciels indépendants à l’API issueLimitedAccessToken si l’abus n’est pas résolu.

Prérequis

• cURL est installé (ou un autre outil qui peut effectuer des requêtes HTTP).
• L’éditeur de logiciels indépendants doit disposer d’une ressource Azure AI Visage ou d’une ressource multiservice Azure AI services.
• Le client doit disposer d’une ressource Azure AI Visage.

Étape 1 : ISV obtient l’ID de ressource Visage du client

L’éditeur de logiciels indépendants doit configurer un canal de communication entre son propre service cloud sécurisé (qui générera le jeton d’accès) et son application s’exécutant sur l’appareil du client. L’ID de ressource Visage du client doit être connu avant de générer LimitedAccessToken.

L’ID de ressource Visage possède le format suivant :

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

Par exemple :

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

Étape 2 : l’éditeur de logiciels indépendants génère un jeton

Le service cloud de l’éditeur de logiciels indépendants, exécuté dans un environnement sécurisé, appelle l’API issueLimitedAccessToken en utilisant l’ID de ressource Visage connu de son client final.

Pour appeler l’API issueLimitedAccessToken, copiez la commande cURL suivante dans un éditeur de texte.

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

Ensuite, apportez les modifications suivantes :

1. Remplacez <isv-endpoint> par le point de terminaison de la ressource de l’éditeur de logiciels indépendants. Par exemple, westus.api.cognitive.microsoft.com.
2. Définissez éventuellement le paramètre expiredTime pour définir la durée d’expiration du jeton en secondes. Elle doit être comprise entre 60 et 86 400. La valeur par défaut est 3 600 (une heure(.
3. Remplacez <client-face-key> par la clé de la ressource Visage du client.
4. Remplacez <subscription-id> par l’ID d’abonnement de l’abonnement Azure du client.
5. Remplacez <resource-group-name> par le nom du groupe de ressources du client.
6. Remplacez <face-resource-name> par le nom de la ressource Visage du client.
7. Définissez "featureFlags" sur l’ensemble des rôles d’accès que vous souhaitez accorder. Les indicateurs disponibles sont "Face.Identification", "Face.Verification" et "LimitedAccess.HighRisk". Un éditeur de logiciels indépendants peut uniquement accorder des autorisations qui lui ont été accordées par Microsoft. Par exemple, si l’éditeur de logiciels indépendants a obtenu l’accès à l’identification de visage, il peut créer un LimitedAccessToken pour Face.Identification pour le client. Toutes les créations et utilisations de jetons sont journalisées à des fins d’utilisation et de sécurité.

Collez ensuite la commande dans une fenêtre de terminal et exécutez-la.

L’API doit retourner une réponse 200 avec le jeton sous la forme d’un jeton web JSON (application/jwt). Si vous souhaitez inspecter LimitedAccessToken, vous pouvez le faire à l’aide de JWT.

Étape 3 : l’application cliente utilise le jeton

L’application de l’éditeur ISV peut ensuite passer le jeton d’accès limité en tant qu’en-tête de requête HTTP pour les futures requêtes de l’API Visage pour le compte du client. Cela fonctionne indépendamment des autres mécanismes d’authentification, de sorte qu’aucune information personnelle du client n’est jamais divulguée à l’éditeur de logiciels indépendants.

Attention

Le client n’a pas besoin de connaître la valeur du jeton, car il peut être passé en arrière-plan. Si le client devait utiliser un outil de surveillance web pour intercepter le trafic, il serait en mesure d’afficher l’en-tête LimitedAccessToken. Toutefois, étant donné que le jeton expire après une courte période, il est limité dans ce qu’il peut effectuer. Ce risque est connu et considéré comme acceptable.

Il appartient à chaque éditeur de logiciels indépendants de décider exactement comment il transmet le jeton de son service cloud à l’application cliente.

REST API

Un exemple de requête de l’API Visage utilisant le jeton d’accès ressemble à ceci :

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

Notes

L’URL du point de terminaison et la clé Visage appartiennent à la ressource Visage du client, et non à la ressource de l’éditeur de logiciels indépendants. <token> est passé en tant qu’en-tête de requête HTTP.

C#

Les extraits de code suivants vous montrent comment utiliser un jeton d’accès avec le Kit de développement logiciel (SDK) Visage pour C#.

La classe suivante utilise un jeton d’accès pour créer un objet ServiceClientCredentials qui peut être utilisé pour authentifier un objet client d’API Visage. Il ajoute automatiquement le jeton d’accès en tant qu’en-tête dans chaque requête effectuée par le client Visage.

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

Dans l’application côté client, la classe d’assistance peut être utilisée comme dans cet exemple :

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

Étapes suivantes

• Référence de l’API LimitedAccessToken