서비스 주체를 사용하여 로컬 개발 중 Azure 서비스에 .NET 앱 인증

아티클
08/09/2024

개발자는 로컬 워크스테이션에서 클라우드 앱을 디버그하고 테스트해야 합니다. 앱이 로컬 개발 중에 개발자의 워크스테이션에서 실행되는 경우에도 앱은 앱에서 사용하는 모든 Azure 서비스에 인증해야 합니다. 이 문서에서는 로컬 개발 중에 사용할 전용 애플리케이션 서비스 주체 개체를 설정하는 방법을 다룹니다.

로컬 .NET 앱이 개발자의 자격 증명을 사용하여 로컬에 설치된 개발 도구를 사용해 Azure에 연결하는 방법을 보여 주는 다이어그램.

로컬 개발을 위한 전용 애플리케이션 서비스 주체를 사용하면 앱 개발 중에 최소 권한 원칙을 따를 수 있습니다. 권한 범위는 개발 중에 앱에 필요한 범위로 정확하게 지정되므로 앱 코드가 다른 앱에서 사용하기 위한 Azure 리소스에 실수로 액세스하지 못하게 됩니다. 이는 앱이 개발 환경에서 과도한 권한을 부여받았기 때문에 앱이 프로덕션으로 이동할 때 버그가 발생하는 것 또한 방지합니다.

앱이 Azure에 등록되면 앱에 대한 애플리케이션 서비스 주체가 설정됩니다. 로컬 개발을 위해 앱을 등록할 때 다음을 수행하는 것이 좋습니다.

앱에서 작업하는 각 개발자에 대해 별도의 앱 등록을 만듭니다. 이렇게 하면 각 개발자가 로컬로 개발하는 동안 사용할 별도의 애플리케이션 서비스 주체가 만들어지고 개발자가 단일 애플리케이션 서비스 주체에 대한 자격 증명을 공유할 필요가 없습니다.
앱당 별도의 앱 등록을 만듭니다. 이는 앱에 필요한 권한으로만 앱의 권한 범위를 지정합니다.

로컬 개발 중에 환경 변수는 애플리케이션 서비스 주체의 ID로 설정됩니다. Azure ID 라이브러리는 이러한 환경 변수를 읽고 이 정보를 사용하여 필요한 Azure 리소스에 대해 앱을 인증합니다.

1 - Azure에 애플리케이션 등록

애플리케이션 서비스 주체 개체는 Azure에서 앱 등록을 통해 만들어집니다. 이 작업은 Azure Portal 또는 Azure CLI를 사용하여 수행할 수 있습니다.

Azure Portal
Azure CLI

Azure Portal에 로그인하고 다음 단계를 따릅니다.

지침	스크린샷
Azure Portal에서 다음을 수행합니다. Azure Portal 상단의 검색 창에 앱 등록을 입력합니다. 검색 창 아래에 나타나는 메뉴의 서비스 제목 아래에서 앱 등록 항목을 선택합니다.
앱 등록 페이지에서 + 신규 등록 을 선택합니다.
애플리케이션 등록 페이지에서 다음과 같이 양식을 작성합니다. 이름 → Azure에 앱 등록을 위한 이름을 입력합니다. 이 이름에는 앱 이름, 앱 등록 대상 사용자, 이 앱 등록이 로컬 개발에 사용됨을 나타내는 'dev'와 같은 식별자가 포함되는 것이 좋습니다. 지원되는 계정 유형 → 이 조직 디렉터리의 계정만. 등록을 선택하여 앱을 등록하고 애플리케이션 서비스 주체를 만듭니다.
앱의 앱 등록 페이지에서: 애플리케이션(클라이언트) ID → 로컬 개발 중에 앱이 Azure에 액세스하는 데 사용할 앱 ID입니다. 이후 단계에서 필요하므로 이 값을 텍스트 편집기의 임시 위치에 복사합니다. 디렉터리(테넌트) ID → 이 값은 앱이 Azure에 인증할 때에도 필요합니다. 이 값 또한 이후 단계에서 필요하므로 텍스트 편집기의 임시 위치에 복사합니다. 클라이언트 자격 증명 → 앱이 Azure에 인증하고 Azure 서비스를 사용하려면 먼저 앱에 대한 클라이언트 자격 증명을 설정해야 합니다. 앱에 대한 자격 증명을 추가하려면 인증서 또는 비밀 추가를 선택합니다.
인증서 및 암호 페이지에서 + 새 클라이언트 암호를 선택합니다.
클라이언트 암호 추가 대화 상자가 페이지 오른쪽에 나타납니다. 이 대화 상자에서: 설명 → 현재 값을 입력합니다. 만료 → 24개월 값을 선택합니다. 비밀을 추가하려면 추가를 선택합니다.
인증서 및 암호 페이지에 클라이언트 암호 값이 표시됩니다. 이후 단계에서 필요하므로 이 값을 텍스트 편집기의 임시 위치에 복사합니다. 중요: 이 값을 볼 수 있는 유일한 시간입니다. 이 페이지를 나가거나 새로 고치면 이 값을 다시 볼 수 없습니다. 이 클라이언트 암호를 무효화하지 않고 추가 클라이언트 암호를 추가할 수 있지만 이 값은 다시 표시되지 않습니다.

