Uso de tókenes de acceso limitados para Face

Los fabricantes independientes de software (ISV, por sus siglas en inglés) pueden administrar el uso de la API Face de sus clientes mediante la emisión de tókenes de acceso, que conceden acceso a las características de Face que suelen estar controladas. Esto permite a las empresas cliente usar la API Face sin tener que pasar por el proceso de aprobación formal.

Si usted es un ISV aprobado, esta guía le muestra cómo generar los tókenes de acceso; si es cliente, le muestra cómo usar los tókenes.

La característica de token de acceso limitado forma parte del servicio de token actual de Servicios de Azure AI. Hemos agregado una nueva operación con el fin de omitir la puerta de acceso limitado para los escenarios aprobados. Solo los ISV que superen los requisitos de acceso tendrán acceso a esta característica.

Ejemplo de caso de uso

Una empresa de ejemplo vende software que usa el servicio Face de Azure AI para operar sistemas de seguridad de acceso a puertas. Sus clientes, fabricantes individuales de dispositivos de puertas, se suscriben al software y lo ejecutan en sus dispositivos. Estas empresas cliente quieren realizar llamadas a la API Face desde sus dispositivos para realizar operaciones de acceso limitado, como la identificación facial. Al confiar en los tókenes de acceso del ISV, pueden omitir el proceso de aprobación formal para la identificación facial. Con la aprobación previa, el ISV puede conceder tókenes de acceso Just-In-Time al cliente.

Expectativa de responsabilidad

El ISV emisor de tókenes es responsable de garantizar que los tókenes solo se usen para el fin aprobado.

Si el ISV descubre que un cliente usa LimitedAccessToken con fines no aprobados, debe dejar de generar tókenes para ese cliente. Microsoft puede realizar un seguimiento de la emisión y el uso de LimitedAccessTokens, y nos reservamos el derecho de revocar el acceso de un ISV a la API issueLimitedAccessToken si no se soluciona el abuso.

Requisitos previos

• cURL instalado (u otra herramienta que pueda realizar solicitudes HTTP).
• El ISV necesita tener un recurso Azure AI Face o un recurso Multiservicio de servicios de Azure AI.
• El cliente necesita tener un recurso de Azure AI Face.

Paso 1: El ISV obtiene el identificador de recurso Face del cliente

El ISV debe configurar un canal de comunicación entre su propio servicio en la nube seguro (que generará el token de acceso) y su aplicación que se ejecuta en el dispositivo del cliente. Se debe conocer el identificador de recurso Face del cliente antes de generar LimitedAccessToken.

El identificador de recurso Face tiene el formato siguiente:

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

Por ejemplo:

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

Paso 2: El ISV genera un token

El servicio en la nube del ISV, que se ejecuta en un entorno seguro, llama a la API issueLimitedAccessToken mediante el identificador de recurso Face conocido del cliente final.

Para llamar a la API issueLimitedAccessToken, copie el siguiente comando cURL en un editor de texto.

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

Luego, realice los siguientes cambios:

1. Reemplace <isv-endpoint> por el punto de conexión del recurso del ISV. Por ejemplo, westus.api.cognitive.microsoft.com.
2. De manera opcional, establezca el parámetro expiredTime para establecer la hora de expiración del token en segundos. Debe estar entre 60 y 86 400. El valor predeterminado es 3600 (una hora).
3. Reemplace <client-face-key> por la clave del recurso Face del cliente.
4. Reemplace <subscription-id> por el identificador de suscripción de la suscripción de Azure del cliente.
5. Reemplace <resource-group-name> por el nombre del grupo de recursos del cliente.
6. Reemplace <face-resource-name> por el nombre del recurso Face del cliente.
7. Establezca "featureFlags" en el conjunto de roles de acceso que desea conceder. Las marcas disponibles son "Face.Identification", "Face.Verification" y "LimitedAccess.HighRisk". Un ISV solo puede conceder permisos concedidos por Microsoft. Por ejemplo, si se ha concedido acceso al ISV a la identificación facial, puede crear un LimitedAccessToken para Face.Identification para el cliente. Todas las creaciones y usos de tókenes se registran con fines de uso y seguridad.

Después, pegue el comando en una ventana de terminal y ejecútelo.

La API debe devolver una respuesta 200 con el token en forma de token web JSON (application/jwt). Si desea inspeccionar LimitedAccessToken, puede hacerlo mediante JWT.

Paso 3: La aplicación cliente usa el token

Luego, la aplicación del ISV puede pasar el token de acceso limitado como encabezado de solicitud HTTP para futuras solicitudes de la API de Face en nombre del cliente. Esto funciona independientemente de otros mecanismos de autenticación, por lo que nunca se filtra la información personal del cliente al ISV.

Precaución

El cliente no necesita tener en cuenta el valor del token, ya que se puede pasar en segundo plano. Si el cliente usara una herramienta de supervisión web para interceptar el tráfico, podría ver el encabezado LimitedAccessToken. Sin embargo, dado que el token expira después de un breve período de tiempo, está limitado respecto de lo que puede hacer con él. Este riesgo es conocido y se considera aceptable.

Depende de cada ISV decidir cómo pasa exactamente el token de su servicio en la nube a la aplicación cliente.

REST API

Una solicitud de API Face de ejemplo con el token de acceso tiene este aspecto:

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

Nota

La dirección URL del punto de conexión y la clave de Face pertenecen al recurso Face del cliente, no al recurso del ISV. <token> se pasa como un encabezado de solicitud HTTP.

C#

Los fragmentos de código siguientes muestran cómo usar un token de acceso con el SDK de Face para C#.

La siguiente clase usa un token de acceso para crear un objeto ServiceClientCredentials que se puede usar para autenticar un objeto de cliente de la API Face. Agrega automáticamente el token de acceso como un encabezado en cada solicitud que realizará el cliente de 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); 
    } 
} 

En la aplicación del lado cliente, la clase auxiliar se puede usar como en este ejemplo:

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