Face에 제한된 액세스 토큰 사용

ISV(독립 소프트웨어 공급업체)는 일반적으로 제한되는 얼굴 특징에 대한 액세스 권한을 부여하는 액세스 토큰을 발행하여 클라이언트의 Face API 사용을 관리할 수 있습니다. 이를 통해 클라이언트 회사는 공식적인 승인 프로세스를 거치지 않고도 Face API를 사용할 수 있습니다.

이 가이드에서는 승인된 ISV인 경우 액세스 토큰을 생성하는 방법과 클라이언트인 경우 토큰을 사용하는 방법을 보여 줍니다.

제한된 액세스 토큰 기능은 기존 Azure AI 서비스 토큰 서비스의 일부입니다. 승인된 시나리오에 대해 Limited Access 게이트를 무시하기 위한 새로운 작업을 추가했습니다. 게이팅 요구 사항을 통과한 ISV만이 이 기능에 액세스할 수 있습니다.

사용 사례

예제 회사에서는 Azure AI Face 서비스를 사용하여 도어 액세스 보안 시스템을 운영하는 소프트웨어를 판매합니다. 고객인 도어 디바이스의 개별 제조업체는 소프트웨어에 가입하고 해당 디바이스에서 실행합니다. 이러한 클라이언트 회사는 얼굴 식별과 같은 Limited Access 작업을 수행하기 위해 디바이스에서 Face API 호출을 원합니다. ISV의 액세스 토큰을 사용하면 얼굴 식별에 대한 공식적인 승인 프로세스를 무시할 수 있습니다. 이미 승인된 ISV는 클라이언트에게 Just-In-Time 액세스 토큰을 부여할 수 있습니다.

책임에 대한 예상 결과

토큰 발급 ISV는 토큰이 승인된 용도로만 사용되는지 확인하는 역할을 담당합니다.

클라이언트가 승인되지 않은 목적으로 LimitedAccessToken을 사용하고 있다는 사실을 ISV가 알게 되면 ISV는 해당 고객을 위한 토큰 생성을 중단해야 합니다. Microsoft는 LimitedAccessTokens의 발급 및 사용을 추적할 수 있으며 남용이 해결되지 않을 경우 ISV의 issueLimitedAccessToken API 액세스 권한을 해지할 권리를 보유합니다.

필수 조건

• cURL이 설치됨(또는 HTTP 요청을 할 수 있는 다른 도구).
• ISV에는 Azure AI Face 리소스 또는 Azure AI 서비스 다중 서비스 리소스가 있어야 합니다.
• 클라이언트에는 Azure AI Face 리소스가 있어야 합니다.

1단계: ISV가 클라이언트의 Face 리소스 ID를 가져옵니다.

ISV는 자체 보안 클라우드 서비스(액세스 토큰을 생성함)와 클라이언트 디바이스에서 실행되는 애플리케이션 간의 통신 채널을 설정해야 합니다. LimitedAccessToken을 생성하기 전에 클라이언트의 Face 리소스 ID를 알아야 합니다.

Face 리소스 ID의 형식은 다음과 같습니다.

/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가 토큰을 생성합니다.

보안 환경에서 실행되는 ISV의 클라우드 서비스는 최종 고객의 알려진 Face 리소스 ID를 사용하여 issueLimitedAccessToken API를 호출합니다.

issueLimitedAccessToken API를 호출하려면 다음 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>를 ISV 리소스의 엔드포인트로 바꿉니다. 예를 들어, westus.api.cognitive.microsoft.com입니다.
2. 선택적으로 expiredTime 매개 변수를 설정하여 토큰 만료 시간을 초 단위로 설정합니다. 60에서 86400 사이여야 합니다. 기본값은 3600(1시간)입니다.
3. <client-face-key>를 클라이언트의 Face 리소스 키로 바꿉니다.
4. <subscription-id>를 클라이언트 Azure 구독의 구독 ID로 바꿉니다.
5. <resource-group-name>을 클라이언트 리소스 그룹의 이름으로 바꿉니다.
6. <face-resource-name>을 클라이언트의 Face 리소스 이름으로 바꿉니다.
7. 부여하려는 액세스 역할 집합으로 "featureFlags"를 설정합니다. 사용 가능한 플래그는 "Face.Identification", "Face.Verification" 및 "LimitedAccess.HighRisk"입니다. ISV는 Microsoft가 자체적으로 부여한 권한만 부여할 수 있습니다. 예를 들어, ISV에 얼굴 식별에 대한 액세스 권한이 부여된 경우 클라이언트의 Face.Identification에 대한 LimitedAccessToken을 만들 수 있습니다. 모든 토큰 생성 스크립트 및 사용은 사용 및 보안 목적으로 기록됩니다.

그런 다음 명령을 터미널 창에 붙여넣고 실행합니다.

API는 JSON 웹 토큰(application/jwt) 형식의 토큰과 함께 200 응답을 반환해야 합니다. LimitedAccessToken을 검사하려면 JWT를 사용하면 됩니다.

3단계: 클라이언트 애플리케이션이 토큰을 사용합니다.

그런 다음 ISV의 애플리케이션은 클라이언트를 대신하여 향후 Face API 요청에 대한 HTTP 요청 헤더로 제한된 액세스 토큰을 전달할 수 있습니다. 이는 다른 인증 메커니즘과 독립적으로 작동하므로 클라이언트의 개인 정보가 ISV로 유출되지 않습니다.

주의

토큰 값은 백그라운드에서 전달될 수 있으므로 클라이언트는 토큰 값을 알 필요가 없습니다. 클라이언트가 웹 모니터링 도구를 사용하여 트래픽을 가로채는 경우 LimitedAccessToken 헤더를 볼 수 있습니다. 그러나 토큰은 짧은 시간이 지나면 만료되기 때문에 이를 사용하여 수행할 수 있는 작업이 제한됩니다. 이 위험은 알려져 있으며 허용 가능한 것으로 간주됩니다.

클라우드 서비스에서 클라이언트 애플리케이션으로 토큰을 정확히 전달하는 방법은 각 ISV가 결정합니다.

REST API

액세스 토큰을 사용하는 Face 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과 Face 키는 ISV의 리소스가 아닌 클라이언트의 Face 리소스에 속합니다. <token>은 HTTP 요청 헤더로 전달됩니다.

C#

다음 코드 조각은 C#용 Face SDK에서 액세스 토큰을 사용하는 방법을 보여 줍니다.

다음 클래스는 액세스 토큰을 사용하여 Face API 클라이언트 개체를 인증하는 데 사용할 수 있는 ServiceClientCredentials 개체를 만듭니다. 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)); 
    }
}

다음 단계

• LimitedAccessToken API 참조