소개
이 문서에서는 인바운드 프로비전 API와 관련하여 일반적으로 발생하는 오류 및 이슈와 문제 해결 방법을 다룹니다.
문제 해결 시나리오
잘못된 데이터 형식
문제 설명
- HTTP 400(잘못된 요청) 응답 코드와 함께 오류 메시지
Invalid Data Format이 표시됩니다.
가능한 원인
- 프로비전 /bulkUpload API 사양에 따라 유효한 대량 요청을 보내고 있지만 HTTP 요청 헤더 ‘Content-Type’을
application/scim+json으로 설정하지 않았습니다. - 프로비전 /bulkUpload API 사양을 준수하지 않는 대량 요청을 보내고 있습니다.
해결 방법:
- HTTP 요청의
Content-Type헤더가application/scim+json값으로 설정되어 있는지 확인합니다. - 대량 요청 페이로드가 프로비전 /bulkUpload API 사양을 준수하는지 확인합니다.
프로비전 로그에 아무것도 없습니다.
문제 설명
- 프로비전 /bulkUpload API 엔드포인트에 요청을 보냈고 HTTP 202 응답 코드를 받았지만 요청에 해당하는 프로비전 로그에 데이터가 없습니다.
가능한 원인
- API 기반 프로비전 앱이 일시 중지되었습니다.
- 프로비전 서비스는 아직 대량 요청 처리 세부 정보로 프로비전 로그를 업데이트하지 않습니다.
- 온-프레미스 프로비전 에이전트 상태가 비활성 상태입니다( 온-프레미스 Active Directory에 /API 기반 인바운드 사용자 프로비저닝을 실행하는 경우).
해결 방법:
- 프로비전 앱이 실행 중인지 확인합니다. 실행되고 있지 않으면 프로비전 시작 메뉴 옵션을 선택하여 데이터를 처리합니다.
- 온-프레미스 에이전트를 다시 시작하여 온-프레미스 프로비전 에이전트 상태를 활성화로 전환합니다.
- 요청 처리와 프로비저닝 로그에 쓰기 사이에 5분에서 10분 사이의 지연이 예상됩니다. API 클라이언트가 프로비전/bulkUpload API 엔드포인트로 데이터를 보내는 경우 요청 호출과 프로비전 로그 쿼리 사이에 시간 지연이 발생합니다.
금지된 403 응답 코드
문제 설명
- 프로비전 /bulkUpload API 엔드포인트에 요청을 보냈고 HTTP 403(금지됨) 응답 코드를 받았습니다.
가능한 원인
- 그래프 권한
SynchronizationData-User.Upload은 API 클라이언트에 할당되지 않습니다.
해결 방법:
- API 클라이언트에
SynchronizationData-User.Upload그래프 권한을 할당하고 작업을 다시 시도합니다.
요청이 너무 많음 429 응답 코드
BulkUpload API 엔드포인트는 다음과 같은 제한 한도를 적용하고 이러한 한도가 위반되는 경우 429 응답 코드를 반환합니다.
5초당 40개의 API 호출 - 호출 수가 5초 범위에서 이 한도를 초과하는 경우 클라이언트는 429 응답을 가져옵니다. 이를 방지하는 한 가지 방법은 클라이언트 요청 제출 논리의 지연을 사용하여 요청 제출 속도를 조정하는 것입니다.
24시간 동안 6,000개의 API 호출 - 호출 수가 이 제한을 초과하면 클라이언트는 429 응답을 받습니다. 이를 방지하는 한 가지 방법은 SCIM 대량 페이로드가 API 호출당 최대 50개의 레코드를 사용하도록 최적화되는 것입니다. 이 방식을 사용하면 24시간마다 300,000개의 레코드를 보낼 수 있습니다.
버킷 전체 500 응답 코드
문제 설명
- SCIM 클라이언트는 "수집된 데이터를 저장하는 버킷이 가득 찼습니다. 동기화 서비스가 수집된 데이터를 처리하고 이 요청을 다시 시도하세요."라는 메시지와 함께 HTTP 500(내부 서버 오류)을 가져옵니다.
- 큰 HR 데이터 세트가 프로비저닝
/bulkUpload엔드포인트로 전송될 때 초기 동기화 또는 전체 동기화 주기 중에 이 오류가 표시될 수 있습니다.
이 오류가 발생하는 이유
- "버킷"은 프로비전 서비스에서 들어오는
/bulkUpload페이로드를 처리하기 전에 버퍼링하는 데 사용하는 임시 수집 큐입니다. - 각 API 기반 프로비저닝 작업에는 전용 수집 큐가 있습니다.
- 프로비전 서비스는 큐에 대기 중인 페이로드를 지속적으로 처리한 다음 처리된 데이터를 삭제합니다. 이 프로세스 및 삭제 주기가 뒤처지거나 중지되면 버킷이 가득 찼을 때까지 대기 중인 데이터가 빌드될 수 있습니다.
가능한 원인 및 해결 방법
| 원인 | 해결 방법 |
|---|---|
| 잘못된 매핑(예: 온-프레미스 Active Directory 관리되는 Microsoft Entra ID 특성을 업데이트하려고 시도) 또는 잘못된 데이터로 인해 페이로드 처리가 실패합니다. 실패한 페이로드는 큐에 남아 있으므로 결국 버킷을 채울 수 있습니다. | 프로비전 로그를 검토하여 실패한 요청 처리를 식별하고, 매핑 또는 데이터 문제를 수정하고, 프로비전 작업을 다시 시작하고, 요청을 다시 보냅니다. |
| API 기반 프로비저닝 작업이 일시 중지 됨 또는 중지됨 상태입니다. 요청은 계속 큐에 대기하지만 처리는 실행되지 않습니다. | 큐에 대기 중인 요청을 처리하고 지울 수 있도록 프로비저닝 작업을 다시 시작합니다. |
| API 기반 프로비저닝 작업은 오랫동안 격리된 상태로 유지됩니다. 요청은 계속 큐에 대기하지만 처리는 실행되지 않습니다. | 격리를 해제하려면 프로비저닝 작업을 다시 시작하세요. 다시 시작하는 동안 대기 중인 기존 데이터가 지워지며 시간이 걸릴 수 있습니다. 약 40분 정도 기다린 다음 SCIM /bulkUpload 요청을 다시 보냅니다. |
| 원본 시스템은 프로비전 작업에서 처리할 수 있는 것보다 SCIM 데이터를 더 빠르게 보냅니다. | Pace 요청 제출. 각 대량 업로드 후에 HTTP 상태 코드를 확인합니다. 버킷 전체 메시지와 함께 HTTP 500을 받는 경우 다시 시도하기 전에 클라이언트(예: 5~10분)를 일시 중지합니다. |
권한 없는 401 응답 코드
문제 설명
- 프로비전 /bulkUpload API 엔드포인트에 요청을 보냈고 HTTP 401(권한 없음) 응답 코드를 받았습니다. 오류 코드는 “액세스 토큰이 만료되었거나 아직 유효하지 않음”이라는 메시지와 함께 “InvalidAuthenticationToken”을 표시합니다.
가능한 원인
- 액세스 토큰이 만료되었습니다.
해결 방법:
- API 클라이언트에 대한 새 액세스 토큰을 생성합니다.
작업이 격리 상태로 들어갑니다.
문제 설명
- 방금 프로비저닝 앱을 시작했으며 해당 앱은 현재 격리 상태입니다.
가능한 원인
- 작업을 시작하기 전에 알림 메일을 설정하지 않았습니다.
해결 방법:프로비전 편집 메뉴 항목으로 이동합니다. 설정에는 오류 발생 시 메일 알림 보내기 옆 확인란과 알림 메일을 입력할 수 있는 필드가 있습니다. 확인란을 선택하고 메일을 입력한 후 변경 내용을 저장합니다. 프로비저닝을 다시 시작하여 격리 상태에서 작업을 해제합니다.
사용자 만들기 - 잘못된 UPN
문제 설명 사용자 프로비전 실패가 있습니다. 프로비전 로그에 AzureActiveDirectoryInvalidUserPrincipalName 오류 코드가 표시됩니다.
해결 방법:
- 특성 매핑 편집 페이지로 이동합니다.
-
UserPrincipalName매핑을 선택하고RandomString함수를 사용하도록 업데이트합니다. -
Join("", Replace([userName], , "(?<Suffix>@(.)*)", "Suffix", "", , ), RandomString(3, 3, 0, 0, 0, ), "@", DefaultDomain())식을 복사하여 식 상자에 붙여넣습니다.
이 식은 Microsoft Entra ID에서 허용하는 UPN 값에 임의의 숫자를 추가하여 문제를 해결합니다.
사용자 만들기 실패 - 잘못된 도메인
문제 설명 사용자 프로비전 실패가 있습니다. 프로비전 로그에는 domain does not exist를 나타내는 오류 메시지가 표시됩니다.
해결 방법:
- 특성 매핑 편집 페이지로 이동합니다.
-
UserPrincipalName매핑을 선택하고 이 식을 복사하여 식 입력 상자Join("", Replace([userName], , "(?<Suffix>@(.)*)", "Suffix", "", , ), RandomString(3, 3, 0, 0, 0, ), "@", DefaultDomain())에 붙여넣습니다.
이 식은 Microsoft Entra ID에서 허용하는 UPN 값에 기본 도메인을 추가하여 문제를 해결합니다.
알려진 제한 사항: 다중값 주소, 전자 메일 및 전화 번호
문제 설명
- API 기반 프로비저닝은 현재
type값이home이거나 기타work가 아닌 값인 경우addresses,emails및phoneNumbers의 SCIM 다중값 특성을 처리하지 않습니다. - 이 제한은 식(예:
addresses[type eq "home"],addresses[type eq "any-other-value"]및phoneNumbers[type eq "home"])에 적용됩니다.
현재 동작
-
addresses[type eq "work"],emails[type eq "work"]및phoneNumbers[type eq "work"]값만 처리됩니다.
Workaround
- 속성이 API 기반 프로비저닝에 의해 처리되어야 하는 경우,
work유형을 사용하여 지원되는 값을 보내세요.