Azure CLI 명령은 Azure Cloud Shell에서 실행하거나 Azure CLI가 설치된 워크스테이션에서 실행할 수 있습니다.

먼저, az ad sp create-for-rbac 명령을 사용하여 앱에 대한 새 서비스 주체를 만듭니다. 동시에 앱에 대한 앱 등록도 만들어집니다.

az ad sp create-for-rbac \
    --name {service-principal-name}

이 명령의 출력은 다음 JSON과 유사합니다.

{
  "appId": "00000000-0000-0000-0000-000000000000",
  "displayName": "{service-principal-name}",
  "password": "abcdefghijklmnopqrstuvwxyz",
  "tenant": "11111111-1111-1111-1111-111111111111"
}

이후 단계에서 이러한 값이 필요하므로 이 출력을 텍스트 편집기의 임시 파일에 복사해 둡니다. 여기가 서비스 주체의 클라이언트 암호를 확인하는 유일한 위치가 됩니다. 그러나 필요한 경우 서비스 주체나 기존 암호를 무효화하지 않고 나중에 새 암호를 추가할 수 있습니다.

2 - 로컬 개발을 위한 Microsoft Entra 그룹 만들기

일반적으로 앱 작업을 수행하는 개발자는 여러 명이므로 개별 서비스 주체 개체에 역할을 할당하는 대신 Microsoft Entra 그룹을 만들어 로컬 개발 중에 앱에 필요한 역할(권한)을 모아 두면 좋습니다. 이 방법을 사용하면 다음과 같은 이점이 있습니다.

역할은 그룹 수준에서 할당되므로 모든 개발자는 동일한 역할을 할당받게 됩니다.
앱에 새 역할이 필요한 경우 앱의 그룹에만 추가하면 됩니다.
새로운 개발자가 팀에 합류하면 개발자를 위한 새로운 애플리케이션 서비스 주체가 만들어져 그룹에 추가되어 개발자에게 앱 작업에 대한 올바른 권한이 있는지 확인합니다.

Azure Portal
Azure CLI

지침	스크린샷
페이지 맨 위에 있는 검색 상자에 Microsoft Entra ID를 입력하여 Azure Portal의 Microsoft Entra ID 페이지로 이동합니다. 서비스 섹션에서 Microsoft Entra ID를 선택합니다.
Microsoft Entra ID 페이지의 왼쪽 메뉴에서 그룹을 선택합니다.
모든 그룹 페이지에서 새 그룹을 선택합니다.
새 그룹 페이지에서: 그룹 유형 → 보안 그룹 이름 → 일반적으로 애플리케이션 이름에서 만들어지는 보안 그룹의 이름입니다. 그룹의 목적을 나타내기 위해 그룹 이름에 local-dev와 같은 문자열을 포함하는 것도 도움이 됩니다. 그룹 설명 → 그룹 목적에 대한 설명입니다. 그룹에 멤버를 추가하려면 멤버 아래에서 선택한 멤버 없음 링크를 선택합니다.
멤버 추가 대화 상자에서 다음을 수행합니다. 검색 상자를 사용하여 목록의 주체 이름 목록을 필터링합니다. 이 앱의 로컬 개발을 위한 애플리케이션 서비스 주체를 선택합니다. 개체를 선택하면 회색으로 표시되고 대화 상자 하단의 선택한 항목 목록으로 이동됩니다. 완료되면 선택 단추를 선택합니다.
새 그룹 페이지로 돌아가서 만들기를 선택하여 그룹을 만듭니다. 그룹이 만들어지고 모든 그룹 페이지로 돌아가게 됩니다. 그룹이 나타나는 데 최대 30초가 걸릴 수 있습니다. Azure Portal의 캐싱으로 인해 페이지를 새로 고쳐야 할 수 있습니다.

