Use tokens de acesso limitado para o Face

Fornecedores independentes de software (ISVs) podem gerenciar o uso da API Face de seus clientes emitindo tokens de acesso que concedem acesso a recursos Face que normalmente são bloqueados. Isso permite que suas empresas clientes usem a API Face sem ter que 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 for um cliente.

O recurso de token de acesso limitado faz parte do serviço de token existente dos Serviços de IA do Azure. Adicionamos uma nova operação com a finalidade de contornar o portão de acesso limitado para cenários aprovados. Apenas ISVs que passarem nos requisitos de seleção terão acesso a esse recurso.

Exemplo de caso de uso

Uma empresa de exemplo vende software que usa o serviço Azure AI Face para operar sistemas de segurança de acesso a portas. Os seus clientes, fabricantes individuais de dispositivos de portas, subscrevem o software e executam-no nos seus dispositivos. Essas empresas clientes querem fazer chamadas de API Face de seus dispositivos para executar operações de Acesso Limitado, como identificação facial. Ao confiar em tokens de acesso do ISV, eles podem ignorar o processo de aprovação formal 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 tokens é responsável por garantir que os tokens sejam usados apenas para a finalidade aprovada.

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

Pré-requisitos

• cURL instalado (ou outra ferramenta que possa fazer solicitações HTTP).
• O ISV precisa ter um recurso Azure AI Face ou um recurso multisserviço de serviços de IA do Azure.
• O cliente precisa ter um recurso do Azure AI Face .

Etapa 1: ISV obtém o ID de recurso Face 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. O ID do recurso Face do cliente deve ser conhecido antes de gerar o LimitedAccessToken.

O ID do recurso Face 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: ISV gera um token

O serviço de nuvem do ISV, executado em um ambiente seguro, chama a API issueLimitedAccessToken usando o ID de recurso Face conhecido 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"]  
}' 

Em seguida, 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 expiredTime parâmetro para definir o tempo de expiração do token em segundos. Deve estar entre 60 e 86400. O valor padrão é 3600 (uma hora).
3. Substitua <client-face-key> pela chave do recurso Face do cliente.
4. Substitua <subscription-id> pela ID de assinatura da assinatura do Azure do cliente.
5. Substitua <resource-group-name> pelo nome do grupo de recursos do cliente.
6. Substitua <face-resource-name> pelo nome do recurso Face do cliente.
7. Defina "featureFlags" para o conjunto de funções de acesso que você deseja conceder. As bandeiras disponíveis são "Face.Identification", "Face.Verification"e "LimitedAccess.HighRisk". Um ISV só pode conceder permissões que ele próprio tenha sido concedido 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 utilizações de tokens são registadas para fins de utilização e segurança.

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

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

Etapa 3: O aplicativo cliente usa o token

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

Atenção

O cliente não precisa estar ciente do valor do token, pois ele pode ser passado em segundo plano. Se o cliente usasse uma ferramenta de monitoramento da Web para intercetar o tráfego, ele seria capaz de visualizar 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. Este risco é conhecido e considerado aceitável.

Cabe a cada ISV decidir exatamente como passa o token de seu serviço de nuvem para o aplicativo cliente.

API REST

Um exemplo de solicitação de API do Face 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  
}'

Nota

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

C#

Os trechos de código a seguir mostram como usar um token de acesso com o Face SDK para C#.

A classe a seguir usa um token de acesso para criar um objeto ServiceClientCredentials que pode ser usado para autenticar um objeto de cliente da API Face. Ele adiciona automaticamente o token de acesso como um cabeçalho em cada solicitação que o cliente Face 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://mytest-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)); 
    }
}