Использование маркеров ограниченного доступа для Face

Независимые поставщики программного обеспечения (НЕЗАВИСИМЫе поставщики программного обеспечения) могут управлять использованием API распознавания лиц своих клиентов, выдавая маркеры доступа, предоставляющие доступ к функциям распознавания лиц, которые обычно включены. Это позволяет своим клиентам использовать API распознавания лиц без необходимости пройти формальный процесс утверждения.

В этом руководстве показано, как создать маркеры доступа, если вы являетесь утвержденным isV, и как использовать маркеры, если вы являетесь клиентом.

Функция маркера ограниченного доступа является частью существующей службы маркеров служб искусственного интеллекта Azure. Мы добавили новую операцию для обхода шлюза ограниченного доступа для утвержденных сценариев. Только поставщики программного обеспечения, которые передают требования к выбору, получат доступ к этой функции.

Примеры использования

Пример компании продает программное обеспечение, которое использует службу распознавания лиц Azure для управления системами безопасности доступа к двери. Их клиенты, отдельные производители устройств двери, подписываться на программное обеспечение и запускать его на своих устройствах. Эти клиентские компании хотят совершать вызовы API распознавания лиц с своих устройств для выполнения операций ограниченного доступа, таких как идентификация лиц. Используя маркеры доступа из поставщика программного обеспечения, они могут обойти формальный процесс утверждения для идентификации лиц. IsV, который уже утвержден, может предоставить клиенту маркеры доступа jit-time.

Ожидание ответственности

Поставщик программного обеспечения, выдавающий токен, отвечает за обеспечение того, чтобы маркеры использовались только для утвержденной цели.

Если isV узнает, что клиент использует LimitedAccessToken для не утвержденных целей, isV должен прекратить создание маркеров для этого клиента. Корпорация Майкрософт может отслеживать выдачу и использование LimitedAccessTokens, и мы зарезервируем право отозвать доступ поставщика программного обеспечения к API issueLimitedAccessToken , если злоупотребление не устранено.

Необходимые компоненты

• cURL установлен (или другой инструмент, который может выполнять HTTP-запросы).
• Поставщик программного обеспечения должен иметь ресурс Azure AI Face или ресурс нескольких служб ИИ Azure.
• Клиент должен иметь ресурс распознавания лиц Azure AI.

Шаг 1. Поставщик программного обеспечения получает идентификатор ресурса распознавания лиц клиента

Поставщик программного обеспечения должен настроить канал связи между собственной защищенной облачной службой (которая создаст маркер доступа) и приложением, работающим на устройстве клиента. Идентификатор ресурса распознавания лиц клиента должен быть известен до создания LimitedAccessToken.

Идентификатор ресурса распознавания лиц имеет следующий формат:

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

Например:

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

Шаг 2. Поставщик программного обеспечения создает токен

Облачная служба isV, запущенная в безопасной среде, вызывает API issueLimitedAccessToken с помощью известного идентификатора ресурса распознавания лиц клиента.

Чтобы вызвать API issueLimitedAccessToken , скопируйте следующую команду cURL в текстовый редактор.

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

Затем внесите следующие изменения:

1. Замените <isv-endpoint> конечной точкой ресурса поставщика программного обеспечения. Например, westus.api.cognitive.microsoft.com.
2. При необходимости задайте expiredTime параметр, чтобы задать время окончания срока действия маркера в секундах. Оно должно быть от 60 до 86400. Значение по умолчанию — 3600 (один час).
3. Замените <client-face-key> ключом ресурса распознавания лиц клиента.
4. Замените <subscription-id> идентификатор подписки клиента на подписку Azure.
5. Замените <resource-group-name> именем группы ресурсов клиента.
6. Замените <face-resource-name> именем ресурса распознавания лиц клиента.
7. Задайте "featureFlags" для набора ролей доступа, которые требуется предоставить. Доступные флаги: "Face.Identification"и "Face.Verification""LimitedAccess.HighRisk". IsV может предоставлять только разрешения, предоставленные корпорацией Майкрософт. Например, если isV предоставлен доступ к идентификации лиц, он может создать LimitedAccessToken для Face.Identification для клиента. Все создания и использование маркеров регистрируются в целях использования и безопасности.

Затем вставьте команду в окно терминала и запустите ее.

API должен возвращать 200 ответ с маркером в виде веб-маркера JSON (application/jwt). Если вы хотите проверить LimitedAccessToken, это можно сделать с помощью JWT.

Шаг 3. Клиентское приложение использует маркер

Затем приложение поставщика программного обеспечения может передать маркер ограниченного доступа в качестве заголовка HTTP-запроса для будущих запросов API распознавания лиц от имени клиента. Это работает независимо от других механизмов проверки подлинности, поэтому личная информация клиента никогда не утечка в isV.

Внимание

Клиенту не нужно знать значение токена, так как его можно передать в фоновом режиме. Если клиент должен был использовать средство веб-мониторинга для перехвата трафика, он сможет просмотреть заголовок LimitedAccessToken. Однако, поскольку срок действия маркера истекает через короткий период времени, они ограничены тем, что они могут сделать с ним. Этот риск известен и считается приемлемым.

Это для каждого поставщика программного обеспечения, чтобы решить, как именно он передает маркер из облачной службы в клиентское приложение.

REST API

Пример запроса API распознавания лиц с помощью маркера доступа выглядит следующим образом:

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

Примечание.

URL-адрес конечной точки и ключ распознавания лиц относятся к ресурсу распознавания лиц клиента, а не к ресурсу поставщика программного обеспечения. Передается <token> в виде заголовка HTTP-запроса.

C#

В следующих фрагментах кода показано, как использовать маркер доступа с пакетом SDK распознавания лиц для C#.

Следующий класс использует маркер доступа для создания объекта ServiceClientCredentials , который можно использовать для проверки подлинности клиентского объекта API распознавания лиц. Он автоматически добавляет маркер доступа в качестве заголовка в каждом запросе, который будет выполнять клиент 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); 
    } 
} 

В клиентском приложении вспомогательный класс можно использовать, как в следующем примере:

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

Следующие шаги

• Справочник по API LimitedAccessToken