클라이언트 앱 인증 코드 작성

아티클
02/17/2024

Azure Digital Twins 인스턴스와 인증을 설정한 후에는 인스턴스와 상호 작용하는 데 사용할 클라이언트 애플리케이션을 만들 수 있습니다. 시작 클라이언트 프로젝트를 설정한 후에는 Azure Digital Twins 인스턴스에 대해 클라이언트 앱에서 인증하는 코드를 작성해야 합니다.

Azure Digital Twins는 OAUTH 2.0 기반 Microsoft Entra Security Tokens를 사용하여 인증합니다. SDK를 인증하려면 Azure Digital Twins에 대한 올바른 사용 권한이 있는 전달자 토큰을 가져와서 API 호출과 함께 전달해야 합니다.

이 문서에서는 Azure.Identity 클라이언트 라이브러리를 사용하여 자격 증명을 가져오는 방법을 설명합니다. 이 문서에서는 .NET(C#) SDK에 대해 작성하는 것과 같은 C#의 코드 예를 보여주지만, 사용 중인 SDK에 관계없이 Azure.Identity 버전을 사용할 수 있습니다. Azure Digital Twins에 사용할 수 있는 SDK에 대한 자세한 내용은 Azure Digital Twins API 및 SDK를 참조하세요.

필수 조건

먼저 인스턴스 및 인증 설정에서 설정 단계를 완료합니다. 이 설정은 Azure Digital Twins 인스턴스가 있고 사용자에게 액세스 권한이 있는지 확인할 수 있습니다. 설정한 후에는 클라이언트 앱 코드를 작성할 준비가 된 것입니다.

계속하려면 코드를 작성하는 클라이언트 앱 프로젝트가 필요합니다. 클라이언트 앱 프로젝트를 아직 설정하지 않은 경우 이 자습서에서 사용할 수 있도록 선택한 언어로 기본 프로젝트를 만듭니다.

Azure.Identity 라이브러리를 사용하여 인증

Azure.Identity는 전달자 토큰을 가져오고 SDK를 사용하여 인증하는 데 사용할 수 있는 몇 가지 자격 증명 가져오기 방법을 제공하는 클라이언트 라이브러리입니다. 이 문서에서는 C#의 예제를 제공하지만 다음을 비롯한 여러 언어에 대한 Azure.Identity를 볼 수 있습니다.

Azure.Identity의 세 가지 일반적인 자격 증명 가져오기 메서드는 다음과 같습니다.

DefaultAzureCredential은 Azure에 배포되는 애플리케이션에 대한 기본 TokenCredential 인증 흐름을 제공하며 로컬 개발에 권장되는 옵션입니다. 또한 이 문서에서 권장하는 다른 두 가지 메서드를 사용하는 데 활용할 수 있습니다. 즉, ManagedIdentityCredential을 래핑하고 구성 변수를 사용하여 InteractiveBrowserCredential에 액세스할 수 있습니다.
ManagedIdentityCredential은 MSI(관리 ID)를 필요로 하는 경우에 적합하며, Azure Functions로 작업하고 Azure 서비스에 배포하는 데 적합합니다.
InteractiveBrowserCredential은 대화형 애플리케이션을 위한 것이며 인증된 SDK 클라이언트를 만드는 데 사용할 수 있습니다.

이 문서의 나머지 부분에서는 이 메서드를 .NET(C#) SDK와 함께 사용하는 방법을 보여 줍니다.

.NET 프로젝트에 Azure.Identity 추가

Azure.Identity로 인증하도록 .NET 프로젝트를 설정하려면 다음 단계를 완료합니다.

프로젝트에 SDK 패키지 Azure.DigitalTwins.Core 및 Azure.Identity 패키지를 포함합니다. 선택한 도구에 따라 Visual Studio 패키지 관리자 또는 dotnet 명령줄 도구를 사용하여 패키지를 포함할 수 있습니다.

다음 using 문을 프로젝트 코드에 추가합니다.

using Azure.DigitalTwins.Core;
using Azure.Identity;
using System;

다음으로, Azure.Identity의 메서드 중 하나를 사용하여 자격 증명을 가져오는 코드를 추가합니다. 다음 섹션에서는 각각을 사용하는 방법에 대해 자세히 설명합니다.

DefaultAzureCredential 메서드

DefaultAzureCredential은 Azure에 배포되는 애플리케이션에 대한 기본 TokenCredential 인증 흐름을 제공하며 로컬 개발에 권장되는 옵션입니다.

기본 Azure 자격 증명을 사용하려면 Azure Digital Twins 인스턴스의 URL(찾아볼 수 있는 지침)이 필요합니다.

프로젝트에 DefaultAzureCredential을 추가하는 코드 샘플은 다음과 같습니다.

public class DefaultAzureCredentialSample
{
    // The URL of your instance, starting with the protocol (https://)
    private const string adtInstanceUrl = "https://<your-Azure-Digital-Twins-instance-URL>";

    internal void RunSample()
    {
        //...

        DigitalTwinsClient client;
        try
        {
            var credential = new DefaultAzureCredential();
            client = new DigitalTwinsClient(new Uri(adtInstanceUrl), credential);
        }
        catch (Exception e)
        {
            Console.WriteLine($"Authentication or client creation error: {e.Message}");
            Environment.Exit(0);
        }
    }
}

참고 항목

현재 인증하는 동안 오류가 발생할 수 있는 DefaultAzureCredential 래퍼 클래스에 영향을 미치는 알려진 문제가 있습니다. 이 문제가 발생하면 다음 선택적 매개 변수를 사용하여 DefaultAzureCredential을 인스턴스화하여 해결할 수 있습니다. new DefaultAzureCredential(new DefaultAzureCredentialOptions { ExcludeSharedTokenCacheCredential = true });

이 문제에 대한 자세한 내용은 Azure Digital Twins 알려진 문제를 참조하세요.

로컬 Azure 자격 증명 설정

DefaultAzureCredential을 사용하면 샘플에서 로컬 Azure CLI 또는 Visual Studio 또는 Visual Studio Code의 Azure 로그인과 같은 로컬 환경에서 자격 증명을 검색합니다. 이러한 이유로 샘플에 대한 자격 증명을 설정하려면 이러한 메커니즘 중 하나를 통해 Azure에 로컬로 로그인해야 합니다.

Visual Studio 또는 Visual Studio Code를 사용하여 코드 샘플을 실행하는 경우 Azure Digital Twins 인스턴스에 액세스하는 데 사용하려는 것과 동일한 Azure 자격 증명을 사용하여 해당 편집기에 로그인했는지 확인합니다. 로컬 CLI 창을 사용하는 경우 az login 명령을 실행하여 Azure 계정에 로그인합니다. 그런 다음 코드 샘플을 실행하면 자동으로 인증을 받아야 합니다.

ManagedIdentityCredential 메서드

ManagedIdentityCredential 메서드는 관리 ID(MSI)가 필요한 경우(예: Azure Functions로 인증)에 유용합니다.

즉, DefaultAzureCredential 또는 InteractiveBrowserCredential과 동일한 프로젝트에서 ManagedIdentityCredential을 사용하여 프로젝트의 다른 부분을 인증할 수 있습니다.

기본 Azure 자격 증명을 사용하려면 Azure Digital Twins 인스턴스의 URL(찾아볼 수 있는 지침)이 필요합니다. 또한 앱 등록과 등록 애플리케이션(클라이언트) ID가 필요할 수 있습니다.

Azure 함수에서 다음과 같은 관리 ID 자격 증명을 사용할 수 있습니다.

public class ManagedIdentityCredentialSample
{
    // The URL of your instance, starting with the protocol (https://)
    private const string adtInstanceUrl = "https://<your-Azure-Digital-Twins-instance-URL>";

    internal void RunSample()
    {
        DigitalTwinsClient client;
        try
        {
            // To use the function app's system-assigned identity:
            ManagedIdentityCredential cred = new ManagedIdentityCredential();
            // To use a user-assigned identity for the function app:
            //ManagedIdentityCredential cred = new ManagedIdentityCredential("<uai-client-ID>");

            client = new DigitalTwinsClient(new Uri(adtInstanceUrl), cred);
        }
        catch (Exception e)
        {
            Console.WriteLine($"Authentication or client creation error: {e.Message}");
            Environment.Exit(0);
        }
    }
}

자격 증명을 만드는 동안 위에 표시된 대로 매개 변수를 비워 두면 함수 앱의 시스템 할당 ID에 대한 자격 증명이 반환됩니다(있는 경우). 대신 사용자 할당 ID를 지정하려면 사용자 할당 ID의 클라이언트 ID를 매개 변수에 전달합니다.

InteractiveBrowserCredential 메서드

InteractiveBrowserCredential 메서드는 대화형 애플리케이션을 위한 것이며 인증을 위해 웹 브라우저를 엽니다. 대화형 인증이 필요한 경우 DefaultAzureCredential 대신 이 메서드를 사용할 수 있습니다.

대화형 브라우저 자격 증명을 사용하려면 Azure Digital Twins API에 대한 사용 권한을 갖게 되는 앱 등록 과정이 필요합니다. 이 앱 등록을 설정하는 방법에 대한 단계는 Azure Digital Twins 액세스를 사용하여 앱 등록 만들기를 참조하세요. 앱 등록을 설정한 후에는 다음이 필요합니다.

다음은 InteractiveBrowserCredential을 사용하여 인증된 SDK 클라이언트를 만드는 코드의 예제입니다.

public class InteractiveBrowserCredentialSample
{
    // Your client / app registration ID
    private const string clientId = "<your-client-ID>";
    // Your tenant / directory ID
    private const string tenantId = "<your-tenant-ID>";
    // The URL of your instance, starting with the protocol (https://)
    private const string adtInstanceUrl = "https://<your-Azure-Digital-Twins-instance-URL>";

    internal void RunSample()
    {
        //...

        DigitalTwinsClient client;
        try
        {
            var credential = new InteractiveBrowserCredential(tenantId, clientId);
            client = new DigitalTwinsClient(new Uri(adtInstanceUrl), credential);
        }
        catch (Exception e)
        {
            Console.WriteLine($"Authentication or client creation error: {e.Message}");
            Environment.Exit(0);
        }
    }
}

참고 항목

위와 같이 클라이언트 ID, 테넌트 ID, 인스턴스 URL을 코드에 직접 저장할 수 있지만, 코드에서 구성 파일 또는 환경 변수로부터 이러한 값을 가져오는 것이 좋습니다.

Azure Functions 인증

이 섹션에는 Azure Functions로 인증하는 컨텍스트에서 몇 가지 중요한 구성 선택 사항이 포함되어 있습니다. 먼저, 함수가 Azure Digital Twins에 액세스할 수 있도록 하는 권장 클래스 수준 변수 및 인증 코드에 대해 읽습니다. 그런 다음 코드가 Azure에 게시된 후 함수에 대해 완료해야 하는 몇 가지 최종 구성 단계에 대해 읽습니다.

애플리케이션 코드 작성

Azure 함수를 작성할 때 다음 변수와 코드를 함수에 추가하는 것이 좋습니다.

Azure Digital Twins 서비스 URL을 환경 변수 또는 구성 설정으로 읽도록 코딩합니다. 함수에 하드 코딩하는 대신 애플리케이션 설정/환경 변수에서 서비스 URL을 읽는 것이 좋습니다. Azure 함수에서 환경 변수를 읽는 코드는 다음과 같습니다.
```
private static readonly string adtInstanceUrl = Environment.GetEnvironmentVariable("ADT_SERVICE_URL");
```
나중에 함수를 게시한 후 이 코드에서 읽을 환경 변수 값을 만들고 설정합니다. 이 작업을 수행하는 방법에 대한 지침은 애플리케이션 설정 구성으로 건너뜁니다.
HttpClient 인스턴스를 보유하는 정적 변수. HttpClient는 만드는 데 상대적으로 비용이 많이 들기 때문에 모든 함수 호출에 대해 만들지 않도록 인증 코드를 사용하여 한 번 만들 수 있습니다.
```
private static readonly HttpClient singletonHttpClientInstance = new HttpClient();
```
관리 ID 자격 증명. 함수에서 Azure Digital Twins에 액세스하는 데 사용할 관리 ID 자격 증명을 만듭니다.
```
// To use the function app's system-assigned identity:
var cred = new ManagedIdentityCredential();
// To use a user-assigned identity for the function app:
//var cred = new ManagedIdentityCredential("<uai-client-ID>");
```
위에 표시된 대로 매개 변수를 비워 두면 함수 앱의 시스템 할당 ID에 대한 자격 증명이 반환됩니다(있는 경우). 대신 사용자 할당 ID를 지정하려면 사용자 할당 ID의 클라이언트 ID를 매개 변수에 전달합니다.

나중에 함수를 게시한 후 함수의 ID에 Azure Digital Twins API를 액세스할 수 있는 권한이 있는지 확인합니다. 이 작업을 수행하는 방법에 대한 지침은 액세스 역할 할당으로 건너뜁니다.
지역 변수 DigitalTwinsClient. 함수 내에 변수를 추가하여 Azure Digital Twins 클라이언트 인스턴스를 보관합니다. 클래스 내부에서 이 변수를 정적으로 설정하지 마세요.
```
var client = new DigitalTwinsClient(
    new Uri(adtInstanceUrl),
    cred,
    new DigitalTwinsClientOptions
    {
        Transport = new HttpClientTransport(singletonHttpClientInstance)
    });
```
adtInstanceUrl에 대한 Null 검사. Null 검사를 추가하고 함수 논리를 try/catch 블록으로 래핑하여 예외를 catch합니다.

이 변수를 함수에 추가한 후 함수 코드는 다음 예와 같을 수 있습니다.

// Default URL for triggering event grid function in the local environment.
// http://localhost:7071/runtime/webhooks/EventGrid?functionName={functionname}
//<Function_dependencies>
using Azure.Core.Pipeline;
using Azure.DigitalTwins.Core;
using Azure.Identity;
using Azure.Messaging.EventGrid;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.EventGrid;
using Microsoft.Extensions.Logging;
using System;
using System.Net.Http;
//</Function_dependencies>

namespace DigitalTwins_Samples
{
    public class DigitalTwinsIngestFunctionSample
    {
        // Your Digital Twin URL is stored in an application setting in Azure Functions
        // <ADT_service_URL>
        private static readonly string adtInstanceUrl = Environment.GetEnvironmentVariable("ADT_SERVICE_URL");
        // </ADT_service_URL>
        // <HTTP_client>
        private static readonly HttpClient singletonHttpClientInstance = new HttpClient();
        // </HTTP_client>

        [FunctionName("TwinsFunction")]
        public void Run([EventGridTrigger] EventGridEvent eventGridEvent, ILogger log)
        {
            log.LogInformation(eventGridEvent.Data.ToString());
            if (adtInstanceUrl == null) log.LogError("Application setting \"ADT_SERVICE_URL\" not set");
            try
            {
                // Authenticate with Digital Twins
                // <ManagedIdentityCredential>
                // To use the function app's system-assigned identity:
                var cred = new ManagedIdentityCredential();
                // To use a user-assigned identity for the function app:
                //var cred = new ManagedIdentityCredential("<uai-client-ID>");
                // </ManagedIdentityCredential>
                // <DigitalTwinsClient>
                var client = new DigitalTwinsClient(
                    new Uri(adtInstanceUrl),
                    cred,
                    new DigitalTwinsClientOptions
                    {
                        Transport = new HttpClientTransport(singletonHttpClientInstance)
                    });
                // </DigitalTwinsClient>
                log.LogInformation($"ADT service client connection created.");

                // Add your business logic here.
            }
            catch (Exception e)
            {
                log.LogError(e.Message);
            }
        }
    }
}

인증 및 함수 논리 추가를 포함하여 함수 코드를 완료했으면 Azure에 앱을 게시합니다.

게시된 앱 구성

마지막으로 게시된 Azure 기능에 대해 다음 구성 단계를 완료하여 Azure Digital Twins 인스턴스에 액세스할 수 있는지 확인합니다.

Azure Cloud Shell 또는 로컬 Azure CLI에서 다음 명령을 실행합니다.

참고 항목

이 섹션은 Azure 리소스에 대한 사용자 액세스를 관리할 수 있는 권한(권한 부여 및 위임 포함)이 있는 Azure 사용자가 완료해야 합니다. 이 요구 사항을 충족하는 일반적인 역할은 소유자, 계정 관리자 또는 사용자 액세스 관리자와 기여자의 조합입니다. Azure Digital Twins 역할의 권한 요구 사항에 대한 자세한 내용은 인스턴스 및 인증 설정을 참조하세요.

액세스 역할 할당

Azure 함수에는 전달자 토큰을 전달해야 합니다. 전달자 토큰이 전달되었는지 확인하려면 함수 앱에 Azure Digital Twins 인스턴스에 대한 Azure Digital Twins 데이터 소유자 역할을 부여합니다. 그러면 함수 앱에 인스턴스에 대한 데이터 평면 작업을 수행할 수 있는 권한이 제공됩니다.

다음 명령을 사용하여 함수에 대한 시스템 관리 ID를 만듭니다(함수에 이미 있는 경우 이 명령은 세부 정보를 출력함). 출력의 principalId 필드를 기록해 두세요. 이 ID를 사용하여 다음 단계에서 해당 권한을 부여할 수 있도록 함수를 참조합니다.
```
az functionapp identity assign --resource-group <your-resource-group> --name <your-function-app-name>	
```
다음 명령에 principalId 값을 사용하여 함수에 Azure Digital Twins 인스턴스의 Azure Digital Twins 데이터 소유자 역할을 부여합니다.
```
az dt role-assignment create --dt-name <your-Azure-Digital-Twins-instance> --assignee "<principal-ID>" --role "Azure Digital Twins Data Owner"
```

애플리케이션 설정 구성

다음으로, 환경 변수를 설정하여 함수에서 Azure Digital Twins 인스턴스의 URL에 액세스할 수 있도록 합니다.

팁

Azure Digital Twins 인스턴스의 URL은 인스턴스의 호스트 이름 앞에 https://가 추가되어 만들어집니다. 인스턴스의 모든 속성과 함께 호스트 이름을 확인하려면 az dt show --dt-name <your-Azure-Digital-Twins-instance> 명령을 실행합니다.

다음 명령은 인스턴스에 액세스해야 할 때마다 함수에서 사용할 인스턴스의 URL에 대한 환경 변수를 설정합니다.

az functionapp config appsettings set --resource-group <your-resource-group> --name <your-function-app-name> --settings "ADT_SERVICE_URL=https://<your-Azure-Digital-Twins-instance-host-name>"

테넌트에서 인증

Azure Digital Twins는 하나의 Microsoft Entra 테넌트(Azure Digital Twins 인스턴스가 있는 구독의 기본 테넌트)만 지원하는 서비스입니다.

결과적으로, Azure Digital Twins API에 대한 요청에는 해당 Azure Digital Twins 인스턴스가 위치한 동일 테넌트의 일부인 사용자 또는 서비스 주체가 필요합니다. Azure Digital Twins 엔드포인트의 악의적인 검색을 방지하기 위해 원래 테넌트 외부에서 액세스 토큰이 있는 요청은 "404 하위 도메인을 찾을 수 없음" 오류 메시지가 반환됩니다. 이 오류는 Microsoft Entra B2B 협업을 통해 사용자 또는 서비스 주체에게 Azure Digital Twins 데이터 소유자 또는 Azure Digital Twins 데이터 읽기 권한자 역할이 부여된 경우에도 반환됩니다.

인스턴스와 다른 테넌트에 속한 서비스 주체 또는 사용자 계정을 사용하여 Azure Digital Twins 인스턴스에 액세스해야 하는 경우 다른 테넌트의 각 페더레이션 ID가 Azure Digital Twins 인스턴스의 "home" 테넌트에서 토큰을 요청하도록 할 수 있습니다.

이를 수행하는 한 가지 방법은 다음 CLI 명령을 사용하는 것입니다. 여기서 <home-tenant-ID>는 Azure Digital Twins 인스턴스가 포함된 Microsoft Entra 테넌트의 ID입니다.

az account get-access-token --tenant <home-tenant-ID> --resource https://digitaltwins.azure.net

이를 요청한 후 ID는 Azure Digital Twins 인스턴스에 대한 테넌트 ID 클레임과 일치하는 https://digitaltwins.azure.net Microsoft Entra 리소스에 대해 발급된 토큰을 받게 됩니다. API 요청 또는 Azure.Identity 코드에서 이 토큰을 사용하면 페더레이션 ID가 Azure Digital Twins 리소스에 액세스할 수 있습니다.

코드의 자격 증명 옵션에서 홈 테넌트를 지정할 수도 있습니다.

다음 예제에서는 DefaultAzureCredential 옵션에서 InteractiveBrowserTenantId에 대한 샘플 테넌트 ID 값을 설정하는 방법을 보여 줍니다.

public class DefaultAzureCredentialOptionsSample
{
    // The URL of your instance, starting with the protocol (https://)
    private const string adtInstanceUrl = "https://<your-Azure-Digital-Twins-instance-URL>";

    private static DefaultAzureCredentialOptions credentialOptions = new DefaultAzureCredentialOptions()
    {
        ExcludeSharedTokenCacheCredential = true,
        ExcludeVisualStudioCodeCredential = true,
        TenantId = "<your-Azure-Active-Directory-tenant-ID>"
    };

    private static DefaultAzureCredential credential = new DefaultAzureCredential(credentialOptions);

    DigitalTwinsClient client = new DigitalTwinsClient(new Uri(adtInstanceUrl), credential);
}

Visual Studio 및 Visual Studio Code 인증을 위한 테넌트 설정에 사용할 수 있는 유사한 옵션이 있습니다. 사용 가능한 옵션에 대한 자세한 내용은 DefaultAzureCredentialOptions 설명서를 참조하세요.

기타 자격 증명 방법

위에서 강조한 인증 시나리오가 사용자 앱의 요구 사항을 해결하지 못하는 경우 Microsoft ID 플랫폼에서 제공하는 다른 유형의 인증을 찾아볼 수 있습니다. 이 플랫폼에 대한 문서는 애플리케이션 유형별로 구성된 더 많은 인증 시나리오를 다룹니다.

다음 단계

Azure Digital Twins에서 보안이 작동하는 방식에 대해 자세히 알아보세요.

Azure Digital Twins 솔루션 보안

또는 이제 인증이 설정되었으므로 인스턴스에서 모델 만들기 및 관리로 이동합니다.

DTDL 모델 관리

클라이언트 앱 인증 코드 작성

필수 조건

Azure.Identity 라이브러리를 사용하여 인증

.NET 프로젝트에 Azure.Identity 추가

DefaultAzureCredential 메서드

로컬 Azure 자격 증명 설정

ManagedIdentityCredential 메서드

InteractiveBrowserCredential 메서드

Azure Functions 인증

애플리케이션 코드 작성

게시된 앱 구성

액세스 역할 할당

애플리케이션 설정 구성

테넌트에서 인증

기타 자격 증명 방법

다음 단계

추가 리소스