빠른 시작: 토큰을 획득하고 Node.js 콘솔 앱에서 Microsoft Graph 호출

이 빠른 시작에서는 Node.js 콘솔 애플리케이션이 앱의 ID를 사용하여 액세스 토큰을 가져와 Microsoft Graph API를 호출하고 디렉터리에 사용자 목록을 표시하는 방법을 보여 주는 코드 샘플을 다운로드하고 실행합니다. 코드 샘플에서는 사용자의 ID 대신 애플리케이션 ID를 사용하여 무인 작업 또는 Windows 서비스를 실행할 수 있는 방법을 보여줍니다.

이 빠른 시작에서는 클라이언트 자격 증명 부여와 함께 Node.js용 Microsoft 인증 라이브러리(MSAL 노드)를 사용합니다.

필수 조건

• Node.JS
• Visual Studio Code 또는 다른 코드 편집기

샘플 애플리케이션 등록 및 다운로드

시작하려면 아래의 단계를 따르세요.

1단계: 애플리케이션 등록

팁

이 문서의 단계는 시작하는 포털에 따라 약간 다를 수 있습니다.

애플리케이션을 등록하고 앱의 등록 정보를 솔루션에 수동으로 추가하려면 다음 단계를 따르세요.

1. 최소한 애플리케이션 관리자로 Microsoft Entra 관리 센터에 로그인합니다.
2. ID>애플리케이션>앱 등록으로 이동합니다.
3. 새 등록을 선택합니다.
4. 애플리케이션에 대한 이름을 입력합니다(예: msal-node-cli). 이 이름은 앱의 사용자에게 표시될 수 있으며 나중에 변경할 수 있습니다.
5. 등록을 선택합니다.
6. 관리에서 인증서 및 비밀을 선택합니다.
7. 클라이언트 암호에서 새 클라이언트 암호를 선택하고 이름을 입력한 다음, 추가를 선택합니다. 이후 단계에서 사용할 수 있도록 안전한 위치에 비밀 값을 기록합니다.
8. 관리에서 API 권한>권한 추가를 선택합니다. Microsoft Graph를 선택합니다.
9. 애플리케이션 권한 선택.
10. 사용자 노드 아래에서 User.Read.All을 선택한 다음, 권한 추가를 선택합니다.

2단계: Node.js 샘플 프로젝트 다운로드

코드 샘플 다운로드

3단계: Node.js 샘플 프로젝트 구성

1. zip 파일을 디스크 루트에 가까운 로컬 폴더(예: C:/Azure-Samples)로 추출합니다.

2. .env를 편집하고 TENANT_ID, CLIENT_ID 및 CLIENT_SECRET 필드의 값을 다음 코드 조각으로 바꿉니다.

   "TENANT_ID": "Enter_the_Tenant_Id_Here",
   "CLIENT_ID": "Enter_the_Application_Id_Here",
   "CLIENT_SECRET": "Enter_the_Client_Secret_Here"
   

   여기서

   • Enter_the_Application_Id_Here - 이전에 등록한 애플리케이션의 애플리케이션(클라이언트) ID입니다. 앱 등록의 개요에서 이 ID를 찾습니다.
   • Enter_the_Tenant_Id_Here - 이 값을 테넌트 ID 또는 테넌트 이름(예: contoso.microsoft.com)으로 바꿉니다. 앱 등록의 개요에서 이 값을 찾습니다.
   • Enter_the_Client_Secret_Here - 이 값을 이전에 만든 클라이언트 암호로 바꿉니다. 새 키를 생성하려면 앱 등록 설정에서 인증서 및 비밀을 사용합니다.

   소스 코드에서 일반 텍스트 비밀을 사용하면 애플리케이션에 대한 보안 위험을 가중시킵니다. 이 빠른 시작의 샘플은 일반 텍스트 클라이언트 암호를 사용하지만 단순성을 위해서만 사용됩니다. 기밀 클라이언트 애플리케이션(특히 프로덕션 환경에 배포하려는 앱)에는 클라이언트 암호 대신 인증서 자격 증명을 사용하는 것이 좋습니다.

3. .env를 편집하고 Microsoft Entra ID 및 Microsoft Graph 엔드포인트를 다음 값으로 바꿉니다.

   • Microsoft Entra 엔드포인트의 경우 Enter_the_Cloud_Instance_Id_Here를 https://login.microsoftonline.com으로 바꿉니다.
   • Microsoft Graph 엔드포인트의 경우 Enter_the_Graph_Endpoint_Here를 https://graph.microsoft.com/으로 바꿉니다.

4단계: 관리자 동의

이 시점에서 애플리케이션을 실행하려고 시도하면 HTTP 403 - 사용할 수 없음 오류: Insufficient privileges to complete the operation 메시지가 표시됩니다. 이 오류는 모든 앱 전용 권한에 관리자 동의가 필요하기 때문에 발생합니다. 즉, 애플리케이션 관리자 또는 전역 관리자가 애플리케이션에 동의해야 합니다. 역할에 따라 아래 옵션 중 하나를 선택합니다.

관리자

