조정된 인증을 위한 Azure ID 플러그 인

이 패키지는 @azure/identity같은 인증 브로커를 사용할 수 있도록 하는 JavaScript()용 Azure ID 라이브러리에 플러그 인을 제공합니다.

인증 브로커는 연결된 계정에 대한 인증 핸드셰이크 및 토큰 유지 관리를 관리하는 사용자의 컴퓨터에서 실행되는 애플리케이션입니다. 현재 Windows 인증 브로커인 WAM(웹 계정 관리자)만 지원됩니다.

소스 코드 | 샘플 | API 참조 설명서 | [Microsoft Entra ID 설명서] (https://learn.microsoft.com/entra/identity/)

시작

import { useIdentityPlugin } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";

useIdentityPlugin(nativeBrokerPlugin);

필수 구성 요소

Azure 구독.

참고: 를 사용한 @azure/identity-broker로컬 개발의 경우 추가 도구를 설치해야 할 수 있습니다. node-gyp 는 시스템 API에 액세스하기 위한 애드온 을 컴파일하는 데 사용됩니다. 설치 요구 사항은 node-gyp README에 나열되어 있습니다.

Linux에서는 라이브러리가 사용 libsecret 하므로 설치해야 할 수도 있습니다. 배포에 따라 다음 명령을 실행해야 합니다.

데비안/우분투: sudo apt-get install libsecret-1-dev
Red Hat 기반: sudo yum install libsecret-devel
아치 리눅스: sudo pacman -S libsecret

비고

조정된 인증은 현재 Windows 및 Linux에서만 지원됩니다. macOS는 아직 지원되지 않습니다.

패키지 설치

이 패키지는 JavaScript용 Azure ID와 함께 사용하도록 설계되었습니다. @azure/identity사용하여 npm 및 이 패키지를 모두 설치합니다.

npm install --save @azure/identity
npm install --save @azure/identity-broker

지원되는 환경

JavaScript용 Azure ID 플러그 인은 v20부터 안정적이고 (짝수 번호) 버전의 Node.js 지원합니다. 플러그 인은 다른 Node.js 버전에서 실행될 수 있지만 지원은 보장되지 않습니다. @azure/identity-broker 브라우저 환경을 지원하지 않습니다.

주요 개념

또는 Microsoft Entra ID를 처음 사용하는 경우 먼저 Microsoft Entra ID 사용하는 읽어보는 것이 좋습니다. 이 문서에서는 플랫폼과 Azure 계정을 올바르게 구성하는 방법을 자세히 이해할 수 있습니다.

부모 창 핸들

InteractiveBrowserCredential통해 broker로 인증하는 경우 요청 창에 인증 대화 상자가 올바르게 표시되도록 하려면 부모 창 핸들이 필요합니다. 디바이스의 그래픽 사용자 인터페이스 컨텍스트에서 창 핸들은 운영 체제가 각 창에 할당하는 고유 식별자입니다. Windows 운영 체제의 경우 이 핸들은 특정 창에 대한 참조 역할을 하는 정수 값입니다.

MSA(Microsoft 계정) 통과

MSA(Microsoft 계정)는 사용자가 Microsoft 서비스에 액세스하기 위해 만든 개인 계정입니다. MSA 통과는 사용자가 일반적으로 MSA 로그인을 허용하지 않는 리소스에 토큰을 가져올 수 있도록 하는 레거시 구성입니다. 이 기능은 자사 애플리케이션에서만 사용할 수 있습니다. MSA 통과를 사용하도록 구성된 애플리케이션으로 인증하는 사용자는 legacyEnableMsaPassthrough 내에서 trueInteractiveBrowserCredentialNodeOptions.brokerOptions 설정하여 WAM에서 이러한 개인 계정을 나열할 수 있도록 할 수 있습니다.

리디렉션 URI

Microsoft Entra 애플리케이션은 리디렉션 URI를 사용하여 사용자가 로그인한 후 인증 응답을 보낼 위치를 결정합니다. WAM을 통해 조정된 인증을 사용하도록 설정하려면 다음 패턴과 일치하는 리디렉션 URI를 애플리케이션에 등록해야 합니다.

ms-appx-web://Microsoft.AAD.BrokerPlugin/{client_id}

Azure ID 플러그 인

@azure/identity 버전 2.0.0을 기준으로 JavaScript용 ID 클라이언트 라이브러리에는 플러그 인 API가 포함되어 있습니다. 이 패키지(@azure/identity-broker)는 인수로 전달해야 하는 플러그 인 개체를 useIdentityPlugin 패키지의 최상위 @azure/identity 함수로 내보냅니다. 다음과 같이 프로그램에서 네이티브 브로커를 사용하도록 설정합니다.

import { useIdentityPlugin, InteractiveBrowserCredential } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";

useIdentityPlugin(nativeBrokerPlugin);

const credential = new InteractiveBrowserCredential({
  brokerOptions: {
    enabled: true,
    parentWindowHandle: new Uint8Array(0), // This should be a handle to the parent window
  },
});

useIdentityPlugin호출한 후 네이티브 브로커 플러그 인은 @azure/identity 패키지에 등록되며 WAM broker 인증을 지원하는 InteractiveBrowserCredential 사용할 수 있습니다. 이 자격 증명은 생성자 옵션에서 brokerOptions.

참고: 버전 4.11.0-beta.1 DefaultAzureCredential 부터 @azure/identity Windows 웹 계정 관리자를 통한 로그인을 지원합니다. 다음과 같이 프로그램에서 네이티브 브로커를 사용하도록 설정합니다.

import { useIdentityPlugin, DefaultAzureCredential } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";

useIdentityPlugin(nativeBrokerPlugin);

const credential = new DefaultAzureCredential();

예제

플러그 인이 등록되면 자격 증명 생성자에 brokerOptionsenabled 속성이 설정된 true 전달하여 WAM broker 인증을 사용하도록 설정할 수 있습니다. 다음 예제에서는 InteractiveBrowserCredential사용합니다.

import { useIdentityPlugin, InteractiveBrowserCredential } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";

useIdentityPlugin(nativeBrokerPlugin);

const credential = new InteractiveBrowserCredential({
  brokerOptions: {
    enabled: true,
    parentWindowHandle: new Uint8Array(0), // This should be a handle to the parent window
  },
});

// We'll use the Microsoft Graph scope as an example
const scope = "https://graph.microsoft.com/.default";

// Print out part of the access token
console.log((await credential.getToken(scope)).token.substring(0, 10), "...");

창 핸들을 검색하기 위해 Electron 앱을 사용하는 전체 예제는 이 샘플참조하세요.

useDefaultBrokerAccount 옵션이 true설정되면 자격 증명은 기본 broker 계정을 자동으로 사용하려고 시도합니다. 기본 계정 사용이 실패하면 자격 증명이 대화형 인증으로 대체됩니다.

import { useIdentityPlugin, InteractiveBrowserCredential } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";

useIdentityPlugin(nativeBrokerPlugin);

const credential = new InteractiveBrowserCredential({
  brokerOptions: {
    enabled: true,
    useDefaultBrokerAccount: true,
    parentWindowHandle: new Uint8Array(0), // This should be a handle to the parent window
  },
});

// We'll use the Microsoft Graph scope as an example
const scope = "https://graph.microsoft.com/.default";

// Print out part of the access token
console.log((await credential.getToken(scope)).token.substr(0, 10), "...");

문제 해결

다양한 오류 시나리오를 진단하는 방법에 대한 자세한 내용은 Azure ID [문제 해결 가이드][https://github.com/Azure/azure-sdk-for-js/blob/@azure/identity-broker_1.3.0/sdk/identity/identity/TROUBLESHOOTING.md]를 참조하세요.

로깅

로깅을 사용하도록 설정하면 오류에 대한 유용한 정보를 파악하는 데 도움이 될 수 있습니다. HTTP 요청 및 응답 로그를 보려면 AZURE_LOG_LEVEL 환경 변수를 info설정합니다. 또는 setLogLevel@azure/logger 호출하여 런타임에 로깅을 사용하도록 설정할 수 있습니다.

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

다음 단계

피드백 제공

버그가 발생하거나 제안이 있는 경우문제를 여세요.

기여

이 라이브러리에 기여하려면 기여 가이드 참조하여 코드를 빌드하고 테스트하는 방법에 대해 자세히 알아보세요.

피드백

이 페이지가 도움이 되었나요?

Last updated on 2025-11-07