JavaScript용 Azure ID 클라이언트 라이브러리 - 버전 4.4.0
Azure ID 라이브러리는 편리한
다양한 자격 증명의 예는 Azure ID 예제 페이지참조하세요.
키 링크:
- 소스 코드
- 패키지(npm)
- API 참조 설명서
- microsoft Entra ID 설명서
- 샘플
시작
현재 지원되는 환경
-
LTS 버전의 Node.js
-
참고: 애플리케이션이 Node.js v8 이하에서 실행되고 Node.js 버전을 안정적인 최신 버전으로 업그레이드할 수 없는 경우
@azure/identity종속성을 버전 1.1.0에 고정합니다.
-
참고: 애플리케이션이 Node.js v8 이하에서 실행되고 Node.js 버전을 안정적인 최신 버전으로 업그레이드할 수 없는 경우
- Safari, Chrome, Edge 및 Firefox의 최신 버전입니다.
-
참고: 이 라이브러리에서 내보낸 다른 자격 증명 중에서
InteractiveBrowserCredential브라우저에서 지원되는 유일한 자격 증명입니다.
-
참고: 이 라이브러리에서 내보낸 다른 자격 증명 중에서
자세한 내용은 지원 정책 참조하세요.
패키지 설치
npm사용하여 Azure ID를 설치합니다.
npm install --save @azure/identity
필수 구성 요소
- Azure 구독.
- 선택 사항: Azure CLI 및/또는
Azure PowerShell 개발 환경에서 인증하고 계정 역할을 관리하는 데 유용할 수도 있습니다.
@azure/identity 사용하는 경우
@azure/identity 노출되는 자격 증명 클래스는 로컬, 개발 환경 및 프로덕션 환경에서 Azure SDK 클라이언트를 인증하는 가장 간단한 방법을 제공하는 데 중점을 두고 있습니다. Azure에서 가능한 대부분의 인증 시나리오를 포괄하는 인증 프로토콜의 단순성과 합리적인 지원을 목표로 합니다. 더 많은 시나리오를 다룰 수 있도록 적극적으로 확장하고 있습니다. 제공되는 자격 증명의 전체 목록은 자격 증명 클래스 섹션을 참조하세요.
@azure/identity 제공하는 모든 자격 증명 형식은 Node.js지원됩니다. 브라우저의 경우 InteractiveBrowserCredential 기본 인증 시나리오에 사용할 자격 증명 유형입니다.
@azure/identity 단순성에 중점을 두지만 @azure/msal-common, @azure/msal-node및 @azure/msal-browser같은 MSAL.js 라이브러리는 Azure에서 지원하는 인증 프로토콜에 대한 강력한 지원을 제공하도록 설계되었습니다.
다른 항목을 사용하는 경우
@azure/identity 자격 증명 형식은 @azure/코어 인증TokenCredential 클래스의 구현입니다. 원칙에 따라 getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null> 충족하는 getToken 메서드를 사용하는 모든 개체는 TokenCredential작동합니다. 즉, 개발자는 자체 자격 증명 형식을 작성하여 @azure/identity적용되지 않는 인증 사례를 지원할 수 있습니다. 자세한 내용은 사용자 지정 자격 증명
자격 증명 유형은 많은 고급 사례를 지원하지만 개발자는 인증 프로토콜을 완전히 제어하기를 원할 수 있습니다. 이 사용 사례의 경우 JavaScript용 Microsoft 인증 라이브러리(MSAL.js) 직접 사용하는 것이 좋습니다. 다음 링크를 통해 자세히 읽을 수 있습니다.
-
Azure ID 예제 페이지에서
@azure/identity고급 사용 사례를 설명합니다.- 여기서는 특히 고급 예제 섹션이 있습니다.
- MSAL로 인증을 직접
방법을 보여 주는 섹션도 있습니다.
브라우저의 고급 인증 워크플로의 경우 @azure/msal-browser 라이브러리를 직접 사용하여 Azure SDK 클라이언트를 인증하는 방법을 보여 주는 섹션이 있습니다.
개발 환경에서 클라이언트 인증
Azure 호스팅 애플리케이션에서 관리 ID를 사용하는 것이 좋습니다. 개발자는 코드를 로컬로 디버깅하고 실행할 때 Azure 서비스에 대한 호출을 인증하는 데 고유한 계정을 사용하는 것이 일반적입니다. 개발 환경에서 이 인증을 수행하는 데 사용할 수 있는 여러 개발자 도구가 있습니다.
Azure 개발자 CLI를 통해 인증
IDE 외부에서 코딩하는 개발자는 Azure Developer CLI 사용하여 인증할 수도 있습니다.
DefaultAzureCredential 또는 AzureDeveloperCliCredential 사용하는 애플리케이션은 로컬로 실행할 때 이 계정을 사용하여 애플리케이션에서 호출을 인증할 수 있습니다.
Azure Developer CLI
기본 웹 브라우저가 없는 시스템의 경우 azd auth login --use-device-code 명령은 디바이스 코드 인증 흐름을 사용합니다.
Azure CLI를 통해 인증
직접 또는 DefaultAzureCredential통해 AzureCliCredential사용하는 애플리케이션은 Azure 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 인증하려면 사용자가 Connect-AzAccount cmdlet을 실행할 수 있습니다. 기본적으로 Azure CLI와 마찬가지로 Connect-AzAccount 기본 웹 브라우저를 시작하여 사용자 계정을 인증합니다.
Azure PowerShell 계정 로그인
세션에서 대화형 인증을 지원하지 못하는 경우 -UseDeviceAuthentication 인수는 cmdlet이 Azure CLI 자격 증명의 해당 옵션과 유사하게 디바이스 코드 인증 흐름을 대신 사용하도록 강제합니다.
Visual Studio Code를 통해 인증
Visual Studio Code를 사용하는 개발자는 Azure 계정 확장 사용하여 편집기를 통해 인증할 수 있습니다. 그런 다음 VisualStudioCodeCredential 사용하는 앱은 이 계정을 사용하여 로컬로 실행할 때 앱에서 호출을 인증할 수 있습니다.
Visual Studio Code에서 인증하려면 Azure 계정 확장이 설치되어 있는지 확인합니다. 설치되면 명령 팔레트 열고 Azure: 로그인 명령을 실행합니다.
또한 @azure/identity-vscode 플러그 인 패키지를 사용합니다. 이 패키지는 VisualStudioCodeCredential 종속성을 제공하고 사용하도록 설정합니다. 플러그 인
브라우저에서 클라이언트 인증
웹 브라우저 내에서 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 다음 메커니즘을 통해 순서대로 인증을 시도합니다.
환경 -환경 변수를 통해 지정된 계정 정보를 읽고 이를 사용하여 인증합니다. -
워크로드 ID - 애플리케이션이 관리 ID를 사용하도록 설정된 Azure Kubernetes Service에 배포되는 경우
DefaultAzureCredential인증합니다. -
관리 ID - 애플리케이션이 관리 ID를 사용하도록 설정된 Azure 호스트에 배포된 경우
DefaultAzureCredential해당 계정으로 인증됩니다. - azure CLI
- 개발자가 Azure CLI 명령을 통해 계정을 인증한 경우 해당 계정으로 인증됩니다. - Azure PowerShell
- 개발자가 Azure PowerShell 모듈 명령을 사용하여 인증한 경우 해당 계정으로 인증됩니다. - Azure 개발자 CLI
- 개발자가 Azure Developer CLI 명령을 통해 계정을 인증한 경우 해당 계정으로 인증됩니다.
연속 정책
버전 3.3.0을 기준으로 DefaultAzureCredential 이전 개발자 자격 증명에 발생한 오류에 관계없이 성공할 때까지 모든 개발자 자격 증명으로 인증을 시도합니다. 예를 들어 개발자 자격 증명은 토큰을 가져오려고 시도하고 실패할 수 있으므로 DefaultAzureCredential 흐름의 다음 자격 증명으로 계속 진행됩니다. 배포된 서비스 자격 증명은 토큰 검색을 시도할 수 있지만 수신하지 않는 경우 throw된 예외로 흐름을 중지합니다.
이렇게 하면 예측 가능한 배포된 동작이 있는 동안 머신에서 모든 개발자 자격 증명을 시도할 수 있습니다.
VisualStudioCodeCredential 대한 참고 사항
알려진 문제인해 DefaultAzureCredential 토큰 체인에서 VisualStudioCodeCredential 제거되었습니다. 이후 릴리스에서 문제가 해결되면 이 변경 내용이 되돌려집니다.
플러그 인
JavaScript용 Azure ID는별도의 @azure/identity 패키지는 플러그 인을 사용하도록 설정하는 데 사용할 수 있는 최상위 함수(useIdentityPlugin)를 내보냅니다. 다음 두 가지 플러그 인 패키지를 제공합니다.
-
@azure/identity-broker- 웹 계정 관리자와 같은 네이티브 브로커를 통해 조정된 인증 지원을 제공합니다. -
@azure/identity-cache-persistence- 운영 체제에서 제공하는 네이티브 보안 스토리지 시스템을 사용하여 Node.js 영구 토큰 캐싱을 제공합니다. 이 플러그 인을 사용하면 캐시된access_token값이 세션 간에 유지되므로 캐시된 토큰을 사용할 수 있는 한 대화형 로그인 흐름을 반복할 필요가 없습니다.
예제
Azure ID 예제 페이지
DefaultAzureCredential 인증
이 예제에서는 DefaultAzureCredential사용하여 @azure/keyvault-keys 클라이언트 라이브러리에서 KeyClient 인증하는 방법을 보여 줍니다.
// 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);
DefaultAzureCredential 사용하여 사용자 할당 관리 ID 지정
비교적 일반적인 시나리오에는 Azure 리소스에 대해 사용자 할당 관리 ID를 사용하여 인증하는 작업이 포함됩니다. DefaultAzureCredential 사용하여 사용자 할당 관리 ID를 인증하는
ChainedTokenCredential 사용하여 사용자 지정 인증 흐름 정의
DefaultAzureCredential 일반적으로 Azure용 애플리케이션 개발을 시작하는 가장 빠른 방법이지만, 고급 사용자는 인증 시 고려되는 자격 증명을 사용자 지정할 수 있습니다. 이 ChainedTokenCredential 통해 사용자는 여러 자격 증명 인스턴스를 결합하여 사용자 지정된 자격 증명 체인을 정의할 수 있습니다. 이 예제에서는 다르게 구성된 두 ClientSecretCredential인스턴스를 사용하여 인증을 시도한 다음, @azure/keyvault-keysKeyClient 인증하는 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 서비스에 대해 직접 DefaultAzureCredential 또는 ManagedIdentityCredential 자격 증명 클래스를 통해 지원됩니다.
- Azure App Service 및 Azure Functions
- Azure Arc
- Azure Cloud Shell
- Azure Kubernetes Service
- Azure Service Fabric
- Azure Virtual Machines
- Azure Virtual Machines Scale Sets
인증에 관리 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같은 개발 도구를 통해 인증하는 자격 증명은 해당 도구의 구성을 사용합니다. 마찬가지로 VisualStudioCodeCredentialauthorityHost 인수를 허용하지만 기본적으로 Visual Studio Code의 Azure: 클라우드 설정과 일치하는 authorityHost 사용됩니다.
자격 증명 클래스
Azure 호스팅 애플리케이션 인증
| 자격 증명 | 사용법 | 본보기 |
|---|---|---|
DefaultAzureCredential |
Azure에서 실행되는 애플리케이션 개발을 빠르게 시작하는 간소화된 인증 환경을 제공합니다. | 예제 |
ChainedTokenCredential |
사용자가 여러 자격 증명을 구성하는 사용자 지정 인증 흐름을 정의할 수 있습니다. | 예제 |
EnvironmentCredential |
환경 변수에 지정된 자격 증명 정보를 통해 서비스 주체 또는 사용자를 인증합니다. | 예제 |
ManagedIdentityCredential |
Azure 리소스의 관리 ID를 인증합니다. | 예제 |
WorkloadIdentityCredential |
Kubernetes에서 Microsoft Entra 워크로드 ID |
예제 |
서비스 주체 인증
| 자격 증명 | 사용법 | 본보기 | 참조 |
|---|---|---|---|
AzurePipelinesCredential |
Azure Pipelines에서 Microsoft Entra 워크로드 ID |
예제 | |
ClientAssertionCredential |
서명된 클라이언트 어설션을 사용하여 서비스 주체를 인증합니다. | 예제 | 서비스 주체 인증 |
ClientCertificateCredential |
인증서를 사용하여 서비스 주체를 인증합니다. | 예제 | 서비스 주체 인증 |
ClientSecretCredential |
비밀을 사용하여 서비스 주체를 인증합니다. | 예제 | 서비스 주체 인증 |
사용자 인증
| 자격 증명 | 사용법 | 본보기 | 참조 |
|---|---|---|---|
AuthorizationCodeCredential |
이전에 얻은 권한 부여 코드를 사용하여 사용자를 인증합니다. | 예제 | OAuth2 인증 코드 |
DeviceCodeCredential |
제한된 UI를 사용하여 디바이스에서 사용자를 대화형으로 인증합니다. | 예제 | 디바이스 코드 인증 |
InteractiveBrowserCredential |
기본 시스템 브라우저를 사용하여 사용자를 대화형으로 인증합니다. 여기에서 |
예제 | OAuth2 인증 코드 |
OnBehalfOfCredential |
요청 체인을 통해 위임된 사용자 ID 및 권한을 전파합니다. | 인증 | |
UsernamePasswordCredential |
사용자 이름 및 암호를 사용하여 사용자를 인증합니다. | 예제 | 사용자 이름 + 암호 인증 |
개발 도구를 통해 인증
| 자격 증명 | 사용법 | 본보기 | 참조 |
|---|---|---|---|
AzureCliCredential |
Azure CLI를 사용하여 개발 환경에서 인증합니다. | 예제 | Azure CLI 인증 |
AzureDeveloperCliCredential |
Azure Developer CLI에서 사용하도록 설정된 사용자 또는 서비스 주체를 사용하여 개발 환경에서 인증합니다. | Azure 개발자 CLI 참조 |
|
AzurePowerShellCredential |
Azure PowerShell을 사용하여 개발 환경에서 인증합니다. | 예제 | Azure PowerShell 인증 |
VisualStudioCodeCredential |
사용자가 Visual Studio Code Azure 계정 확장에 로그인할 때 인증합니다. | VS Code Azure 계정 확장 |
환경 변수
환경 변수를 사용하여 DefaultAzureCredential 및 EnvironmentCredential 구성할 수 있습니다. 각 인증 유형에는 특정 변수에 대한 값이 필요합니다.
비밀이 있는 서비스 주체
| 변수 이름 | 값 |
|---|---|
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(지속적인 액세스 평가)로 보호되는 리소스에 액세스할 수 있습니다.
GetTokenOptions.enableCae(boolean) API사용하여 사용하도록 설정할 수 있습니다. CAE는 개발자 자격 증명에 대해 지원되지 않습니다.
토큰 캐싱
토큰 캐싱은 앱에서 다음을 수행할 수 있도록 하는 Azure ID 라이브러리에서 제공하는 기능입니다.
- 메모리(기본값) 및 디스크(옵트인)에서 토큰을 캐시합니다.
- 복원력 및 성능을 향상시킵니다.
- 액세스 토큰을 얻기 위해 Microsoft Entra ID에 대한 요청 수를 줄입니다.
Azure ID 라이브러리는 메모리 내 및 영구 디스크 캐싱을 모두 제공합니다. 자세한 내용은 토큰 캐싱 설명서참조하세요.
조정된 인증
인증 브로커는 사용자의 컴퓨터에서 실행되고 연결된 계정에 대한 인증 핸드셰이크 및 토큰 유지 관리를 관리하는 애플리케이션입니다. 현재 WAM(Windows 웹 계정 관리자)만 지원됩니다. 지원을 사용하려면 @azure/identity-broker 패키지를 사용합니다. WAM을 사용하여 인증하는 방법에 대한 자세한 내용은 broker 플러그 인 설명서참조하세요.
문제 해결
문제 해결에 대한 지원은 문제 해결 가이드참조하세요.
다음 단계
설명서 읽기
이 라이브러리에 대한 API 설명서는 설명서 사이트찾을 수 있습니다.
클라이언트 라이브러리 지원
Azure SDK 릴리스 페이지에 나열된 클라이언트 및 관리 라이브러리는 Microsoft Entra 인증을 지원하는 이 라이브러리의 자격 증명을 수락합니다. 릴리스 페이지에서 연결된 설명서에서 이러한 라이브러리를 사용하는 방법에 대해 자세히 알아봅니다.
알려진 문제
Azure AD B2C 지원
이 라이브러리는 Azure AD B2C 서비스를 지원하지 않습니다.
열려 있는 다른 문제는 라이브러리의 GitHub 리포지토리참조하세요.
피드백 제공
버그가 발생하거나 제안이 있는 경우문제를
기여
이 라이브러리에 기여하려면 기여 가이드 읽어 코드를 빌드하고 테스트하는 방법에 대해 자세히 알아보세요.
Azure SDK for JavaScript