JavaScript용 Azure ID 클라이언트 라이브러리 - 버전 4.1.0

Azure ID 라이브러리는 편리한 TokenCredential 구현 집합을 통해 Microsoft Entra ID(이전의 Azure Active Directory) 토큰 인증을 제공합니다.

다양한 자격 증명의 예제는 Azure ID 예제 페이지를 참조하세요.

주요 링크:

시작

v1에서 v2로 마이그레이션 @azure/identity

@azure/identityv1을 사용하는 경우 v2로 업데이트하는 마이그레이션 가이드 를 참조하세요.

현재 지원되는 환경

  • Node.js의 LTS 버전
    • 참고: 애플리케이션이 Node.js v8 이하에서 실행되고 Node.js 버전을 안정적인 최신 버전으로 업그레이드할 수 없는 경우 종속성을 버전 1.1.0에 고정합니다 @azure/identity .
  • 최신 버전의 Safari, Chrome, Edge, Firefox.
    • 참고: 이 라이브러리 InteractiveBrowserCredential 에서 내보낸 다양한 자격 증명 중 은 브라우저에서 지원되는 유일한 자격 증명입니다.

자세한 내용은 지원 정책을 참조하세요.

패키지 설치

npm으로 Azure ID를 설치합니다.

npm install --save @azure/identity

사전 요구 사항

@azure/identity를 사용하는 경우

에서 노출하는 @azure/identity 자격 증명 클래스는 로컬, 개발 환경 및 프로덕션 환경에서 Azure SDK 클라이언트를 인증하는 가장 간단한 방법을 제공하는 데 중점을 줍니다. Azure에서 가능한 대부분의 인증 시나리오를 다루기 위해 인증 프로토콜의 단순성과 합리적인 지원을 목표로 합니다. 더 많은 시나리오를 다루기 위해 적극적으로 확장하고 있습니다. 제공되는 자격 증명의 전체 목록은 자격 증명 클래스 섹션을 참조하세요 .

에서 제공하는 @azure/identity 모든 자격 증명 형식은 Node.js 지원됩니다. 브라우저의 InteractiveBrowserCredential 경우 는 기본 인증 시나리오에 사용할 자격 증명 유형입니다.

에서 제공하는 @azure/identity 대부분의 자격 증명 형식은 MSAL.js(JavaScript용 Microsoft 인증 라이브러리)를 사용합니다. 특히 PKCE와 함께 OAuth 2.0 인증 코드 흐름을 사용하고 OpenID 규격인 v2 MSAL.js 라이브러리를 사용합니다. 단순성에 중점을 두지만 @azure/identity @azure/msal-common, @azure/msal-node 및 @azure/msal-browser와 같은 MSAL.js 라이브러리는 Azure에서 지원하는 인증 프로토콜에 대한 강력한 지원을 제공하도록 설계되었습니다.

다른 항목을 사용해야 하는 경우

자격 증명 형식은 @azure/identity@azure/core-auth 클래스의 구현입니다 TokenCredential . 원칙에 따라 충족 getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null> 하는 메서드가 있는 getToken 모든 개체는 로 TokenCredential작동합니다. 즉, 개발자는 에서 다루지 @azure/identity않는 인증 사례를 지원하기 위해 자체 자격 증명 형식을 작성할 수 있습니다. 자세한 내용은 사용자 지정 자격 증명을 참조하세요.

자격 증명 유형은 많은 고급 사례를 지원하지만 개발자는 인증 프로토콜을 완전히 제어하기를 원할 수 있습니다. 이 사용 사례의 경우 JavaScript용 Microsoft 인증 라이브러리(MSAL.js) 를 직접 사용하는 것이 좋습니다. 다음 링크를 통해 자세히 읽을 수 있습니다.

브라우저의 고급 인증 워크플로의 경우 @azure/msal-browser 라이브러리를 직접 사용하여 Azure SDK 클라이언트를 인증하는 방법을 보여 주는 섹션이 있습니다.

개발 환경에서 클라이언트 인증

