JavaScript용 Azure ID 라이브러리의 자격 증명 체인

Azure ID 라이브러리는 Azure Core 라이브러리의 TokenCredential 인터페이스를 구현하는 공용 클래스인 자격 증명을 제공합니다. 자격 증명은 Microsoft Entra ID에서 액세스 토큰을 획득하기 위한 고유한 인증 흐름을 나타냅니다. 이러한 자격 증명을 함께 연결하여 순서가 있는 일련의 인증 메커니즘을 시도할 수 있도록 구성할 수 있습니다.

연결된 자격 증명의 작동 방식

런타임에 자격 증명 체인은 시퀀스의 첫 번째 자격 증명을 사용하여 인증을 시도합니다. 해당 자격 증명이 액세스 토큰을 획득하지 못하면 액세스 토큰을 성공적으로 가져올 때까지 시퀀스의 다음 자격 증명이 시도됩니다. 다음 시퀀스 다이어그램은 이 동작을 보여 줍니다.

액세스 토큰을 가져올 때까지 여러 자격 증명을 통해 진행하는 인증 시도를 보여 주는 자격 증명 체인 시퀀스의 다이어그램입니다.

자격 증명 체인을 사용하는 이유

연결된 자격 증명은 다음과 같은 이점을 제공할 수 있습니다.

환경 인식: 앱이 실행 중인 환경에 따라 가장 적합한 자격 증명을 자동으로 선택합니다. 이 코드가 없으면 다음과 같은 코드를 작성해야 합니다.

import { 
    ManagedIdentityCredential, 
    AzureCliCredential 
} from "@azure/identity";

let credential;
if (process.env.NODE_ENV === "production") {
    credential = new ManagedIdentityCredential();
} else {
    credential = new AzureCliCredential();
}

원활한 전환: 앱은 인증 코드를 변경하지 않고 로컬 개발에서 스테이징 또는 프로덕션 환경으로 이동할 수 있습니다.
향상된 복원력: 이전에 액세스 토큰을 획득하지 못한 경우 다음 자격 증명으로 이동하는 대체 메커니즘을 포함합니다.

연결된 자격 증명을 선택하는 방법

자격 증명 체인에는 두 가지 방법이 있습니다.

체인 "해제하기": 미리 구성된 체인으로 시작하고 필요하지 않은 것을 제외합니다. 이 접근 방식에 대해서는 DefaultAzureCredential 개요 섹션을 참조하세요.
체인 "구축": 빈 체인으로 시작하고 필요한 것만 포함합니다. 이 접근 방식에 대해서는 ChainedTokenCredential 개요 섹션을 참조하세요.

DefaultAzureCredential 개요

DefaultAzureCredential는 규칙적인, 미리 구성된 자격 증명 체인입니다. 가장 일반적인 인증 흐름 및 개발자 도구와 함께 많은 환경을 지원하도록 설계되었습니다. 기본 체인은 그래픽 형식으로 다음과 같습니다.

DefaultAzureCredential 자격 증명을 시도하는 순서는 다음과 같습니다.

