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

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

A diagram showing how a JavaScript app during local development will use the developer's credentials to connect to Azure by obtaining those credentials locally installed development tools.

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

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

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

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

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

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

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

지침 스크린샷
Azure Portal에서 다음을 수행합니다.
  1. Azure Portal 상단의 검색 창에 앱 등록을 입력합니다.
  2. 검색 창 아래에 나타나는 메뉴의 서비스 제목 아래에서 앱 등록 항목을 선택합니다.
A screenshot showing how to use the top search bar in the Azure portal to find and navigate to the App registrations page.
앱 등록 페이지에서 + 신규 등록 을 선택합니다. A screenshot showing the location of the New registration button in the App registrations page.
애플리케이션 등록 페이지에서 다음과 같이 양식을 작성합니다.
  1. 이름 → Azure에 앱 등록을 위한 이름을 입력합니다. 이 이름에는 앱 이름, 앱 등록 대상 사용자, 이 앱 등록이 로컬 개발에 사용됨을 나타내는 'dev'와 같은 식별자가 포함되는 것이 좋습니다.
  2. 지원되는 계정 유형이 조직 디렉터리의 계정만.
등록을 선택하여 앱을 등록하고 애플리케이션 서비스 주체를 만듭니다.
A screenshot showing how to fill out the Register an application page by giving the app a name and specifying supported account types as accounts in this organizational directory only.
앱의 앱 등록 페이지에서:
  1. 애플리케이션(클라이언트) ID → 앱이 로컬 개발 중에 Azure에 액세스하는 데 사용할 앱 ID입니다. 이 값은 이후 단계에서 필요하므로 텍스트 편집기에서 임시 위치에 복사합니다.
  2. 디렉터리(테넌트) ID → 이 값은 앱이 Azure에 인증할 때에도 필요합니다. 이 값을 텍스트 편집기에서 임시 위치에 복사합니다. 이후 단계에서도 필요합니다.
  3. 클라이언트 자격 증명 → 앱이 Azure에 인증하고 Azure 서비스를 사용하려면 먼저 앱에 대한 클라이언트 자격 증명을 설정해야 합니다. 앱에 대한 자격 증명을 추가하려면 인증서 또는 비밀 추가를 선택합니다.
A screenshot after the app registration has been completed with the location of the application ID, tenant ID.
인증서 및 비밀 페이지에서 + 새 클라이언트 암호를 선택합니다. A screenshot showing the location of the link to use to create a new client secret on the certificates and secrets page.
클라이언트 암호 추가 대화 상자가 페이지 오른쪽에 나타납니다. 이 대화 상자에서:
  1. 설명현재 값을 입력합니다.
  2. 만료24개월 값을 선택합니다.
비밀을 추가하려면 추가를 선택합니다.
A screenshot showing the page where a new client secret is added for the application service principal create by the app registration process.
인증서 및 비밀 페이지에 클라이언트 암호의 값이 표시됩니다.

이 값은 이후 단계에서 필요하므로 텍스트 편집기에서 임시 위치에 복사합니다.

중요: 이 값이 표시되는 유일한 시간입니다. 이 페이지를 나가거나 새로 고치면 이 값을 다시 볼 수 없습니다. 이 클라이언트 비밀을 무효화하지 않고 클라이언트 비밀을 더 추가할 수 있지만 이 값은 다시 표시되지 않습니다.
A screenshot showing the page with the generated client secret.

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

일반적으로 애플리케이션에서 작업하는 여러 개발자가 있으므로 개별 서비스 주체 개체에 역할을 할당하는 대신 앱이 로컬 개발에 필요한 역할(권한)을 캡슐화하는 Microsoft Entra 그룹을 만드는 것이 좋습니다. 이는 다음과 같은 이점을 제공합니다.

  • 역할은 그룹 수준에서 할당되므로 모든 개발자는 동일한 역할을 할당받게 됩니다.
  • 앱에 새 역할이 필요한 경우 앱에 대한 Microsoft Entra 그룹에만 추가하면 됩니다.
  • 새로운 개발자가 팀에 합류하면 개발자를 위한 새로운 애플리케이션 서비스 주체가 만들어져 그룹에 추가되어 개발자에게 앱 작업에 대한 올바른 권한이 있는지 확인합니다.