프로덕션 애플리케이션에서 관리 ID 또는 서비스 주체 인증을 사용하는 것이 좋습니다. 개발자는 코드를 로컬로 디버깅하고 실행할 때 Azure 서비스에 대한 호출을 인증하는 데 고유한 계정을 사용하는 것이 일반적입니다. 개발 환경에서 이 인증을 수행하는 데 사용할 수 있는 몇 가지 개발자 도구가 있습니다.

Azure Developer CLI 통해 인증

IDE 외부에서 코딩하는 개발자는 [Azure Developer CLI][azure_developer_cli]를 사용하여 인증할 수도 있습니다. 그러면 DefaultAzureCredential 또는 AzureDeveloperCliCredential을 사용하는 애플리케이션이 이 계정을 사용하여 로컬에서 실행할 때 애플리케이션에서 호출을 인증할 수 있습니다.

[Azure Developer CLI][azure_developer_cli]로 인증하려면 사용자가 명령을 azd auth login실행할 수 있습니다. 기본 웹 브라우저가 있는 시스템에서 실행되는 사용자의 경우 Azure Developer CLI 브라우저를 시작하여 사용자를 인증합니다.

기본 웹 브라우저가 없는 시스템의 경우 azd auth login --use-device-code 명령은 디바이스 코드 인증 흐름을 사용합니다.

Azure CLI를 통해 인증

를 사용하는 애플리케이션은 AzureCliCredential직접 또는 를 통해 DefaultAzureCredentialAzure CLI 계정을 사용하여 로컬로 실행할 때 애플리케이션에서 호출을 인증할 수 있습니다.

Azure CLI 사용자를 인증하려면 az login 명령을 실행할 수 있습니다. 기본 웹 브라우저가 있는 시스템에서 실행되는 사용자의 경우 Azure CLI는 브라우저를 시작하여 사용자를 인증합니다.

Azure CLI 계정 로그인

기본 웹 브라우저가 없는 시스템의 경우 az login 명령은 디바이스 코드 인증 흐름을 사용합니다. 또한 사용자는 --use-device-code 인수를 지정하여 브라우저를 시작하는 대신 Azure CLI에서 디바이스 코드 흐름을 사용하도록 강제할 수 있습니다.

Azure CLI 계정 디바이스 코드 로그인

Azure PowerShell 통해 인증

를 직접 사용하든 를 통해DefaultAzureCredential든 를 사용하는 AzurePowerShellCredential애플리케이션은 로컬로 실행할 때 Azure PowerShell 연결된 계정을 사용하여 애플리케이션에서 호출을 인증할 수 있습니다.

Azure PowerShell 인증하려면 사용자가 cmdlet을 Connect-AzAccount 실행할 수 있습니다. 기본적으로 Azure CLI Connect-AzAccount ike는 기본 웹 브라우저를 시작하여 사용자 계정을 인증합니다.

Azure PowerShell 계정 로그인

세션에서 -UseDeviceAuthentication 대화형 인증을 지원 할 수없는 경우 인수는 azure CLI 자격 증명의 해당 옵션과 유사하게 cmdlet이 디바이스 코드 인증 흐름을 대신 사용하도록 강제합니다.

Visual Studio Code 통해 인증

Visual Studio Code 사용하는 개발자는 Azure 계정 확장을 사용하여 편집기를 통해 인증할 수 있습니다. 그런 다음 를 사용하는 VisualStudioCodeCredential 앱은 이 계정을 사용하여 로컬로 실행할 때 앱에서 호출을 인증할 수 있습니다.

Visual Studio Code 인증하려면 Azure 계정 확장이 설치되어 있는지 확인합니다. 설치되면 명령 팔레트 를 열고 Azure: 로그인 명령을 실행합니다.

또한 플러그 인 패키지를 사용합니다 @azure/identity-vscode . 이 패키지는 의 VisualStudioCodeCredential 종속성을 제공하고 사용하도록 설정합니다. 플러그 인을 참조하세요.

Azure 계정 확장 버전이 VisualStudioCodeCredential0.9.11보다 최신 버전에서 작동하지 않는 알려진 문제입니다. 이 문제에 대한 장기적인 수정이 진행 중입니다. 그 동안 Azure CLI를 통해 인증하는 것이 좋습니다.

브라우저에서 클라이언트 인증