az ad group create 명령은 Microsoft Entra ID에서 그룹을 만드는 데 사용됩니다. --display-name 및 --mail-nickname 매개 변수는 필수 항목입니다. 그룹에 부여되는 이름은 앱 이름을 기반으로 해야 합니다. 그룹의 목적을 나타내기 위해 그룹 이름에 'local-dev'와 같은 문구를 포함하는 것도 유용합니다.

az ad group create \
    --display-name MyDisplay \
    --mail-nickname MyDisplay \
    --description {group-description}

그룹에 구성원을 추가하려면 애플리케이션 ID와 다른 애플리케이션 서비스 주체의 개체 ID가 필요합니다. az ad sp list 명령을 사용하여 사용 가능한 서비스 주체를 나열합니다. --filter 매개 변수 명령은 OData 스타일 필터를 허용하며 표시된 대로 목록을 필터링하는 데 사용할 수 있습니다. --query 매개 변수는 필요한 항목으로만 열을 제한합니다.

az ad sp list \
    --filter "startswith(displayName, 'msdocs')" \
    --query "[].{objectId:objectId, displayName:displayName}" \
    --output table

그런 다음 az ad group member add 명령을 사용하여 그룹에 구성원을 추가할 수 있습니다.

az ad group member add \
    --group {group-name} \
    --member-id {object-id}

3 - 애플리케이션에 역할 할당

다음으로, 앱에 어떤 리소스에 대한 어떤 역할(권한)이 필요한지 결정하고 해당 역할을 앱에 할당합니다. 이 예에서는 2단계에서 만든 Microsoft Entra 그룹에 역할이 할당됩니다. 그룹은 리소스, 리소스 그룹 또는 구독 범위에서 역할을 할당할 수 있습니다. 이 예에서는 대부분의 앱이 모든 Azure 리소스를 단일 리소스 그룹으로 그룹화하므로 리소스 그룹 범위에서 역할을 할당하는 방법을 보여 줍니다.

Azure Portal
Azure CLI

지침	스크린샷
Azure Portal 상단에 있는 검색 상자를 통해 리소스 그룹 이름을 검색하여 앱에 필요한 리소스 그룹을 찾습니다. 대화 상자의 리소스 그룹 제목 아래에서 리소스 그룹 이름을 선택하여 리소스 그룹으로 이동합니다.
리소스 그룹 페이지의 왼쪽 메뉴에서 액세스 제어(IAM)를 선택합니다.
액세스 제어(IAM) 페이지에서 다음을 수행합니다. 역할 할당 탭을 선택합니다. 위쪽 메뉴에서 + 추가를 선택한 다음, 드롭다운 메뉴에서 역할 할당 추가를 선택합니다.
역할 할당 추가 페이지에는 리소스 그룹에 할당할 수 있는 모든 역할이 나열됩니다. 검색 상자를 사용하여 목록을 보다 관리하기 쉬운 크기로 필터링합니다. 이 예에서는 Storage Blob 역할을 필터링하는 방법을 보여 줍니다. 할당하려는 역할을 선택합니다. 다음 화면으로 이동하려면 다음을 선택합니다.
다음 역할 할당 추가 페이지에서는 역할을 할당할 사용자를 할당할 수 있습니다. 액세스 할당에서 사용자, 그룹 또는 서비스 주체를 선택합니다. 구성원에서 + 구성원 선택을 선택합니다. Azure Portal의 오른쪽에 대화 상자가 열립니다.
멤버 선택 대화 상자에서: 선택 텍스트 상자를 사용하여 구독의 사용자 및 그룹 목록을 필터링할 수 있습니다. 필요한 경우 앱용으로 만든 로컬 개발 Microsoft Entra 그룹의 처음 몇 문자를 입력합니다. 애플리케이션과 연결된 로컬 개발 Microsoft Entra 그룹을 선택합니다. 계속하려면 대화 상자 하단에서 선택을 선택합니다.
역할 할당 추가 화면에 Microsoft Entra 그룹이 선택된 것으로 표시됩니다. 검토 + 할당을 선택하여 최종 페이지로 이동한 다음 다시 검토 + 할당을 선택하여 프로세스를 완료합니다.

애플리케이션 서비스 주체에는 az role assignment create 명령을 사용하여 Azure의 역할이 할당됩니다.

az role assignment create --assignee "{appId}" \
    --role "{roleName}" \
    --resource-group "{resourceGroupName}"

서비스 주체를 할당할 수 있는 역할 이름을 가져오려면 az role definition list 명령을 사용합니다.

az role definition list \
    --query "sort_by([].{roleName:roleName, description:description}, &roleName)" \
    --output table