지침 스크린샷
페이지 맨 위에 있는 검색 상자에 Microsoft Entra ID를 입력한 다음 서비스에서 Microsoft Entra ID선택하여 Azure Portal의 Microsoft Entra ID 페이지로 이동합니다. A screenshot showing how to use the top search bar in the Azure portal to search for and navigate to the Microsoft Entra ID page.
Microsoft Entra ID 페이지의 왼쪽 메뉴에서 그룹을 선택합니다. A screenshot showing the location of the Groups menu item in the left-hand menu of the Microsoft Entra ID Default Directory page.
모든 그룹 페이지에서 새 그룹을 선택합니다. A screenshot showing the location of the New Group button in the All groups page.
새 그룹 페이지에서:
  1. 그룹 유형보안
  2. 그룹 이름 → 일반적으로 애플리케이션 이름에서 만들어지는 보안 그룹의 이름입니다. 그룹의 목적을 나타내기 위해 그룹 이름에 local-dev와 같은 문자열을 포함하는 것도 도움이 됩니다.
  3. 그룹 설명 → 그룹 목적에 대한 설명입니다.
  4. 그룹에 멤버를 추가하려면 멤버 아래에서 선택한 멤버 없음 링크를 선택합니다.
A screenshot showing how to create a new Microsoft Entra group for the application.
멤버 추가 대화 상자에서 다음을 수행합니다.
  1. 검색 상자를 사용하여 목록의 주체 이름 목록을 필터링합니다.
  2. 이 앱의 로컬 개발을 위한 애플리케이션 서비스 주체를 선택합니다. 개체를 선택하면 회색으로 표시되고 대화 상자 하단의 선택한 항목 목록으로 이동됩니다.
  3. 완료되면 선택 단추를 선택합니다.
A screenshot of the Add members dialog box showing how to select application service principals to be included in the group.
새 그룹 페이지로 돌아가서 만들기를 선택하여 그룹을 만듭니다.

그룹이 만들어지고 모든 그룹 페이지로 돌아갑니다. 그룹이 표시되는 데 최대 30초가 걸릴 수 있으며 Azure Portal의 캐싱으로 인해 페이지를 새로 고쳐야 할 수도 있습니다.
A screenshot of the New Group page showing how to complete the process by selecting the Create button.

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

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

지침 스크린샷
Azure Portal 상단에 있는 검색 상자를 통해 리소스 그룹 이름을 검색하여 애플리케이션에 대한 리소스 그룹을 찾습니다.

대화 상자의 리소스 그룹 제목 아래에서 리소스 그룹 이름을 선택하여 리소스 그룹으로 이동합니다.
A screenshot showing how to use the top search box in the Azure portal to locate and navigate to the resource group you want to assign roles (permissions) to.
리소스 그룹 페이지의 왼쪽 메뉴에서 액세스 제어(IAM)를 선택합니다. A screenshot of the resource group page showing the location of the Access control (IAM) menu item.
액세스 제어(IAM) 페이지에서 다음을 수행합니다.
  1. 역할 할당 탭을 선택합니다.
  2. 위쪽 메뉴에서 + 추가를 선택한 다음, 드롭다운 메뉴에서 역할 할당 추가를 선택합니다.
A screenshot showing how to navigate to the role assignments tab and the location of the button used to add role assignments to a resource group.
역할 할당 추가 페이지에는 리소스 그룹에 할당할 수 있는 모든 역할이 나열됩니다.
  1. 검색 상자를 사용하여 목록을 보다 관리하기 쉬운 크기로 필터링합니다. 이 예에서는 Storage Blob 역할을 필터링하는 방법을 보여 줍니다.
  2. 할당하려는 역할을 선택합니다.
    다음 화면으로 이동하려면 다음을 선택합니다.
A screenshot showing how to filter and select role assignments to be added to the resource group.
다음 역할 할당 추가 페이지에서는 역할을 할당할 사용자를 할당할 수 있습니다.
  1. 액세스 할당에서 사용자, 그룹 또는 서비스 주체를 선택합니다.
  2. 멤버에서 + 멤버 선택을 선택합니다.
Azure Portal의 오른쪽에 대화 상자가 열립니다.
A screenshot showing the radio button to select to assign a role to a Microsoft Entra group and the link used to select the group to assign the role to.
멤버 선택 대화 상자에서:
  1. 선택 텍스트 상자를 사용하여 구독의 사용자 및 그룹 목록을 필터링할 수 있습니다. 필요한 경우 앱에 대해 만든 로컬 개발 Microsoft Entra 그룹의 처음 몇 문자를 입력합니다.
  2. 애플리케이션과 연결된 로컬 개발 Microsoft Entra 그룹을 선택합니다.
계속하려면 대화 상자 하단에서 선택을 선택합니다.
A screenshot showing how to filter for and select the Microsoft Entra group for the application in the Select members dialog box.
Microsoft Entra 그룹은 역할 할당 추가 화면에서 선택된 대로 표시됩니다.

검토 + 할당을 선택하여 최종 페이지로 이동한 다음 다시 검토 + 할당을 선택하여 프로세스를 완료합니다.
A screenshot showing the completed Add role assignment page and the location of the Review + assign button used to complete the process.