웹 브라우저 내에서 Azure SDK 클라이언트를 인증하기 위해 리디렉션 또는 팝업을 사용하여 인증 흐름을 완료하도록 설정할 수 있는 를 제공합니다 InteractiveBrowserCredential. 먼저 웹 애플리케이션에 대한 Azure Portal Azure 앱 등록을 만들어야 합니다.

주요 개념

처음 사용 @azure/identity 하거나 Microsoft Entra ID 경우 먼저 Microsoft Entra ID 사용을 @azure/identity 참조하세요. 이 문서에서는 플랫폼과 Azure 계정을 올바르게 구성하는 방법에 대한 심층적인 이해를 제공합니다.

자격 증명

자격 증명은 서비스 클라이언트가 요청을 인증하는 데 필요한 데이터를 포함하고 있거나 획득할 수 있는 클래스입니다. Azure SDK의 서비스 클라이언트는 생성될 때 자격 증명을 허용합니다. 서비스 클라이언트는 이러한 자격 증명을 사용하여 서비스에 대한 요청을 인증합니다.

Azure ID 라이브러리는 Microsoft Entra ID 사용한 OAuth 인증에 중점을 두고 있으며, 서비스 요청을 인증하기 위해 Microsoft Entra 토큰을 획득할 수 있는 다양한 자격 증명 클래스를 제공합니다. 이 라이브러리의 모든 자격 증명 클래스는 TokenCredential 추상 클래스의 구현이며, TokenCredential로 인증할 수 있는 서비스 클라이언트를 구성하는 데 사용할 수 있습니다.

자격 증명 클래스를 참조하세요.

DefaultAzureCredential

DefaultAzureCredential 애플리케이션이 궁극적으로 Azure에서 실행되도록 의도된 대부분의 시나리오에 적합합니다. 은 DefaultAzureCredential 개발 환경에서 인증하는 데 사용되는 자격 증명과 함께 배포될 때 일반적으로 인증하는 데 사용되는 자격 증명을 결합하기 때문입니다.

참고: DefaultAzureCredential 적절한 기본 동작으로 일반적인 시나리오를 처리하여 SDK 시작을 간소화하기 위한 것입니다. 더 많은 제어를 원하거나 자신의 시나리오가 기본 설정에서 제공되지 않는 개발자는 다른 자격 증명 형식을 사용해야 합니다.

Node.js 사용하는 경우 는 DefaultAzureCredential 다음 메커니즘을 통해 순서대로 인증을 시도합니다.

DefaultAzureCredential 인증 흐름

  1. 환경 - 는 DefaultAzureCredential환경 변수 를 통해 지정된 계정 정보를 읽고 이를 사용하여 인증합니다.
  2. 워크로드 ID - 애플리케이션이 관리 ID를 사용하도록 설정된 Azure Kubernetes Service 배포된 DefaultAzureCredential 경우 에서 인증합니다.
  3. 관리 ID - 애플리케이션이 관리 ID를 사용하도록 설정된 Azure 호스트에 배포된 DefaultAzureCredential 경우 는 해당 계정으로 인증됩니다.
  4. Azure CLI - 개발자가 Azure CLI az login 명령을 통해 계정을 인증한 경우 는 DefaultAzureCredential 해당 계정으로 인증합니다.
  5. Azure PowerShell - 개발자가 Azure PowerShell 모듈 Connect-AzAccount 명령을 DefaultAzureCredential 사용하여 인증한 경우 는 해당 계정으로 인증됩니다.
  6. Azure Developer CLI - 개발자가 Azure Developer CLI azd auth login 명령을 DefaultAzureCredential 통해 계정을 인증한 경우 는 해당 계정으로 인증됩니다.

연속 정책

버전 3.3.0을 기준으로 는 DefaultAzureCredential 이전 개발자 자격 증명에서 발생한 오류에 관계없이 성공할 때까지 모든 개발자 자격 증명으로 인증을 시도합니다. 예를 들어 개발자 자격 증명은 토큰을 가져와 실패하려고 시도할 수 있으므로 DefaultAzureCredential 흐름의 다음 자격 증명으로 계속 진행됩니다. 배포된 서비스 자격 증명은 토큰 검색을 시도할 수 있지만 수신하지 않는 경우 throw된 예외로 흐름을 중지합니다.