주문	자격 증명	묘사	기본값으로 활성화되어 있습니까?
1	환경	환경 변수 컬렉션을 읽어 애플리케이션 서비스 주체(애플리케이션 사용자)가 앱에 대해 구성되어 있는지 확인합니다. 그렇다면 `DefaultAzureCredential` 이러한 값을 사용하여 Azure에 앱을 인증합니다. 이 메서드는 서버 환경에서 가장 자주 사용되지만 로컬로 개발할 때도 사용할 수 있습니다.	Yes
2	워크로드 아이덴티티	앱이 워크로드 ID를 사용하도록 설정된 Azure 호스트에 배포된 경우 해당 계정을 인증합니다.	Yes
3	매니지드 아이덴티티	관리 ID를 사용하도록 설정된 Azure 호스트에 앱을 배포하는 경우 해당 관리 ID를 사용하여 Azure에 앱을 인증합니다.	Yes
4	Visual Studio Code	개발자가 Visual Studio Code의 Azure 리소스 확장을 통해 인증하고 @azure/id-vscode 패키지 가 설치된 경우 해당 계정을 인증합니다.	Yes
5	Azure CLI	개발자가 Azure CLI의 `az login` 명령을 사용하여 Azure에 인증한 경우 동일한 계정을 사용하여 Azure에 앱을 인증합니다.	Yes
6	Azure PowerShell	개발자가 Azure PowerShell의 `Connect-AzAccount` cmdlet을 사용하여 Azure에 인증한 경우 동일한 계정을 사용하여 Azure에 앱을 인증합니다.	Yes
7	Azure 개발자 CLI	개발자가 Azure Developer CLI의 `azd auth login` 명령을 사용하여 Azure에 인증한 경우 해당 계정으로 인증합니다.	Yes
8 (여덟)	중개인	broker를 통해 OS에 로그인한 기본 계정을 사용하여 인증합니다. @azure/identity-broker 패키지가 설치되어 있어야 합니다.	Yes

가장 간단한 형식으로 다음과 같이 매개 변수가 없는 DefaultAzureCredential 버전을 사용할 수 있습니다.

import { DefaultAzureCredential } from "@azure/identity";
import { BlobServiceClient } from "@azure/storage-blob";

// Acquire a credential object
const credential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
    `https://${storageAccountName}.blob.core.windows.net`,
    credential
);

DefaultAzureCredential을 사용자 지정하는 방법

다음 섹션에서는 체인에 포함되는 자격 증명을 제어하기 위한 전략을 설명합니다.

자격 증명 형식 범주 제외

전체 Developer tool 또는 Deployed service 자격 증명을 제외하려면 환경 변수 AZURE_TOKEN_CREDENTIALS를 prod 또는 dev로 각각 설정합니다. 값 prod 이 사용되는 경우 기본 자격 증명 체인은 다음과 같습니다.

액세스 토큰을 가져올 때까지 여러 자격 증명을 통해 진행하는 인증 시도를 보여 주는 자격 증명 체인 시퀀스의 다이어그램입니다.

값 dev 이 사용되는 경우 체인은 다음과 같이 표시됩니다.

인증에 사용되는 개발자 도구 자격 증명을 보여 주는 AZURE_TOKEN_CREDENTIALS 'dev'로 설정된 DefaultAzureCredential 체인의 다이어그램

환경 변수가 정의되고 지원되는 문자열로 설정되도록 하려면 requiredEnvVars 속성을 다음으로 AZURE_TOKEN_CREDENTIALS설정합니다.

const credential = new DefaultAzureCredential({ 
    requiredEnvVars: [ "AZURE_TOKEN_CREDENTIALS" ]
});

특정 자격 증명 사용

자격 증명을 제외한 모든 자격 증명을 제외하려면 환경 변수 AZURE_TOKEN_CREDENTIALS 를 자격 증명 이름으로 설정합니다. 예를 들어 .로 설정 DefaultAzureCredentialAzureCliCredential하여 체인을 AZURE_TOKEN_CREDENTIALSAzureCliCredential 줄일 수 있습니다. 문자열 비교는 대/소문자를 구분하지 않는 방식으로 수행됩니다. 환경 변수에 유효한 문자열 값은 다음과 같습니다.

AzureCliCredential
AzureDeveloperCliCredential
AzurePowerShellCredential
EnvironmentCredential
ManagedIdentityCredential
VisualStudioCodeCredential
WorkloadIdentityCredential

중요합니다

환경 변수는 AZURE_TOKEN_CREDENTIALS 패키지 버전 4.11.0 이상에서 @azure/identity 개별 자격 증명 이름을 지원합니다.

환경 변수가 정의되고 지원되는 문자열로 설정되도록 하려면 필수 속성EnvVars 를 다음으로 AZURE_TOKEN_CREDENTIALS설정합니다.

