Azure 호스팅 애플리케이션 인증 문제 해결

이 문서에서는 다양한 TokenCredential 구현을 통해 Azure에서 호스트되는 Java 애플리케이션용 Azure SDK를 인증할 때 발생하는 문제를 처리하는 방법에 대한 지침을 제공합니다. 자세한 내용은 Azure 호스팅 Java 애플리케이션 인증을 참조 하세요.

DefaultAzureCredential 문제 해결

사용할 DefaultAzureCredential때 필요에 따라 .에 대해 CredentialUnavailableException시도/catch할 수 있습니다. 다음 표에서는 이 예외가 나타내는 오류와 완화 방법을 보여 줍니다.

오류 메시지	설명	마이그레이션
CredentialUnavailableException raised with message "DefaultAzureCredential failed to retrieve a token from the included credentials."	체인의 모든 자격 증명이 DefaultAzureCredential 토큰을 검색하지 못하고 각각 .CredentialUnavailableException	로깅 을 사용하도록 설정하여 시도 중인 자격 증명을 확인하고 추가 진단 정보를 가져옵니다. 자세한 내용은 다음 기본 자격 증명 유형 중 하나에 대한 문제 해결 가이드를 참조하세요. - EnvironmentCredential - ManagedIdentityCredential - VisualStudioCodeCredential - AzureCLICredential - AzurePowershellCredential
HttpResponseException raised from the client with a status code of 401 or 403	인증에 성공했지만 권한 부여 Azure 서비스가 401(인증) 또는 403(금지됨) 상태 코드로 응답했습니다. 이 문제는 의도한 계정이 아닌 다른 계정을 인증하거나 의도한 계정에 올바른 권한 또는 역할이 할당되지 않은 경우에 DefaultAzureCredential 종종 발생합니다.	로깅 을 사용하도록 설정하여 인증 토큰을 반환한 체인의 자격 증명을 확인합니다. 예상된 자격 증명 이외의 자격 증명이 토큰을 반환하는 경우 해당 개발 도구에서 로그아웃하여 이 문제를 무시합니다. 올바른 역할이 사용 중인 계정에 할당되었는지 확인합니다. 예를 들어 구독 소유자 역할이 아닌 서비스별 역할입니다.

EnvironmentCredential 문제 해결

사용할 EnvironmentCredential때 필요에 따라 .에 대해 CredentialUnavailableException시도/catch할 수 있습니다. 다음 표에서는 이 예외가 나타내는 오류와 완화 방법을 보여 줍니다.

오류 메시지	설명	마이그레이션
Environment variables aren't fully configured.	환경 변수의 유효한 조합이 설정되지 않았습니다.	다음 목록에 설명된 대로 애플리케이션을 시작하기 전에 적절한 환경 변수가 의도한 인증 방법에 대해 설정되었는지 확인합니다. - 클라이언트 암호를 사용하여 서비스 주체를 인증하려면 변수가 올바르게 설정되어 있는지 확인합니다AZURE_CLIENT_IDAZURE_TENANT_IDAZURE_CLIENT_SECRET. - 인증서를 사용하여 서비스 주체를 인증하려면 변수AZURE_CLIENT_ID, AZURE_TENANT_IDAZURE_CLIENT_CERTIFICATE_PATH및 필요에 AZURE_CLIENT_CERTIFICATE_PASSWORD 따라 올바르게 설정되었는지 확인합니다. - 암호를 사용하여 사용자를 인증하려면 변수가 올바르게 설정되어 있는지 확인합니다 AZURE_USERNAMEAZURE_PASSWORD .

ManagedIdentityCredential 문제 해결

ManagedIdentityCredential 는 관리 ID를 제공하는 다양한 Azure 호스트에서 작동하도록 설계되었습니다. 관리 ID 구성 및 문제 해결 실패는 호스트마다 다릅니다. 다음 목록에서는 관리 ID를 할당하고 ManagedIdentityCredential 지원하는 Azure 호스트 환경을 보여 줍니다.

