Azure Identity Authentication 문제 해결

아티클
10/23/2023

이 문서에서는 오류 조사 기술, Azure Identity Java 클라이언트 라이브러리의 자격 증명 유형에 대한 일반적인 오류 및 이러한 오류를 해결하기 위한 완화 단계를 설명합니다. Java용 Azure SDK에서 사용할 수 있는 자격 증명 유형이 많기 때문에 사용 시나리오에 따라 문제 해결 가이드를 섹션으로 분할했습니다. 다음 섹션들을 사용할 수 있습니다:

이 문서의 다시 기본 내용은 모든 자격 증명 유형에 적용되는 일반적인 문제 해결 기술 및 지침을 다룹니다.

Azure ID 예외 처리

문제 해결 개요의 Java 용 Azure SDK 섹션에 있는 예외 처리에 설명된 것처럼 Java용 Azure SDK에서 throw할 수 있는 포괄적인 예외 및 오류 코드 집합이 있습니다. 특히 Azure ID의 경우 이해해야 하는 몇 가지 주요 예외 유형이 있습니다.

ClientAuthenticationException

서비스에 대한 요청을 만드는 모든 서비스 클라이언트 메서드는 인증 오류로 인해 발생하는 예외를 발생할 수 있습니다. 이러한 예외는 서비스에 대한 첫 번째 호출 및 토큰을 새로 고쳐야 하는 서비스에 대한 후속 요청에 대한 자격 증명에서 토큰이 요청되기 때문에 가능합니다.

이러한 오류를 서비스 클라이언트의 오류와 구분하기 위해 Azure ID 클래스는 예외 메시지의 오류 원본 및 오류 메시지를 설명하는 세부 정보로 발생 ClientAuthenticationException 합니다. 애플리케이션에 따라 이러한 오류는 복구할 수 있거나 복구할 수 없습니다. 다음 코드는 catch ClientAuthenticationException의 예를 보여줍니다.

// Create a secret client using the DefaultAzureCredential
SecretClient client = new SecretClientBuilder()
    .vaultUrl("https://myvault.vault.azure.net/")
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

try {
    KeyVaultSecret secret = client.getSecret("secret1");
} catch (ClientAuthenticationException e) {
    //Handle Exception
    e.printStackTrace();
}

CredentialUnavailableException

CredentialUnavailableException 는 .에서 ClientAuthenticationException파생된 특수 예외 형식입니다. 이 예외 유형은 필수 구성 또는 설정이 부족하여 자격 증명이 현재 환경에서 인증할 수 없음을 나타내는 데 사용됩니다. 이 예외는 체인 자격 증명과 같은 연결된 자격 증명 형식에 대한 신호로 DefaultAzureCredentialChainedTokenCredential도 사용되며, 체인의 뒷부분에서 다른 자격 증명 형식을 계속 시도해야 합니다.

권한 문제

401 또는 403으로 인해 HttpResponseExceptionStatusCode 서비스 클라이언트에 대한 호출은 호출자에게 지정된 API에 대한 충분한 권한이 없음을 나타내는 경우가 많습니다. 서비스 설명서를 확인하여 특정 요청에 필요한 역할을 확인합니다. 인증된 사용자 또는 서비스 주체에게 리소스에 대한 적절한 역할이 부여되었는지 확인합니다.

예외 메시지에서 관련 정보 찾기

ClientAuthenticationException 는 자격 증명을 인증하는 동안 예기치 않은 오류가 발생할 때 throw됩니다. 이러한 오류에는 MICROSOFT Entra STS(보안 토큰 서비스)에 대한 요청에서 받은 오류가 포함될 수 있으며 진단에 유용한 정보가 포함되어 있는 경우가 많습니다. 다음 메시지를 고려합니다.ClientAuthenticationException

ClientSecretCredential authentication failed: A configuration issue is preventing authentication - check the error message from the server for details. You can modify the configuration in the application registration portal. See https://aka.ms/msal-net-invalid-client for details.

Original exception:
AADSTS7000215: Invalid client secret provided. Ensure the secret being sent in the request is the client secret value, not the client secret ID, for a secret added to app 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'.
Trace ID: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
Correlation ID: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
Timestamp: 2022-01-01 00:00:00Z

이 오류 메시지에는 다음 정보가 포함됩니다.

자격 증명 유형 실패: 인증에 실패한 자격 증명의 형식입니다. 이 경우 ClientSecretCredential. 이 정보는 연결된 자격 증명 유형(예: DefaultAzureCredential 또는 ChainedTokenCredential)과 관련된 문제를 진단할 때 유용합니다.
STS 오류 코드 및 메시지: Microsoft Entra STS에서 반환된 오류 코드 및 메시지 - 이 경우 AADSTS7000215: Invalid client secret provided. 이 정보는 요청이 실패한 특정 이유에 대한 인사이트를 제공할 수 있습니다. 예를 들어 이 특정 경우에는 제공된 클라이언트 암호가 잘못되었기 때문입니다. STS 오류 코드에 대한 자세한 내용은 Microsoft Entra 인증 및 권한 부여 오류 코드의 AADSTS 오류 코드 섹션을 참조하세요.
상관 관계 ID 및 타임스탬프: 서버 쪽 로그에서 요청을 식별하는 데 사용되는 상관 관계 ID 및 호출 타임스탬프입니다. 이 정보는 예기치 않은 STS 오류를 진단할 때 엔지니어를 지원하는 데 유용합니다.

로깅 사용 및 구성

Java용 Azure SDK는 애플리케이션 오류 문제를 해결하고 해결을 신속하게 하는 데 도움이 되는 일관된 로깅 스토리를 제공합니다. 생성된 로그는 근본 문제를 찾는 데 도움이 되도록 터미널 상태에 도달하기 전에 애플리케이션의 흐름을 캡처합니다. 로깅 에 대한 지침은 Java 용 Azure SDK의 로깅 구성 및 뷰를 통해 문제 해결을 참조하세요.

기본 MSAL 라이브러리인 MSAL4J에도 자세한 로깅이 있습니다. 이 로깅은 매우 자세한 정보이며 토큰을 포함한 모든 개인 데이터를 포함합니다. 이 로깅은 제품 지원을 사용할 때 가장 유용합니다. v1.10.0을 기준으로 이 로깅을 제공하는 자격 증명에는 메서드가 있습니다 enableUnsafeSupportLogging().

주의

Azure ID 라이브러리의 요청 및 응답에는 중요한 정보가 포함됩니다. 계정 보안을 손상시키지 않도록 출력을 사용자 지정할 때 로그를 보호하기 위해 주의해야 합니다.

다음 단계

이 문서의 문제 해결 지침이 Java용 Azure SDK 클라이언트 라이브러리를 사용할 때 문제를 해결하는 데 도움이 되지 않는 경우 Java GitHub 리포지토리용 Azure SDK에 문제를 제출하는 것이 좋습니다.

다음을 통해 공유