이렇게 하면 예측 가능한 배포된 동작이 있는 동안 머신에서 모든 개발자 자격 증명을 시도할 수 있습니다.

참고 정보 VisualStudioCodeCredential

알려진 문제로VisualStudioCodeCredential 인해 이 토큰 체인에서 DefaultAzureCredential 제거되었습니다. 이후 릴리스에서 문제가 해결되면 이 변경 내용이 되돌려집니다.

플러그 인

JavaScript용 Azure ID는 별도의 플러그 인 패키지를 통해 특정 기능을 제공할 수 있는 플러그 인 API를 제공합니다. 패키지는 @azure/identity 플러그 인을 사용하도록 설정하는 데 사용할 수 있는 최상위 함수(useIdentityPlugin)를 내보냅니다. 다음 두 가지 플러그 인 패키지를 제공합니다.

  • @azure/identity-broker- 웹 계정 관리자와 같은 네이티브 브로커를 통해 조정된 인증 지원을 제공합니다.
  • @azure/identity-cache-persistence운영 체제에서 제공하는 네이티브 보안 스토리지 시스템을 사용하여 Node.js 영구 토큰 캐싱을 제공합니다. 이 플러그 인을 사용하면 캐시된 access_token 값을 세션 간에 유지할 수 있습니다. 즉, 캐시된 토큰을 사용할 수 있는 한 대화형 로그인 흐름을 반복할 필요가 없습니다.

예제

Azure ID 예제 페이지에서 다양한 자격 증명을 사용하는 더 많은 예제를 찾을 수 있습니다.

다음을 사용하여 인증 DefaultAzureCredential

이 예제에서는 를 사용하여 @azure/keyvault-keys 클라이언트 라이브러리에서 를 인증하는 KeyClient 방법을 보여 줍니다DefaultAzureCredential.

// The default credential first checks environment variables for configuration as described above.
// If environment configuration is incomplete, it will try managed identity.

// Azure Key Vault service to use
import { KeyClient } from "@azure/keyvault-keys";

// Azure authentication library to access Azure Key Vault
import { DefaultAzureCredential } from "@azure/identity";

// Azure SDK clients accept the credential as a parameter
const credential = new DefaultAzureCredential();

// Create authenticated client
const client = new KeyClient(vaultUrl, credential);

다음을 사용하여 사용자 할당 관리 ID를 지정합니다. DefaultAzureCredential

비교적 일반적인 시나리오에는 Azure 리소스에 대해 사용자가 할당한 관리 ID를 사용하여 인증하는 작업이 포함됩니다. DefaultAzureCredential을 사용하여 사용자 할당 관리 ID 인증의 예제를 탐색하여 환경 변수 또는 코드에서 구성할 수 있는 비교적 간단한 작업을 만드는 방법을 알아봅니다.

ChainedTokenCredential을 사용하여 사용자 지정 인증 흐름 정의

DefaultAzureCredential이 일반적으로 Azure용 애플리케이션 개발을 시작하는 가장 빠른 방법이지만, 고급 사용자는 인증할 때 고려되는 자격 증명을 사용자 지정할 수 있습니다. ChainedTokenCredential을 사용하면 사용자가 여러 자격 증명 인스턴스를 결합하여 사용자 지정 자격 증명 체인을 정의할 수 있습니다. 이 예제에서는 의 서로 다르게 구성된 두 인스턴스ClientSecretCredential를 사용하여 인증을 시도한 다음, @azure/keyvault-keys에서 를 인증 KeyClient 하는 을 만드는 ChainedTokenCredential 방법을 보여 줍니다.

import { ClientSecretCredential, ChainedTokenCredential } from "@azure/identity";

// When an access token is requested, the chain will try each
// credential in order, stopping when one provides a token
const firstCredential = new ClientSecretCredential(tenantId, clientId, clientSecret);
const secondCredential = new ClientSecretCredential(tenantId, anotherClientId, anotherSecret);
const credentialChain = new ChainedTokenCredential(firstCredential, secondCredential);

// The chain can be used anywhere a credential is required
import { KeyClient } from "@azure/keyvault-keys";
const client = new KeyClient(vaultUrl, credentialChain);

관리 ID 지원

