다음을 통해 공유

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

  • 아티클

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

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

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

시작

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

useIdentityPlugin(nativeBrokerPlugin);

필수 구성 요소

패키지 설치

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

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

지원되는 환경

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

주요 개념

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

부모 창 핸들

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

MSA(Microsoft 계정) 통과

MSA(Microsoft 계정)는 사용자가 Microsoft 서비스에 액세스하기 위해 만든 개인 계정입니다. MSA 통과는 사용자가 일반적으로 MSA 로그인을 허용하지 않는 리소스에 토큰을 가져올 수 있도록 하는 레거시 구성입니다. 이 기능은 자사 애플리케이션에서만 사용할 수 있습니다. MSA 통과를 사용하도록 구성된 애플리케이션으로 인증하는 사용자는 내부 InteractiveBrowserCredentialNodeOptions.brokerOptions 로 true 설정 legacyEnableMsaPassthrough 하여 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 { nativeBrokerPlugin } from "@azure/identity-broker";
import { useIdentityPlugin, InteractiveBrowserCredential } from "@azure/identity";

useIdentityPlugin(nativeBrokerPlugin);

const credential = new InteractiveBrowserCredential({
  brokerOptions: {
    enabled: true,
  },
});

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

예제

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

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

useIdentityPlugin(nativeBrokerPlugin);

async function main() {
  const credential = new InteractiveBrowserCredential({
    brokerOptions: {
      enabled: true,
      parentWindowHandle: <insert_current_window_handle>
    },
  });

  // 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), "...");
}

main().catch((error) => {
  console.error("An error occurred:", error);
  process.exit(1);
});

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

로그인에 기본 계정 사용

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

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

useIdentityPlugin(nativeBrokerPlugin);

async function main() {
  const credential = new InteractiveBrowserCredential({
    brokerOptions: {
      enabled: true,
      useDefaultBrokerAccount: true,
      parentWindowHandle: <insert_current_window_handle>
    },
  });

  // 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), "...");
}

main().catch((error) => {
  console.error("An error occurred:", error);
  process.exit(1);
});

문제 해결

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

로깅

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

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

setLogLevel("info");

다음 단계

피드백 제공

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

참여

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

Impressions