예를 들어 appId가 00000000-0000-0000-0000-000000000000인 애플리케이션 서비스 주체에 msdocs-dotnet-sdk-auth-example 리소스 그룹의 모든 스토리지 계정에 대한 데이터와 Azure Storage Blob 컨테이너에 대한 읽기, 쓰기, 삭제 액세스 권한을 허용하려면 다음 명령을 사용하여 Storage Blob 데이터 기여자 역할에 애플리케이션 서비스 주체를 할당합니다.

az role assignment create --assignee "00000000-0000-0000-0000-000000000000" \
    --role "Storage Blob Data Contributor" \
    --resource-group "msdocs-dotnet-sdk-auth-example"

Azure CLI를 사용하여 리소스 또는 구독 수준에서 권한을 할당하는 방법에 대한 자세한 내용은 Azure CLI를 사용하여 Azure 역할 할당을 참조하세요.

4 - 애플리케이션 환경 변수 설정

런타임 시 DefaultAzureCredential은 환경 변수 컬렉션에서 서비스 주체 정보를 찾습니다. .NET으로 작업할 때 도구 및 환경에 따라 환경 변수를 구성하는 여러 가지 방법이 있습니다.

어떤 방식을 선택하든 서비스 주체로 작업할 때 다음 환경 변수를 구성합니다.

AZURE_CLIENT_ID → 앱 ID 값입니다.
AZURE_TENANT_ID → 테넌트 ID 값입니다.
AZURE_CLIENT_SECRET → 앱에 대해 생성된 암호/자격 증명입니다.

Visual Studio를 사용하여 로컬로 작업할 때 프로젝트의 Properties 폴더에 있는 launchsettings.json 파일에서 환경 변수를 설정할 수 있습니다. 앱이 시작되면 이러한 값을 자동으로 가져옵니다. 이러한 구성은 앱이 배포될 때 앱과 함께 이동하지 않으므로 대상 호스팅 환경에서 환경 변수를 설정해야 한다는 점에 유의해야 합니다.

"profiles": {
    "SampleProject": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7177;http://localhost:5177",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "AZURE_CLIENT_ID": "00000000-0000-0000-0000-000000000000",
        "AZURE_TENANT_ID":"11111111-1111-1111-1111-111111111111",
        "AZURE_CLIENT_SECRET": "=abcdefghijklmnopqrstuvwxyz"
      }
    },
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "AZURE_CLIENT_ID": "00000000-0000-0000-0000-000000000000",
        "AZURE_TENANT_ID": "11111111-1111-1111-1111-111111111111",
        "AZURE_CLIENT_SECRET": "=abcdefghijklmnopqrstuvwxyz"
      }
    }
  }

Visual Studio Code를 사용하여 로컬로 작업하는 경우 프로젝트의 launch.json 파일에서 환경 변수를 설정할 수 있습니다. 앱이 시작되면 이러한 값이 자동으로 가져옵니다. 이러한 구성은 앱이 배포될 때 앱과 함께 이동하지 않으므로 대상 호스팅 환경에서 환경 변수를 설정해야 한다는 점에 유의해야 합니다.

"configurations": [
{
    "env": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "AZURE_CLIENT_ID": "00000000-0000-0000-0000-000000000000",
        "AZURE_TENANT_ID":"11111111-1111-1111-1111-111111111111",
        "AZURE_CLIENT_SECRET": "=abcdefghijklmnopqrstuvwxyz"
    }
}

명령줄에서 Windows에 대한 환경 변수를 설정할 수 있습니다. 그러나 이 방법을 사용하는 경우 해당 운영 체제에서 실행되는 모든 앱에서 값에 액세스할 수 있으며 주의하지 않으면 충돌이 발생할 수 있습니다. 환경 변수는 사용자 또는 시스템 수준에서 설정할 수 있습니다.

# Set user environment variables
setx ASPNETCORE_ENVIRONMENT "Development"
setx AZURE_CLIENT_ID "00000000-0000-0000-0000-000000000000"
setx AZURE_TENANT_ID "11111111-1111-1111-1111-111111111111"
setx AZURE_CLIENT_SECRET "=abcdefghijklmnopqrstuvwxyz"

# Set system environment variables - requires running as admin
setx ASPNETCORE_ENVIRONMENT "Development"
setx AZURE_CLIENT_ID "00000000-0000-0000-0000-000000000000" /m
setx AZURE_TENANT_ID "11111111-1111-1111-1111-111111111111" /m
setx AZURE_CLIENT_SECRET "=abcdefghijklmnopqrstuvwxyz" /m

PowerShell을 사용하여 사용자 또는 컴퓨터 수준에서 환경 변수를 설정할 수도 있습니다.