관리 ID 인증은 다음 Azure 서비스에 대해 또는 ManagedIdentityCredential 자격 증명 클래스를 통해 DefaultAzureCredential 직접 지원됩니다.

인증에 관리 ID를 사용하는 방법에 대한 예제는 예제를 참조하세요.

클라우드 구성

자격 증명은 기본적으로 Azure 퍼블릭 클라우드에 대한 Microsoft Entra 엔드포인트에 인증합니다. Azure Government 또는 프라이빗 클라우드와 같은 다른 클라우드의 리소스에 액세스하려면 생성자의 인수를 사용하여 authorityHost 자격 증명을 구성합니다. 인터페이스는 AzureAuthorityHosts 잘 알려진 클라우드에 대한 기관을 정의합니다. 미국 정부 클라우드의 경우 다음과 같이 자격 증명을 인스턴스화할 수 있습니다.

import { AzureAuthorityHosts, ClientSecretCredential } from "@azure/identity";
const credential = new ClientSecretCredential(
  "<YOUR_TENANT_ID>",
  "<YOUR_CLIENT_ID>",
  "<YOUR_CLIENT_SECRET>",
  {
    authorityHost: AzureAuthorityHosts.AzureGovernment,
  }
);

모든 자격 증명에 이 구성이 필요한 것은 아닙니다. 와 같은 AzureCliCredential개발 도구를 통해 인증하는 자격 증명은 해당 도구의 구성을 사용합니다. 마찬가지로 는 VisualStudioCodeCredential 인수를 authorityHost 수락하지만 기본적으로 authorityHost 일치하는 Visual Studio Code Azure: 클라우드 설정으로 설정됩니다.

자격 증명 클래스

Azure 호스팅 애플리케이션 인증

자격 증명 사용법 예제
DefaultAzureCredential Azure에서 실행되는 애플리케이션 개발을 빠르게 시작하는 간소화된 인증 환경을 제공합니다. 예제
ChainedTokenCredential 사용자가 여러 자격 증명을 구성하는 사용자 지정 인증 흐름을 정의할 수 있습니다. 예제
EnvironmentCredential 환경 변수에 지정된 자격 증명 정보를 통해 서비스 주체 또는 사용자를 인증합니다. 예제
ManagedIdentityCredential Azure 리소스의 관리 ID를 인증합니다. 예제
WorkloadIdentityCredential Kubernetes에서 Microsoft Entra 워크로드 ID를 지원합니다. 예제

서비스 주체 인증

자격 증명 사용법 예제 참조
ClientAssertionCredential 서명된 클라이언트 어설션을 사용하여 서비스 주체를 인증합니다. 예제 서비스 주체 인증
ClientCertificateCredential 인증서를 사용하여 서비스 주체를 인증합니다. 예제 서비스 주체 인증
ClientSecretCredential 비밀을 사용하여 서비스 주체를 인증합니다. 예제 서비스 주체 인증

사용자 인증

자격 증명 사용법 예제 참조
AuthorizationCodeCredential 이전에 가져온 권한 부여 코드를 사용하여 사용자를 인증합니다. 예제 OAuth2 인증 코드
DeviceCodeCredential UI가 제한된 디바이스에서 사용자를 대화형으로 인증합니다. 예제 디바이스 코드 인증
InteractiveBrowserCredential 기본 시스템 브라우저를 사용하여 사용자를 대화형으로 인증합니다. 여기서 어떻게 이런 일이 일어나는지 자세히 알아보세요. 예제 OAuth2 인증 코드
OnBehalfOfCredential 요청 체인을 통해 위임된 사용자 ID 및 권한을 전파합니다. On-Behalf-Of 인증
UsernamePasswordCredential 사용자 이름 및 암호를 사용하여 사용자를 인증합니다. 예제 사용자 이름 + 암호 인증

개발 도구를 통해 인증

자격 증명 사용법 예제 참조
AzureCliCredential Azure CLI를 사용하여 개발 환경에서 인증합니다. 예제 Azure CLI 인증
AzureDeveloperCliCredential Azure Developer CLI 사용하도록 설정된 사용자 또는 서비스 주체를 사용하여 개발 환경에서 인증합니다. Azure Developer CLI 참조
AzurePowerShellCredential Azure PowerShell 사용하여 개발 환경에서 인증합니다. 예제 Azure PowerShell 인증
VisualStudioCodeCredential 사용자가 Visual Studio Code Azure 계정 확장에 로그인한 것으로 인증합니다. VS Code Azure 계정 확장

