인바운드 프로비전 API 문제 해결
소개
이 문서에서는 인바운드 프로비전 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 기반 프로비전 앱이 일시 중지되었습니다.
- 프로비전 서비스는 아직 대량 요청 처리 세부 정보로 프로비전 로그를 업데이트하지 않습니다.
- 온-프레미스 프로비전 에이전트 상태가 비활성 상태입니다(/API-driven inbound user provisioning to on-premises Active Directory를 실행하는 경우).
해결 방법:
- 프로비전 앱이 실행 중인지 확인합니다. 실행되고 있지 않으면 프로비전 시작 메뉴 옵션을 선택하여 데이터를 처리합니다.
- 온-프레미스 에이전트를 다시 시작하여 온-프레미스 프로비전 에이전트 상태를 활성화로 전환합니다.
- 요청을 처리하고 프로비전 로그에 기록할 때까지 5~10분 정도 걸릴 것으로 예상됩니다. API 클라이언트가 프로비전/bulkUpload API 엔드포인트로 데이터를 보내는 경우 요청 호출과 프로비전 로그 쿼리 사이에 시간 지연이 발생합니다.
금지된 403 응답 코드
문제 설명
- 프로비전 /bulkUpload API 엔드포인트에 요청을 보냈고 HTTP 403(금지됨) 응답 코드를 받았습니다.
가능한 원인
SynchronizationData-User.UploadGraph 권한이 API 클라이언트에 할당되지 않았습니다.
해결 방법:
- API 클라이언트에
SynchronizationData-User.Upload그래프 권한을 할당하고 작업을 다시 시도합니다.
요청이 너무 많음 429 응답 코드
BulkUpload API 엔드포인트는 다음과 같은 제한 한도를 적용하고 이러한 한도가 위반되는 경우 429 응답 코드를 반환합니다.
5초당 40개의 API 호출 - 호출 수가 5초 범위에서 이 한도를 초과하는 경우 클라이언트는 429 응답을 가져옵니다. 이를 방지하는 한 가지 방법은 클라이언트 요청 제출 논리의 지연을 사용하여 요청 제출 속도를 조정하는 것입니다.
24시간 동안 6000개의 API 호출 – 호출 수가 이 한도를 초과하면 클라이언트는 429 응답을 받습니다. 이를 방지하는 한 가지 방법은 SCIM 대량 페이로드가 API 호출당 최대 50개의 레코드를 사용하도록 최적화되는 것입니다. 이 방식을 사용하면 24시간마다 300,000개의 레코드를 보낼 수 있습니다.
권한 없는 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 값에 기본 도메인을 추가하여 문제를 해결합니다.