# Set user environment variables
[Environment]::SetEnvironmentVariable("ASPNETCORE_ENVIRONMENT", "Development", "User")
[Environment]::SetEnvironmentVariable("AZURE_CLIENT_ID", "00000000-0000-0000-0000-000000000000", "User")
[Environment]::SetEnvironmentVariable("AZURE_TENANT_ID", "11111111-1111-1111-1111-111111111111", "User")
[Environment]::SetEnvironmentVariable("AZURE_CLIENT_SECRET", "=abcdefghijklmnopqrstuvwxyz", "User")

# Set system environment variables - requires running as admin
[Environment]::SetEnvironmentVariable("ASPNETCORE_ENVIRONMENT", "Development", "Machine")
[Environment]::SetEnvironmentVariable("AZURE_CLIENT_ID", "00000000-0000-0000-0000-000000000000", "Machine")
[Environment]::SetEnvironmentVariable("AZURE_TENANT_ID", "11111111-1111-1111-1111-111111111111", "Machine")
[Environment]::SetEnvironmentVariable("AZURE_CLIENT_SECRET", "=abcdefghijklmnopqrstuvwxyz", "Machine")

5 - 애플리케이션에 DefaultAzureCredential 구현

DefaultAzureCredential은 Microsoft Entra에 인증하기 위한 순서가 지정된 독자적 메커니즘 시퀀스입니다. 각 인증 메커니즘은 TokenCredential 클래스에서 파생된 클래스이며 자격 증명이라고 합니다. 런타임 시 DefaultAzureCredential은 첫 번째 자격 증명을 사용하여 인증을 시도합니다. 해당 자격 증명이 액세스 토큰을 획득하지 못하면 액세스 토큰을 성공적으로 가져올 때까지 시퀀스의 다음 자격 증명이 시도됩니다. 이러한 방식을 통해 앱은 환경별 코드를 작성하지 않고도 다양한 환경에서 여러 자격 증명을 사용할 수 있습니다.

DefaultAzureCredential이 자격 증명을 찾는 순서와 위치는 DefaultAzureCredential에서 확인할 수 있습니다.

DefaultAzureCredential을 사용하려면 Azure.Identity 및 필요에 따라 Microsoft.Extensions.Azure 패키지를 애플리케이션에 추가합니다.

명령줄
NuGet 패키지 관리자

원하는 터미널에서 애플리케이션 프로젝트 디렉터리로 이동하고 다음 명령을 실행합니다.

dotnet add package Azure.Identity
dotnet add package Microsoft.Extensions.Azure

Azure 서비스는 다양한 Azure SDK 클라이언트 라이브러리의 특수 클라이언트 클래스를 사용하여 액세스됩니다. 이러한 클래스와 자체 사용자 지정 서비스는 등록되어야 앱 전체에서 종속성 주입을 통해 액세스할 수 있습니다. Program.cs에서 다음 단계를 완료하여 클라이언트 클래스와 DefaultAzureCredential을 등록합니다.

using 지시문을 통해 Azure.Identity 및 Microsoft.Extensions.Azure 네임스페이스를 포함합니다.
해당하는 Add 접두사 확장 메서드를 사용하여 Azure 서비스 클라이언트를 등록합니다.
DefaultAzureCredential 인스턴스를 UseCredential 메서드에 전달합니다.

예시:

using Microsoft.Extensions.Azure;
using Azure.Identity;

builder.Services.AddAzureClients(clientBuilder =>
{
    clientBuilder.AddBlobServiceClient(
        new Uri("https://<account-name>.blob.core.windows.net"));
    clientBuilder.UseCredential(new DefaultAzureCredential());
});

UseCredential의 대안은 DefaultAzureCredential을 직접 인스턴스화하는 것입니다.

using Azure.Identity;

builder.Services.AddSingleton<BlobServiceClient>(_ =>
    new BlobServiceClient(
        new Uri("https://<account-name>.blob.core.windows.net"),
        new DefaultAzureCredential()));

위 코드가 로컬 개발 워크스테이션에서 실행되면 환경 변수에서 애플리케이션 서비스 주체를 찾거나 로컬에 설치된 개발자 도구(예: Visual Studio)에서 개발자 자격 증명 집합을 찾습니다. 두 방법 중 하나를 사용하여 로컬 개발 중에 Azure 리소스에 앱을 인증할 수 있습니다.

Azure에 배포되면 이 동일한 코드는 다른 Azure 리소스에 대해 앱을 인증할 수도 있습니다. DefaultAzureCredential은 환경 설정 및 관리 ID 구성을 검색하여 다른 서비스에 자동으로 인증할 수 있습니다.

다음을 통해 공유