환경 변수

DefaultAzureCredentialEnvironmentCredential은 환경 변수로 구성할 수 있습니다. 각 인증 유형에는 특정 변수에 대한 값이 필요합니다.

비밀을 사용하는 서비스 주체

변수 이름
AZURE_CLIENT_ID Microsoft Entra 애플리케이션의 ID
AZURE_TENANT_ID 애플리케이션의 Microsoft Entra 테넌트의 ID
AZURE_CLIENT_SECRET 애플리케이션의 클라이언트 암호 중 하나

인증서를 사용하는 서비스 주체

변수 이름
AZURE_CLIENT_ID Microsoft Entra 애플리케이션의 ID
AZURE_TENANT_ID 애플리케이션의 Microsoft Entra 테넌트의 ID
AZURE_CLIENT_CERTIFICATE_PATH 프라이빗 키를 포함하여 PEM으로 인코딩된 인증서 파일의 경로
AZURE_CLIENT_CERTIFICATE_PASSWORD 인증서 파일의 암호(있는 경우)

사용자 이름 및 암호

변수 이름
AZURE_CLIENT_ID Microsoft Entra 애플리케이션의 ID
AZURE_TENANT_ID 애플리케이션의 Microsoft Entra 테넌트의 ID
AZURE_USERNAME 사용자 이름(일반적으로 메일 주소)
AZURE_PASSWORD 해당 사용자 암호

위의 순서대로 구성이 시도됩니다. 예를 들어 클라이언트 암호 및 인증서 값이 모두 있는 경우 클라이언트 암호가 사용됩니다.

지속적인 액세스 평가

버전 3.3.0을 기준으로 요청별로 CAE( 지속적인 액세스 평가 )로 보호되는 리소스에 액세스할 수 있습니다. API를 사용하여 GetTokenOptions.enableCae(boolean)사용하도록 설정할 수 있습니다. CAE는 개발자 자격 증명에 대해 지원되지 않습니다.

토큰 캐싱

토큰 캐싱은 앱에서 다음을 수행할 수 있도록 하는 Azure ID 라이브러리에서 제공하는 기능입니다.

  • 메모리(기본값) 및 디스크의 캐시 토큰(옵트인).
  • 복원력 및 성능을 개선합니다.
  • 액세스 토큰을 가져오기 위해 Microsoft Entra ID 요청 수를 줄입니다.

Azure ID 라이브러리는 메모리 내 및 영구 디스크 캐싱을 모두 제공합니다. 자세한 내용은 토큰 캐싱 설명서를 참조하세요.

조정된 인증

인증 브로커는 사용자의 컴퓨터에서 실행되고 연결된 계정에 대한 인증 핸드셰이크 및 토큰 유지 관리를 관리하는 애플리케이션입니다. 현재 WAM(Windows 웹 계정 관리자)만 지원됩니다. 지원을 사용하도록 설정하려면 패키지를 사용합니다 @azure/identity-broker . WAM을 사용하여 인증하는 방법에 대한 자세한 내용은 broker 플러그 인 설명서를 참조하세요.

문제 해결

문제 해결에 대한 지원은 문제 해결 가이드를 참조하세요.

다음 단계

설명서 읽기

이 라이브러리에 대한 API 설명서는 설명서 사이트에서 찾을 수 있습니다.

클라이언트 라이브러리 지원

Microsoft Entra 인증을 지원하는 Azure SDK 릴리스 페이지에 나열된 클라이언트 및 관리 라이브러리는 이 라이브러리의 자격 증명을 수락합니다. 릴리스 페이지에서 연결된 설명서에서 이러한 라이브러리를 사용하는 방법에 대해 자세히 알아봅니다.

알려진 문제

Azure AD B2C 지원

이 라이브러리는 Azure AD B2C 서비스를 지원하지 않습니다.

열려 있는 다른 문제는 라이브러리의 GitHub 리포지토리를 참조하세요.

피드백 제공

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

참여

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

Impressions