• Azure 앱 Service 및 Azure Functions - 구성 - 문제 해결
• Azure Arc - 구성
• Azure Kubernetes Service - 구성 - 문제 해결
• Azure Service Fabric -configuration
• Azure Virtual Machines 및 Scale Sets - 구성 - 문제 해결

Azure Virtual Machines 관리 ID

사용할 ManagedIdentityCredential때 필요에 따라 .에 대해 CredentialUnavailableException시도/catch할 수 있습니다. 다음 표에서는 이 예외가 나타내는 오류와 완화 방법을 보여 줍니다.

오류 메시지	설명	마이그레이션
The requested identity hasn't been assigned to this resource.	AZURE IMDS(Instance Metadata Service) 엔드포인트는 요청된 ID가 VM(가상 머신)에 할당되지 않았음을 나타내는 400의 상태 코드로 응답했습니다.	사용자 할당 ID를 사용하는 경우 지정된 clientId ID가 올바른지 확인합니다. 시스템 할당 ID를 사용하는 경우 올바르게 사용하도록 설정했는지 확인합니다. 자세한 내용은 Azure Portal을 사용하여 VM에서 Azure 리소스에 대한 관리 ID 구성의 기존 VM 섹션에서 시스템 할당 관리 ID 사용 섹션을 참조하세요.
The request failed due to a gateway error.	게이트웨이 오류, 502 또는 504 상태 코드로 인해 IMDS 엔드포인트에 대한 요청이 실패했습니다.	IMDS는 프록시 또는 게이트웨이를 통한 호출을 지원하지 않습니다. IMDS 엔드포인트에 대한 호출에 대해 VM에서 실행되는 프록시 또는 게이트웨이를 사용하지 않도록 설정합니다. http://169.254.169.254/
No response received from the managed identity endpoint.	IMDS에 대한 요청에 대한 응답이 수신되지 않거나 요청 시간이 초과되었습니다.	- VM에서 관리 ID를 올바르게 구성했는지 확인합니다. 자세한 내용은 Azure Portal을 사용하여 VM에서 Azure 리소스에 대한 관리 ID 구성을 참조하세요. - VM에서 IMDS 엔드포인트에 연결할 수 있는지 확인합니다. 자세한 내용은 다음 섹션을 참조 하세요.
Multiple attempts failed to obtain a token from the managed identity endpoint.	IMDS 엔드포인트에서 토큰을 검색하기 위한 재시도는 모두 사용되었습니다.	- 특정 오류에 대한 자세한 내용은 내부 예외 메시지를 참조하세요. 데이터가 잘린 경우 로그를 수집하여 더 자세한 정보를 얻을 수 있습니다. - VM에서 관리 ID를 올바르게 구성했는지 확인합니다. 자세한 내용은 Azure Portal을 사용하여 VM에서 Azure 리소스에 대한 관리 ID 구성을 참조하세요. - VM에서 IMDS 엔드포인트에 연결할 수 있는지 확인합니다. 자세한 내용은 다음 섹션을 참조 하세요.

VM에서 IMDS를 사용할 수 있는지 확인

VM에 액세스할 수 있는 경우 다음 예제와 같이 명령줄을 통해 관리 ID 엔드포인트를 curl사용할 수 있는지 확인할 수 있습니다.

curl 'http://169.254.169.254/metadata/identity/oauth2/token?resource=https://management.core.windows.net&api-version=2018-02-01' -H "Metadata: true"

Warning

이 명령의 출력에는 유효한 액세스 토큰이 포함되어 있습니다. 계정 보안이 손상되지 않도록 하려면 이 액세스 토큰을 공유하지 마세요.

Azure App Service 및 Azure Functions 관리 ID

사용할 ManagedIdentityCredential때 필요에 따라 .에 대해 CredentialUnavailableException시도/catch할 수 있습니다. 다음 표에서는 이 예외가 나타내는 오류와 완화 방법을 보여 줍니다.