4 - 로컬 개발 환경 변수 설정

DefaultAzureCredential 개체는 런타임 시 환경 변수 집합에서 서비스 주체 정보를 찾습니다. 대부분의 개발자는 여러 애플리케이션에서 작업하므로 개발 중에 애플리케이션 디렉터리에 저장된 파일에서 .env 환경에 액세스하기 위해 dotenv와 같은 패키지를 사용하는 것이 좋습니다. 이 범위는 이 애플리케이션에서만 사용할 수 있도록 Azure에 애플리케이션을 인증하는 데 사용되는 환경 변수의 범위를 지정합니다.

파일 .env 은 Azure에 대한 애플리케이션 비밀 키를 포함하기 때문에 소스 제어에 검사 않습니다. JavaScript용 표준 .gitignore 파일은 검사 파일을 자동으로 제외합니다.env.

패키지를 사용 dotenv 하려면 먼저 애플리케이션에 패키지를 설치합니다.

npm install dotenv

그런 다음 애플리케이션 루트 디렉터리에 파일을 만듭니 .env 다. 다음과 같이 앱 등록 프로세스에서 가져온 값으로 환경 변수 값을 설정합니다.

  • AZURE_CLIENT_ID → 앱 ID 값입니다.
  • AZURE_TENANT_ID → 테넌트 ID 값입니다.
  • AZURE_CLIENT_SECRET → 앱에 대해 생성된 암호/자격 증명입니다.
AZURE_CLIENT_ID=00000000-0000-0000-0000-000000000000
AZURE_TENANT_ID=11111111-1111-1111-1111-111111111111
AZURE_CLIENT_SECRET=abcdefghijklmnopqrstuvwxyz

마지막으로 애플리케이션의 시작 코드에서 라이브러리를 dotenv 사용하여 시작 시 파일에서 환경 변수를 .env 읽습니다.

import 'dotenv/config'

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

Azure에 Azure SDK 클라이언트 개체를 인증하려면 애플리케이션에서 패키지의 클래스를 DefaultAzureCredential@azure/identity 사용해야 합니다. 이 시나리오 DefaultAzureCredential 에서는 환경 변수를 AZURE_CLIENT_IDAZURE_TENANT_ID검색하고AZURE_CLIENT_SECRET, 해당 변수를 설정하고 읽어 Azure에 연결할 애플리케이션 서비스 주체 정보를 가져옵니다.

먼저 애플리케이션에 @azure/ID 패키지를 추가합니다.

npm install @azure/identity

다음으로, 앱에서 Azure SDK 클라이언트 개체를 만드는 JavaScript 코드의 경우 다음을 수행합니다.

  1. 모듈에서 DefaultAzureCredential 클래스를 @azure/identity 가져옵니다.
  2. DefaultAzureCredential 개체를 만듭니다.
  3. 개체를 DefaultAzureCredential Azure SDK 클라이언트 개체 생성자에 전달합니다.

이 예제는 다음 코드 세그먼트에 나와 있습니다.

// Azure authentication dependency
import { DefaultAzureCredential } from '@azure/identity';

// Azure resource management dependency
import { SubscriptionClient } from "@azure/arm-subscriptions";

// Acquire credential
const tokenCredential = new DefaultAzureCredential();

async function listSubscriptions() {
  try {

    // use credential to authenticate with Azure SDKs
    const client = new SubscriptionClient(tokenCredential);

    // get details of each subscription
    for await (const item of client.subscriptions.list()) {
      const subscriptionDetails = await client.subscriptions.get(
        item.subscriptionId
      );
      /* 
        Each item looks like:
      
        {
          id: '/subscriptions/123456',
          subscriptionId: '123456',
          displayName: 'YOUR-SUBSCRIPTION-NAME',
          state: 'Enabled',
          subscriptionPolicies: {
            locationPlacementId: 'Internal_2014-09-01',
            quotaId: 'Internal_2014-09-01',
            spendingLimit: 'Off'
          },
          authorizationSource: 'RoleBased'
        },
    */
      console.log(subscriptionDetails);
    }
  } catch (err) {
    console.error(JSON.stringify(err));
  }
}

listSubscriptions()
  .then(() => {
    console.log("done");
  })
  .catch((ex) => {
    console.log(ex);
  });

DefaultAzureCredential 는 앱에 대해 구성된 인증 메커니즘을 자동으로 검색하고 Azure에 앱을 인증하는 데 필요한 토큰을 가져옵니다. 애플리케이션에서 둘 이상의 SDK 클라이언트를 사용하는 경우 각 SDK 클라이언트 개체와 동일한 자격 증명 개체를 사용할 수 있습니다.