const credential = new DefaultAzureCredential({ 
    requiredEnvVars: [ "AZURE_TOKEN_CREDENTIALS" ]
});

ChainedTokenCredential 개요

ChainedTokenCredential은 앱의 요구에 맞게 자격 증명을 추가할 수 있도록 설계된 빈 체인입니다. 다음은 그 예입니다.

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

const credential = new ChainedTokenCredential(
    new AzureCliCredential(),
    new VisualStudioCodeCredential()
);

const blobServiceClient = new BlobServiceClient(
    `https://${storageAccountName}.blob.core.windows.net`,
    credential
);

앞의 코드 샘플은 두 개의 개발 시간 자격 증명으로 구성된 맞춤형 자격 증명 체인을 만듭니다. AzureCliCredential 먼저 시도되고, 필요한 경우 VisualStudioCodeCredential이어서 시도됩니다. 그래픽으로 표현된 체인은 다음과 같습니다.

AzureCliCredential을 첫 번째 시도로 표시하고 VisualStudioCodeCredential을 대체로 보여 주는 자격 증명 체인의 다이어그램

팁

성능을 향상시키려면 가장 적게 사용되는 자격 증명에서 ChainedTokenCredential 자격 증명 순서를 최적화합니다.

DefaultAzureCredential에 대한 사용 지침

DefaultAzureCredential 의심할 여지 없이 Azure ID 라이브러리를 시작하는 가장 쉬운 방법이지만 이러한 편의상 장단점이 있습니다. Azure에 앱을 배포한 후에는 앱의 인증 요구 사항을 이해해야 합니다. 이러한 이유로 DefaultAzureCredentialTokenCredential같은 특정 ManagedIdentityCredential 구현으로 대체합니다.

그 이유는 다음과 같습니다.

디버깅 문제: 인증에 실패하면 잘못된 자격 증명을 디버깅하고 식별하는 것이 어려울 수 있습니다. 한 자격 증명에서 다음 자격 증명으로의 진행률과 각 자격 증명의 성공/실패 상태를 보려면 로깅을 사용하도록 설정해야 합니다. 자세한 내용은 자격 증명 디버그를 참조하세요.
성능 오버헤드: 여러 자격 증명을 순차적으로 시도하는 프로세스로 인해 성능 오버헤드가 발생할 수 있습니다. 예를 들어 로컬 개발 머신에서 실행하는 경우 관리 ID를 사용할 수 없습니다. 따라서 ManagedIdentityCredential 로컬 개발 환경에서는 항상 실패합니다.
예측할 수 없는 동작: DefaultAzureCredential 특정 환경 변수가 있는지 확인합니다. 호스트 컴퓨터의 시스템 수준에서 이러한 환경 변수를 추가하거나 수정할 수 있습니다. 이러한 변경 내용은 전역적으로 적용되므로 해당 컴퓨터에서 실행되는 모든 앱에서 런타임에 DefaultAzureCredential 동작을 변경합니다.

자격 증명 디버그

예기치 않은 문제를 진단하거나 자격 증명이 수행하는 작업을 이해하려면 앱에서 로깅을 사용하도록 설정합니다 . 다음은 그 예입니다.

import { setLogLevel, AzureLogger } from "@azure/logger";
import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

// Constant for the Azure Identity log prefix
const AZURE_IDENTITY_LOG_PREFIX = "azure:identity";

// override logging to output to console.log (default location is stderr)
// only log messages that start with the Azure Identity log prefix
setLogLevel("verbose");
AzureLogger.log = (...args) => {
  const message = args[0];
  if (typeof message === 'string' && message.startsWith(AZURE_IDENTITY_LOG_PREFIX)) {
    console.log(...args);
  }
};

// Get storage account name from environment variable
const storageAccountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;

