사용자 지정 클레임 공급자 API 문제 해결
인증 이벤트 및 사용자 지정 클레임 공급자를 사용하면 외부 시스템과 통합하여 Microsoft Entra 인증 환경을 사용자 지정할 수 있습니다. 예를 들어 사용자 지정 클레임 공급자 API를 만들고 외부 저장소에서 클레임이 있는 토큰을 받도록 OpenID Connect 앱 또는 SAML 앱을 구성할 수 있습니다.
오류 동작
API 호출이 실패하면 오류 동작은 다음과 같습니다.
- OpenId Connect 앱의 경우 - Microsoft Entra ID는 오류가 있는 사용자를 클라이언트 애플리케이션으로 다시 리디렉션합니다. 토큰은 채굴되지 않습니다.
- SAML 앱의 경우 - Microsoft Entra ID는 인증 환경에서 사용자에게 오류 화면을 표시합니다. 사용자가 클라이언트 애플리케이션으로 다시 리디렉션되지 않습니다.
애플리케이션 또는 사용자에게 다시 전송된 오류 코드는 제네릭입니다. 문제를 해결하려면 오류 코드에 대한 로그인 로그를 확인합니다.
로깅
사용자 지정 클레임 공급자 REST API 엔드포인트의 문제를 해결하려면 REST API가 로깅을 처리해야 합니다. Azure Functions 및 기타 API 개발 플랫폼은 심층적인 로깅 솔루션을 제공합니다. 이러한 솔루션을 사용하여 API 동작에 대한 자세한 정보를 얻고 API 논리 문제를 해결합니다.
Microsoft Entra 로그인 로그
팁
이 문서의 단계는 시작하는 포털에 따라 약간 다를 수 있습니다.
REST API 로그 및 호스팅 환경 진단 솔루션 외에도 Microsoft Entra 로그인 로그를 사용할 수도 있습니다. Microsoft Entra 로그인 로그를 사용하면 사용자의 로그인에 영향을 미칠 수 있는 오류를 찾을 수 있습니다. Microsoft Entra 로그인 로그는 HTTP 상태, 오류 코드, 실행 기간 및 Microsoft Entra ID에서 API를 호출한 다시 시도 횟수에 대한 정보를 제공합니다.
Microsoft Entra 로그인 로그는 Azure Monitor와도 통합됩니다. 경고 및 모니터링을 설정하고, 데이터를 시각화하고, SIEM(보안 정보 및 이벤트 관리) 도구와 통합할 수 있습니다. 예를 들어 오류 수가 선택한 특정 임계값을 초과하는 경우 알림을 설정할 수 있습니다.
Microsoft Entra 로그인 로그에 액세스하려면:
최소한 클라우드 애플리케이션 관리자로 Microsoft Entra 관리 센터에 로그인합니다.
ID>애플리케이션>엔터프라이즈 애플리케이션으로 이동합니다.
로그인 로그를 선택한 다음 최신 로그인 로그를 선택합니다.
자세한 내용을 보려면 인증 이벤트 탭을 선택합니다. 오류 코드를 포함하여 사용자 지정 인증 확장 REST API 호출과 관련된 정보가 표시됩니다.
오류 코드 참조
다음 표를 사용하여 오류 코드를 진단합니다.
| 오류 코드 | 오류 이름 | 설명 |
|---|---|---|
| 1003000 | EventHandlerUnexpectedError | 이벤트 처리기를 처리할 때 예기치 않은 오류가 발생했습니다. |
| 1003001 | CustomExtenstionUnexpectedError | 사용자 지정 확장 API를 호출하는 동안 예기치 않은 오류가 발생했습니다. |
| 1003002 | CustomExtensionInvalidHTTPStatus | 사용자 지정 확장 API가 잘못된 HTTP 상태 코드를 반환했습니다. API가 해당 사용자 지정 확장 형식에 대해 정의된 허용되는 상태 코드를 반환하는지 확인합니다. |
| 1003003 | CustomExtensionInvalidResponseBody | 사용자 지정 확장의 응답 본문을 구문 분석하는 데 문제가 있었습니다. API 응답 본문이 해당 사용자 지정 확장 형식에 허용되는 스키마에 있는지 확인합니다. |
| 1003004 | CustomExtensionThrottlingError | 사용자 지정 확장 요청이 너무 많습니다. 제한에 도달하면 사용자 지정 확장 API 호출에 대해 이 예외가 throw됩니다. |
| 1003005 | CustomExtensionTimedOut | 사용자 지정 확장이 허용된 시간 제한 내에 응답하지 않았습니다. 사용자 지정 확장에 대해 구성된 시간 제한 내에서 API가 응답하는지 확인합니다. 액세스 토큰이 잘못되었음을 나타낼 수도 있습니다. 단계에 따라 REST API를 직접 호출합니다. |
| 1003006 | CustomExtensionInvalidResponseContentType | 사용자 지정 확장의 응답 콘텐츠 형식이 'application/json'이 아닙니다. |
| 1003007 | CustomExtensionNullClaimsResponse | 사용자 지정 확장 API는 null 클레임 모음으로 응답했습니다. |
| 1003008 | CustomExtensionInvalidResponseApiSchemaVersion | 사용자 지정 확장 API가 호출된 것과 동일한 apiSchemaVersion으로 응답하지 않았습니다. |
| 1003009 | CustomExtensionEmptyResponse | 사용자 지정 확장 API 응답 본문이 필요하지 않은 경우 null이었습니다. |
| 1003010 | CustomExtensionInvalidNumberOfActions | 사용자 지정 확장 API 응답에는 해당 사용자 지정 확장 형식에 대해 지원되는 작업과 다른 수의 작업이 포함되었습니다. |
| 1003011 | CustomExtensionNotFound | 이벤트 수신기와 연결된 사용자 지정 확장을 찾을 수 없습니다. |
| 1003012 | CustomExtensionInvalidActionType | 사용자 지정 확장은 해당 사용자 지정 확장 형식에 대해 정의된 잘못된 작업 형식을 반환했습니다. |
| 1003014 | CustomExtensionIncorrectResourceIdFormat | 사용자 지정 확장에 대한 애플리케이션 등록을 위한 매니페스트의 identifierUris 속성은 "api://{정규화된 도메인 이름}/{appid} 형식이어야 합니다. |
| 1003015 | CustomExtensionDomainNameDoesNotMatch | 사용자 지정 확장의 targetUrl 및 resourceId는 동일한 정규화된 도메인 이름을 가져야 합니다. |
| 1003016 | CustomExtensionResourceServicePrincipalNotFound | 사용자 지정 확장 resourceId의 appId는 테넌트의 실제 서비스 사용자와 일치해야 합니다. |
| 1003017 | CustomExtensionClientServicePrincipalNotFound | 테넌트에서 사용자 지정 확장 리소스 서비스 사용자를 찾을 수 없습니다. |
| 1003018 | CustomExtensionClientServiceDisabled | 이 테넌트에서 사용자 지정 확장 리소스 서비스 사용자를 사용할 수 없습니다. |
| 1003019 | CustomExtensionResourceServicePrincipalDisabled | 이 테넌트에서 사용자 지정 확장 리소스 서비스 사용자를 사용할 수 없습니다. |
| 1003020 | CustomExtensionIncorrectTargetUrlFormat | 대상 URL이 잘못된 형식입니다. https로 시작하는 유효한 URL이어야 합니다. |
| 1003021 | CustomExtensionPermissionNotGrantedToServicePrincipal | 서비스 사용자에게 앱이 사용자 지정 인증 확장 HTTP 요청을 수신하는 데 필요한 Microsoft Graph CustomAuthenticationExtensions.Receive.Payload 앱 역할(애플리케이션 권한이라고도 함)에 대한 관리자 동의가 없습니다. |
| 1003022 | CustomExtensionMsGraphServicePrincipalDisabledOrNotFound | MS Graph 서비스 사용자가 비활성화되어 있거나 이 테넌트에서 찾을 수 없습니다. |
| 1003023 | CustomExtensionBlocked | 사용자 지정 확장에 사용되는 엔드포인트는 서비스에 의해 차단됩니다. |
| 1003024 | CustomExtensionResponseSizeExceeded | 사용자 지정 확장 응답 크기가 최대 제한을 초과했습니다. |
| 1003025 | CustomExtensionResponseClaimsSizeExceeded | 사용자 지정 확장 응답의 총 클레임 크기가 최대 제한을 초과했습니다. |
| 1003026 | CustomExtensionNullOrEmptyClaimKeyNotSupported | 사용자 지정 확장 API가 null 또는 빈 키를 포함하는 클레임으로 응답했습니다. |
| 1003027 | CustomExtensionConnectionError | 사용자 지정 확장 API에 연결하는 동안 오류가 발생했습니다. |
REST API를 직접 호출
사용자의 REST API는 Microsoft Entra 액세스 토큰으로 보호됩니다. 다음을 통해 API를 테스트할 수 있습니다.
- 사용자 지정 인증 확장과 연결된 애플리케이션 등록을 사용하여 액세스 토큰 가져오기
- API 테스트 도구를 사용하여 API를 로컬로 테스트합니다.
로컬 개발 및 테스트를 위해 local.settings.json 열고 코드를 다음 JSON으로 바꿉니다.
{ "IsEncrypted": false, "Values": { "AzureWebJobsStorage": "", "AzureWebJobsSecretStorageType": "files", "FUNCTIONS_WORKER_RUNTIME": "dotnet", "AuthenticationEvents__BypassTokenValidation" : false } }참고 항목
Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents NuGet 패키지를 사용한 경우 로컬 테스트 목적으로 설정
"AuthenticationEvents__BypassTokenValidation" : true해야 합니다.선호하는 API 테스트 도구를 사용하여 새 HTTP 요청을 만들고 HTTP 메서드를
POST.로 설정합니다.Microsoft Entra ID가 REST API에 보내는 요청을 모방하는 다음 JSON 본문을 사용합니다.
{ "type": "microsoft.graph.authenticationEvent.tokenIssuanceStart", "source": "/tenants/aaaabbbb-0000-cccc-1111-dddd2222eeee/applications/00001111-aaaa-2222-bbbb-3333cccc4444", "data": { "@odata.type": "microsoft.graph.onTokenIssuanceStartCalloutData", "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee", "authenticationEventListenerId": "11112222-bbbb-3333-cccc-4444dddd5555", "customAuthenticationExtensionId": "22223333-cccc-4444-dddd-5555eeee6666", "authenticationContext": { "correlationId": "aaaa0000-bb11-2222-33cc-444444dddddd", "client": { "ip": "127.0.0.1", "locale": "en-us", "market": "en-us" }, "protocol": "OAUTH2.0", "clientServicePrincipal": { "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb", "appId": "00001111-aaaa-2222-bbbb-3333cccc4444", "appDisplayName": "My Test application", "displayName": "My Test application" }, "resourceServicePrincipal": { "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb", "appId": "00001111-aaaa-2222-bbbb-3333cccc4444", "appDisplayName": "My Test application", "displayName": "My Test application" }, "user": { "companyName": "Casey Jensen", "createdDateTime": "2023-08-16T00:00:00Z", "displayName": "Casey Jensen", "givenName": "Casey", "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee", "mail": "casey@contoso.com", "onPremisesSamAccountName": "Casey Jensen", "onPremisesSecurityIdentifier": "<Enter Security Identifier>", "onPremisesUserPrincipalName": "Casey Jensen", "preferredLanguage": "en-us", "surname": "Jensen", "userPrincipalName": "casey@contoso.com", "userType": "Member" } } } }팁
Microsoft Entra ID에서 가져온 액세스 토큰을 사용하는 경우 권한 부여를 선택한 다음 전달자 토큰을 선택한 다음 Microsoft Entra ID에서 받은 액세스 토큰을 붙여넣습니다.
보내기를 선택하면 다음과 유사한 JSON 응답을 받게 됩니다.
{ "data": { "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData", "actions": [ { "@odata.type": "microsoft.graph.tokenIssuanceStart.provideClaimsForToken", "claims": { "customClaim1": "customClaimValue1", "customClaim2": [ "customClaimString1", "customClaimString2" ] } } ] } }
일반적인 성능 향상
가장 일반적인 문제 중 하나는 사용자 지정 클레임 공급자 API가 2초 제한 시간 내에 응답하지 않는다는 것입니다. REST API가 후속 재시도에서 응답하지 않으면 인증이 실패합니다. REST API의 성능을 개선하려면 아래 제안을 따릅니다.
- API가 다운스트림 API에 액세스하는 경우 이러한 API를 호출하는 데 사용되는 액세스 토큰을 캐시하므로 모든 실행 시 새 토큰을 획득할 필요가 없습니다.
- 성능 문제는 종종 다운스트림 서비스와 관련이 있습니다. 다운스트림 서비스를 호출하는 프로세스 시간을 기록하는 로깅을 추가합니다.
- 클라우드 공급자를 사용하여 API를 호스트하는 경우 API를 항상 "웜"으로 유지하는 호스팅 계획을 사용합니다. Azure Functions의 경우 프리미엄 플랜 또는 전용 플랜일 수 있습니다.
- 인증을 위해 자동 통합 테스트를 실행합니다. API 테스트 도구를 사용하여 API 성능만 테스트할 수도 있습니다.