애플리케이션 관리자 또는 글로벌 관리자 역할이 할당된 경우 Azure Portal 애플리케이션 등록의 API 권한 페이지로 이동하여 {테넌트 이름}에 대한 관리자 동의 부여(여기서 {테넌트 이름}은 디렉터리 이름)를 선택합니다.

표준 사용자

테넌트의 표준 사용자인 경우 Global 관리istrator에게 애플리케이션에 대한 관리자 동의를 부여하도록 요청해야 합니다. 이렇게 하려면 관리자에게 다음 URL을 제공합니다.

https://login.microsoftonline.com/Enter_the_Tenant_Id_Here/adminconsent?client_id=Enter_the_Application_Id_Here

여기서

• Enter_the_Tenant_Id_Here - 이 값을 테넌트 ID 또는 테넌트 이름(예: contoso.microsoft.com)으로 바꿉니다.
• Enter_the_Application_Id_Here - 등록한 애플리케이션의 애플리케이션(클라이언트) ID입니다.

5단계: 애플리케이션 실행

명령 프롬프트 또는 콘솔에서 package.json이 있는 샘플의 루트 폴더를 찾습니다. 처음으로 실행하기 전에 샘플 앱에 필요한 종속성을 설치해야 합니다.

npm install

그런 다음, 명령 프롬프트 또는 콘솔을 통해 애플리케이션을 실행합니다.

node . --op getUsers

콘솔에서 Microsoft Entra 디렉터리의 사용자 목록을 나타내는 일부 JSON 조각을 출력하는 것을 볼 수 있습니다.

코드 정보

아래에서는 애플리케이션 예제의 몇 가지 중요한 측면에 대해 설명합니다.

MSAL 노드

MSAL Node는 사용자를 로그인시키고 Microsoft ID 플랫폼으로 보호되는 API 액세스에 사용되는 토큰을 요청할 때 사용되는 라이브러리입니다. 설명한 것과 같이 이 빠른 시작은 위임된 권한 대신 애플리케이션 권한(애플리케이션 소유 ID 사용)으로 토큰을 요청합니다. 이 경우에 사용되는 인증 흐름을 OAuth 2.0 클라이언트 자격 증명 흐름이라고 합니다. 디먼 앱에서 MSAL Node를 사용하는 방법에 대한 자세한 내용은 시나리오: 디먼 애플리케이션을 참조하세요.

다음 npm 명령을 실행하여 MSAL Node를 설치할 수 있습니다.

npm install @azure/msal-node --save

MSAL 초기화

다음 코드를 추가하여 MSAL에 대한 참조를 추가할 수 있습니다.

const msal = require('@azure/msal-node');

그런 다음, 아래 코드를 사용하여 MSAL을 초기화합니다.

const msalConfig = {
    auth: {
        clientId: "Enter_the_Application_Id_Here",
        authority: "https://login.microsoftonline.com/Enter_the_Tenant_Id_Here",
        clientSecret: "Enter_the_Client_Secret_Here",
   }
};
const cca = new msal.ConfidentialClientApplication(msalConfig);

여기서	설명
clientId	Azure Portal에 등록된 애플리케이션의 애플리케이션(클라이언트) ID입니다. 이 값은 Azure Portal에서 앱의 개요 페이지에 있습니다.
authority	사용자가 인증하는 STS 엔드포인트 일반적으로 퍼블릭 클라우드에 대한 https://login.microsoftonline.com/{tenant}입니다. 여기서 {tenant}는 테넌트의 이름 또는 테넌트 ID입니다.
clientSecret	Azure Portal에서 애플리케이션에 대한 클라이언트 암호가 생성됩니다.

자세한 내용은 ConfidentialClientApplication에 대한 참조 설명서를 참조하세요.

토큰 요청

앱의 ID를 사용하여 토큰을 요청하려면 acquireTokenByClientCredential 메서드를 사용합니다.

const tokenRequest = {
    scopes: [ 'https://graph.microsoft.com/.default' ],
};

const tokenResponse = await cca.acquireTokenByClientCredential(tokenRequest);

여기서	설명
tokenRequest	요청된 범위를 포함합니다. 기밀 클라이언트의 경우 요청되는 범위가 Azure Portal에서 설정된 앱 개체에서 정적으로 정의된 것임을 나타내기 위해 {Application ID URI}/.default와 유사한 양식을 사용해야 합니다(Microsoft Graph의 경우 {Application ID URI}는 https://graph.microsoft.com을 가리킴). 사용자 지정 웹 API의 경우 {Application ID URI}는 Azure Portal의 애플리케이션 등록에서 API 노출 섹션 아래에 정의됩니다.
tokenResponse	응답에는 요청된 범위에 대한 액세스 토큰이 포함되어 있습니다.

도움말 및 지원 

도움이 필요하거나, 문제를 보고하거나, 지원 옵션에 대해 알아보려면 개발자를 위한 도움말 및 지원을 참조하세요.

다음 단계

MSAL Node를 사용한 디먼/콘솔 앱 개발에 대해 자세히 알아보려면 다음 자습서를 참조하세요.

웹 API를 호출하는 디먼 애플리케이션