if (!storageAccountName) {
    throw new Error("AZURE_STORAGE_ACCOUNT_NAME environment variable is required");
}

const credential = new DefaultAzureCredential({ 
    requiredEnvVars: [ "AZURE_TOKEN_CREDENTIALS" ]
});


const blobServiceClient = new BlobServiceClient(
    `https://${storageAccountName}.blob.core.windows.net`,
    credential
);

azure:identity:info EnvironmentCredential => Found the following environment variables: 
azure:identity:verbose EnvironmentCredential => AZURE_CLIENT_SEND_CERTIFICATE_CHAIN: undefined; sendCertificateChain: false
azure:identity:info WorkloadIdentityCredential => Found the following environment variables:
azure:identity:warning DefaultAzureCredential => Skipped createDefaultWorkloadIdentityCredential because of an error creating the credential: CredentialUnavailableError: WorkloadIdentityCredential: is unavailable. clientId is a required parameter. In DefaultAzureCredential and ManagedIdentityCredential, this can be provided as an environment variable - "AZURE_CLIENT_ID".
        See the troubleshooting guide for more information: https://aka.ms/azsdk/js/identity/workloadidentitycredential/troubleshoot
azure:identity:info ManagedIdentityCredential => Using DefaultToImds managed identity.
azure:identity:warning DefaultAzureCredential => Skipped createDefaultBrokerCredential because of an error creating the credential: Error: Broker for WAM was requested, but no plugin was configured or no authentication record was found. You must install the @azure/identity-broker plugin package (npm install --save @azure/identity-broker) and enable it by importing `useIdentityPlugin` from `@azure/identity` and calling useIdentityPlugin(nativeBrokerPlugin) before using enableBroker.
azure:identity:info DefaultAzureCredential => getToken() => Skipping createDefaultWorkloadIdentityCredential, reason: WorkloadIdentityCredential: is unavailable. clientId is a required parameter. In DefaultAzureCredential and ManagedIdentityCredential, this can be provided as an environment variable - "AZURE_CLIENT_ID".
        See the troubleshooting guide for more information: https://aka.ms/azsdk/js/identity/workloadidentitycredential/troubleshoot
azure:identity:info ManagedIdentityCredential => getToken() => Using the MSAL provider for Managed Identity.
azure:identity:info ManagedIdentityCredential - Token Exchange => ManagedIdentityCredential - Token Exchange: Unavailable. The environment variables needed are: AZURE_CLIENT_ID (or the client ID sent through the parameters), AZURE_TENANT_ID and AZURE_FEDERATED_TOKEN_FILE
azure:identity:info ManagedIdentityCredential => getToken() => MSAL Identity source: DefaultToImds
azure:identity:info ManagedIdentityCredential => getToken() => Using the IMDS endpoint to probe for availability.
azure:identity:info ManagedIdentityCredential - IMDS => ManagedIdentityCredential - IMDS: Pinging the Azure IMDS endpoint
azure:identity:verbose ManagedIdentityCredential - IMDS => ManagedIdentityCredential - IMDS: Caught error RestError: connect ENETUNREACH 169.254.169.254:80
azure:identity:info ManagedIdentityCredential - IMDS => ManagedIdentityCredential - IMDS: The Azure IMDS endpoint is unavailable
azure:identity:error ManagedIdentityCredential => getToken() => ERROR. Scopes: https://storage.azure.com/.default. Error message: Attempted to use the IMDS endpoint, but it is not available..
azure:identity:info AzureCliCredential => getToken() => Using the scope https://storage.azure.com/.default
azure:identity:info AzureCliCredential => getToken() => expires_on is available and is valid, using it
azure:identity:info AzureCliCredential => getToken() => SUCCESS. Scopes: https://storage.azure.com/.default.

이전 출력에서 DefaultAzureCredential가 AzureCliCredential을 사용하여 토큰을 성공적으로 획득했습니다.

피드백

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

Last updated on 2025-10-10