Usar tokens de acesso limitado para Detecção Facial

Os ISVs (fornecedores independentes de software) podem gerenciar o uso da API de Detecção Facial de seus clientes emitindo tokens que concedem acesso aos recursos de Detecção Facial que normalmente são fechados. Isso permite que as empresas cliente usem a API de Detecção Facial sem precisar passar pelo processo de aprovação formal.

Este guia mostra como gerar os tokens de acesso, se você for um ISV aprovado e como usar os tokens se você for um cliente.

O recurso de token de acesso limitado faz parte do serviço de token de serviços de IA do Azure existente. Adicionamos uma nova operação com a finalidade de ignorar o portão de Acesso Limitado para cenários aprovados. Somente os ISVs que passarem pelos requisitos de gating terão acesso a esse recurso.

Caso de uso de exemplo

Um exemplo de empresa que vende um software que usa o serviço de Detecção Facial por IA do Azure para operar sistemas de segurança de acesso a portas. Seus clientes, fabricantes individuais de dispositivos de porta, assinam o software e o executam em seus dispositivos. Essas empresas cliente desejam fazer chamadas à API de Detecção Facial de seus dispositivos para executar operações de Acesso Limitado, como identificação facial. Ao depender de tokens de acesso do ISV, elas podem ignorar o processo formal de aprovação para identificação facial. O ISV que já foi aprovado pode conceder ao cliente tokens de acesso just-in-time.

Expectativa de responsabilidade

O ISV emissor de token é responsável por garantir que os tokens sejam utilizados somente para a finalidade aprovada.

Se o ISV souber que um cliente está usando o LimitedAccessToken para fins não aprovados, ele deve parar de gerar tokens para esse cliente. A Microsoft pode acompanhar a emissão e o uso de LimitedAccessTokens e reservamos o direito de revogar o acesso de um ISV à API issueLimitedAccessToken se o abuso não for resolvido.

Pré-requisitos

• cURL instalado (ou outra ferramenta que pode fazer solicitações HTTP).
• O ISV precisa ter um recurso de Detecção Facial de IA do Azure ou um recurso de vários serviços de IA do Azure.
• O cliente precisa ter um recurso Detecção Facial de IA do Azure.

Etapa 1: o ISV obtém a ID do recurso de Detecção Facial do cliente

O ISV deve configurar um canal de comunicação entre seu próprio serviço de nuvem segura (que gerará o token de acesso) e seu aplicativo em execução no dispositivo do cliente. A ID do recurso de Detecção Facial do cliente deve ser conhecida antes de gerar o LimitedAccessToken.

A ID do recurso de Detecção Facial tem o seguinte formato:

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

Por exemplo:

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

Etapa 2: o ISV gera um token

O serviço de nuvem do ISV, em execução em um ambiente seguro, chama a API issueLimitedAccessToken usando a ID de recurso de Detecção Facial conhecida do cliente final.

Para chamar a API issueLimitedAccessToken, copie o seguinte comando cURL para um 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"]  
}' 

Depois, faça as seguintes alterações:

1. Substitua <isv-endpoint> pelo ponto de extremidade do recurso do ISV. Por exemplo, westus.api.cognitive.microsoft.com.
2. Opcionalmente, defina o parâmetro expiredTime para definir o tempo de expiração do token em segundos. Ele precisa estar entre 60 e 86400. O valor padrão é 3600 (uma hora).
3. Substitua <client-face-key> pela chave do recurso de Detecção Facial do cliente.
4. Substitua <subscription-id> pela ID da assinatura do cliente do Azure.
5. Substitua <resource-group-name> pelo nome do grupo de recursos do cliente.
6. Substitua <face-resource-name> pelo nome do recurso de Detecção Facial do cliente.
7. Defina "featureFlags" como o conjunto de funções de acesso que você deseja conceder. Os sinalizadores disponíveis são "Face.Identification", "Face.Verification"e "LimitedAccess.HighRisk". Um ISV só pode conceder permissões concedidas pela Microsoft. Por exemplo, se o ISV tiver recebido acesso à identificação facial, ele poderá criar um LimitedAccessToken para Face.Identification para o cliente. Todas as criações e usos de token são registrados para fins de uso e segurança.

Em seguida, cole o comando em uma janela do terminal e execute-o.

A API deve retornar uma resposta 200 com o token na forma de um token Web JSON (application/jwt). Se você quiser inspecionar o LimitedAccessToken, poderá fazer isso usando JWT.

Etapa 3: o aplicativo cliente usa o token

O aplicativo ISV pode, então, passar o token de acesso limitado como um cabeçalho de solicitação HTTP para futuras solicitações da API de Detecção Facial em nome do cliente. Isso funciona independentemente de outros mecanismos de autenticação, portanto, nenhuma informação pessoal do cliente é vazada para o ISV.

Cuidado

O cliente não precisa estar ciente do valor do token, pois ele pode ser passado em segundo plano. Se o cliente usar uma ferramenta de monitoramento da Web para interceptar o tráfego, ele poderá exibir o cabeçalho LimitedAccessToken. No entanto, como o token expira após um curto período de tempo, eles são limitados no que podem fazer com ele. Esse risco é conhecido e considerado aceitável.

Cada ISV decide como exatamente ele passa o token de seu serviço de nuvem para o aplicativo cliente.

REST API

Um exemplo de solicitação de API de Detecção Facial usando o token de acesso tem esta aparência:

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

Observação

A URL do ponto de extremidade e a chave facial pertencem ao recurso de Detecção Facial do cliente, não ao recurso do ISV. O <token> é passado como um cabeçalho de solicitação HTTP.

C#

Os snippets de código a seguir mostram como usar um token de acesso com o SDK de Detecção Facial para C#.

A classe a seguir usa um token de acesso para criar um objeto ServiceClientCredentials que pode ser usado para autenticar um objeto cliente da API de Detecção Facial. Ele adiciona automaticamente o token de acesso como um cabeçalho em cada solicitação que o cliente de Detecção Facial fará.

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

No aplicativo do lado do cliente, a classe auxiliar pode ser usada como neste exemplo:

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

Próximas etapas

• Referência da API LimitedAccessToken