오류 메시지	설명	마이그레이션
ManagedIdentityCredential authentication unavailable.	App Services 호스트에서 구성한 환경 변수가 없습니다.	- App Service 인스턴스에서 관리 ID를 올바르게 구성했는지 확인합니다. 자세한 내용은 App Service 및 Azure Functions에 관리 ID를 사용하는 방법을 참조 하세요. - App Service 환경을 올바르게 구성했으며 관리 ID 엔드포인트를 사용할 수 있는지 확인합니다. 자세한 내용은 다음 섹션을 참조 하세요.

App Service 관리 ID 엔드포인트를 사용할 수 있는지 확인

App Service 인스턴스에 대한 SSH에 대한 액세스 권한이 있는 경우 환경에서 관리 ID를 사용할 수 있는지 확인할 수 있습니다. 먼저 환경 변수 및 MSI_SECRET 환경에서 설정했는지 확인합니다MSI_ENDPOINT. 그런 다음 다음 예제와 같이 관리 ID 엔드포인트를 사용하여 curl사용할 수 있는지 확인할 수 있습니다.

curl 'http://169.254.169.254/metadata/identity/oauth2/token?resource=https://management.core.windows.net&api-version=2018-02-01' -H "Metadata: true"

Warning

이 명령의 출력에는 유효한 액세스 토큰이 포함되어 있습니다. 계정 보안이 손상되지 않도록 하려면 이 액세스 토큰을 공유하지 마세요.

Azure Kubernetes Service 관리 ID

Kubernetes용 Pod ID

사용할 ManagedIdentityCredential때 필요에 따라 .에 대해 CredentialUnavailableException시도/catch할 수 있습니다. 다음 표에서는 이 예외가 나타내는 오류와 완화 방법을 보여 줍니다.

오류 메시지	설명	마이그레이션
No Managed Identity endpoint found	애플리케이션은 ID가 Pod에 할당되기 전에 인증을 시도했습니다.	Pod의 레이블이 올바르게 지정되었는지 확인합니다. 이 문제는 ID가 준비되기 전에 올바르게 레이블이 지정된 Pod가 인증될 때도 발생합니다. 초기화 경합을 방지하려면 응답에서 헤더를 Retry-After 설정하도록 NMI를 구성합니다. 자세한 내용은 Pod ID 설명서의 NMI 응답 에서 Retry-After 헤더 설정을 참조하세요.

WorkloadIdentityCredential 문제 해결

사용할 WorkloadIdentityCredential때 필요에 따라 .에 대해 CredentialUnavailableException시도/catch할 수 있습니다. 다음 표에서는 이 예외가 나타내는 오류와 완화 방법을 보여 줍니다.

오류 메시지	설명	마이그레이션
WorkloadIdentityCredential authentication unavailable. The workload options aren't fully configured.	WorkloadIdentityCredential에는 clientIdtenantIdtokenFilePath Microsoft Entra ID를 사용하여 인증해야 합니다.	사용하는 경우 다음을 수행 DefaultAzureCredential합니다. - setter 또는 환경 변수를 통해 클라이언트 ID가 workloadIdentityClientIdAZURE_CLIENT_ID 지정되었는지 확인합니다. - 환경 변수를 통해 테넌트 ID가 AZURE_TENANT_ID 지정되었는지 확인합니다. - 환경 변수를 통해 AZURE_FEDERATED_TOKEN_FILE 토큰 파일 경로를 지정했는지 확인합니다. - 환경 변수를 통해 기관 호스트가 AZURE_AUTHORITY_HOST 지정되었는지 확인합니다. 사용하는 경우 다음을 수행 WorkloadIdentityCredential합니다. - 테넌트 ID가 자격 증명 작성기 또는 환경 변수의 tenantId setter를 AZURE_TENANT_ID 통해 지정되었는지 확인합니다. - 클라이언트 ID가 자격 증명 작성기 또는 환경 변수의 clientId setter를 AZURE_CLIENT_ID 통해 지정되었는지 확인합니다. - 토큰 파일 경로가 자격 증명 작성기 또는 AZURE_FEDERATED_TOKEN_FILE 환경 변수의 tokenFilePath setter를 통해 지정되었는지 확인합니다. - 다른 문제는 제품 문제 해결 가이드를 참조하세요.

다음 단계

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