사용자 지정 인증 확장 문제 해결

인증 이벤트 및 사용자 지정 클레임 공급자를 사용하면 외부 시스템과 통합하여 Microsoft Entra 인증 환경을 사용자 지정할 수 있습니다. 예를 들어 사용자 지정 클레임 공급자 API를 만들고 외부 저장소에서 클레임이 있는 토큰을 받도록 OpenID Connect 앱을 구성할 수 있습니다.

Error behavior

API 호출이 실패하면 오류 동작은 다음과 같습니다.

OpenId Connect 앱의 경우 - Microsoft Entra ID는 오류가 있는 사용자를 클라이언트 애플리케이션으로 다시 리디렉션합니다. 토큰은 발행되지 않습니다.
SAML 앱의 경우 - Microsoft Entra ID는 인증 환경에서 사용자에게 오류 화면을 표시합니다. 사용자가 클라이언트 애플리케이션으로 다시 리디렉션되지 않습니다.

애플리케이션 또는 사용자에게 다시 전송된 오류 코드는 제네릭입니다. To troubleshoot, check the sign-in logs for the error codes.

Logging

사용자 지정 클레임 공급자 REST API 엔드포인트의 문제를 해결하려면 REST API가 로깅을 처리해야 합니다. Azure Functions 및 기타 API 개발 플랫폼은 심층적인 로깅 솔루션을 제공합니다. 이러한 솔루션을 사용하여 API 동작에 대한 자세한 정보를 얻고 API 논리 문제를 해결합니다.

REST API 로그 및 호스팅 환경 진단 솔루션 외에도 Microsoft Entra 로그인 로그 를 사용할 수도 있습니다. Microsoft Entra 로그인 로그를 사용하면 사용자의 로그인에 영향을 미칠 수 있는 오류를 찾을 수 있습니다. Microsoft Entra 로그인 로그는 HTTP 상태, 오류 코드, 실행 기간 및 Microsoft Entra ID에서 API를 호출한 다시 시도 횟수에 대한 정보를 제공합니다.

Microsoft Entra sign-in logs also integrate with Azure Monitor. 경고 및 모니터링을 설정하고, 데이터를 시각화하고, SIEM(보안 정보 및 이벤트 관리) 도구와 통합할 수 있습니다. 예를 들어 오류 수가 선택한 특정 임계값을 초과하는 경우 알림을 설정할 수 있습니다.

Microsoft Entra 로그인 로그에 액세스하려면:

Microsoft Entra 관리 센터에 최소한 클라우드 애플리케이션 관리자로 로그인합니다.
Browse to Entra ID>Enterprise apps.
Select Sign-in logs, and then select the latest sign-in log.
For more details, select the Authentication Events tab. Information related to the custom authentication extension REST API call is displayed, including any error codes.

오류 코드 참조

다음 표를 사용하여 오류 코드를 진단합니다.

Error code	Error name	Description
1003000	EventHandlerUnexpectedError	이벤트 처리기를 처리할 때 예기치 않은 오류가 발생했습니다.
1003001	CustomExtensionUnexpectedError	사용자 지정 확장 API를 호출하는 동안 예기치 않은 오류가 발생했습니다.
1003002	CustomExtensionInvalidHTTPStatus	사용자 지정 확장 API가 잘못된 HTTP 상태 코드를 반환했습니다. API가 해당 사용자 지정 확장 형식에 대해 정의된 허용되는 상태 코드를 반환하는지 확인합니다.
1003003	CustomExtensionInvalidResponseBody	사용자 지정 확장의 응답 본문을 구문 분석하는 데 문제가 있었습니다. API 응답 본문이 해당 사용자 지정 확장 형식에 허용되는 스키마에 있는지 확인합니다.
1003004	CustomExtensionThrottlingError	사용자 지정 확장 요청이 너무 많습니다. 제한에 도달하면 사용자 지정 확장 API 호출 시 이 예외가 발생합니다.
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	The identifierUris property in the manifest for the application registration for the custom extension, should be in the format of "api://{fully qualified domain name}/{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를 테스트할 수 있습니다.

Obtaining an access token with an application registration associated with the custom authentication extensions
API 테스트 도구를 사용하여 로컬에서 API를 테스트합니다.

API 테스트 도구
액세스 토큰 가져오기

For local development and testing purposes, open local.settings.json and replace the code with the following JSON:
```
{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "",
    "AzureWebJobsSecretStorageType": "files",
    "FUNCTIONS_WORKER_RUNTIME": "dotnet",
    "AuthenticationEvents__BypassTokenValidation" : false
  }
}
```
Note

If you used the Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents NuGet package, be sure to set "AuthenticationEvents__BypassTokenValidation" : true for local testing purposes.
Using your preferred API testing tool, create a new HTTP request and set the HTTP method to 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"
            }
        }
    }
}

Tip

If you're using an access token obtained from Microsoft Entra ID, select Authorization and then select Bearer token, then paste the access token you received from Microsoft Entra ID.

Select Send, and you should receive a JSON response similar to the following:

{
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData",
        "actions": [
            {
                "@odata.type": "microsoft.graph.tokenIssuanceStart.provideClaimsForToken",
                "claims": {
                    "customClaim1": "customClaimValue1",
                    "customClaim2": [
                        "customClaimString1",
                        "customClaimString2" 
                    ]
                }
            }

        ]
    }
}

액세스 토큰을 획득한 후 HTTP Authorization 헤더를 전달합니다. 액세스 토큰을 얻으려면 다음 단계를 수행합니다.

Microsoft Entra 관리 센터에 최소한 클라우드 애플리케이션 관리자로 로그인합니다.
Browse to Entra ID>App registrations.
이전에 토큰 발급 이벤트에 대한 사용자 지정 클레임 공급자 구성에서 구성된 Azure Functions 인증 이벤트 API 앱 등록을 선택합니다.
Copy the application ID.
앱 비밀을 만들지 않은 경우 다음 단계를 수행합니다.
1. 인증서 및 비밀>클라이언트 비밀>새 클라이언트 비밀을 선택합니다.
2. 클라이언트 비밀에 대한 설명을 추가합니다.
3. 암호에 대해 만료를 선택하거나 사용자 지정 수명을 지정합니다.
4. Select Add.
5. Record the secret's value for use in your client application code. 이 비밀 값은 이 페이지에서 나가면 다시 표시되지 않습니다.
메뉴에서 API 노출을 선택하고 애플리케이션 ID URI의 값을 복사합니다. 예들 들어 api://contoso.azurewebsites.net/aaaabbbb-0000-cccc-1111-dddd2222eeee입니다.
기본 API 테스트 도구를 열고 새 HTTP 쿼리를 만듭니다.
Change the HTTP method to POST.
다음 URL을 입력합니다. {tenantID}를 테넌트 ID로 바꿉니다.
```
https://login.microsoftonline.com/{tenantID}/oauth2/v2.0/token
```

Under the Body, select form-data and add the following keys:

Key	Value
`grant_type`	`client_credentials`
`client_id`	The Client ID of your application.
`client_secret`	The Client Secret of your application.
`scope`	애플리케이션의 애플리케이션 ID URI를 추가`.default`합니다. 예를 들어 `api://contoso.azurewebsites.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/.default`

HTTP 쿼리를 실행하고 access_token을 https://jwt.ms 웹앱에 복사합니다.
iss API에서 구성한 발급자 이름과 비교합니다.
aud API에서 구성한 클라이언트 ID와 비교합니다.

일반적인 성능 향상

가장 일반적인 문제 중 하나는 사용자 지정 클레임 공급자 API가 2초 제한 시간 내에 응답하지 않는다는 것입니다. REST API가 후속 재시도에서 응답하지 않으면 인증이 실패합니다. REST API의 성능을 개선하려면 아래 제안을 따릅니다.

API가 다운스트림 API에 액세스하는 경우 이러한 API를 호출하는 데 사용되는 액세스 토큰을 캐시하므로 모든 실행 시 새 토큰을 획득할 필요가 없습니다.
성능 문제는 종종 다운스트림 서비스와 관련이 있습니다. 다운스트림 서비스를 호출하는 프로세스 시간을 기록하는 로깅을 추가합니다.
클라우드 공급자를 사용하여 API를 호스팅하는 경우, API를 항상 예열된 상태로 유지하는 호스팅 계획을 사용하세요. Azure Functions의 경우 프리미엄 플랜 또는 전용 플랜일 수 있습니다.
인증에 대한 자동화된 통합 테스트를 실행합니다. API 테스트 도구를 사용하여 API 성능만 테스트할 수도 있습니다.

피드백

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

Last updated on 2025-07-24