API 기반 인바운드 프로비전에 대해 FAQ(질문과 대답)

이 문서에서는 API 기반 인바운드 프로비전에 대해 FAQ(질문과 대답)에 답변합니다.

새로운 인바운드 프로비전/bulkUpload API는 MS Graph Users API와 어떻게 다른가요?

프로비전 /bulkUpload API와 MS Graph Users API 엔드포인트 간에는 상당한 차이가 있습니다.

• 페이로드 형식: MS Graph Users API 엔드포인트에는 OData 형식의 데이터가 필요합니다. 새로운 인바운드 프로비전 /bulkUpload API에 대한 요청 페이로드 형식은 SCIM 스키마 구문을 사용합니다. 이 API를 호출할 때 'Content-Type' 헤더를 application/scim+json으로 설정합니다.
• 작업 최종 결과:
  • ID 데이터가 MS Graph 사용자 API 엔드포인트로 전송되면 즉시 처리되고 Microsoft Entra 사용자 프로필에서 만들기/업데이트/삭제 작업이 수행됩니다.
  • 프로비전 /bulkUpload API로 전송된 요청 데이터는 Microsoft Entra 프로비전 서비스에 의해 비동기식으로 처리됩니다. 프로비전 작업은 IT 관리자가 구성한 범위 지정 규칙, 특성 매핑 및 변환을 적용합니다. 그러면 Microsoft Entra 사용자 프로필 또는 온-프레미스 AD 사용자 프로필에서 Create/Update/Delete 작업이 시작됩니다.
• IT 관리자가 제어권 보존: API 기반 인바운드 프로비전을 통해 IT 관리자는 수신 ID 데이터가 처리되고 Microsoft Entra 특성에 매핑되는 방식을 더 효과적으로 제어할 수 있습니다. 특정 형식의 ID 데이터(예: 계약자 데이터)를 제외하도록 범위 지정 규칙을 정의하고 사용자 프로필에 특성 값을 설정하기 전에 변환 함수를 사용하여 새 값을 파생할 수 있습니다.

인바운드 프로비전 /bulkUpload API가 표준 SCIM 엔드포인트인가요?

MS Graph 인바운드 프로비전 /bulkUpload API는 요청 페이로드에서 SCIM 스키마를 사용하지만 표준화된 SCIM API 엔드포인트는 아닙니다. 그 이유는 다음과 같습니다.

일반적으로 SCIM 서비스 엔드포인트는 SCIM 페이로드를 사용하여 HTTP 요청(POST, PUT, GET)을 처리하고 이를 ID 저장소의 해당 작업(만들기, 업데이트, 조회)으로 변환합니다. SCIM 서비스 엔드포인트는 ID 만들기/업데이트/삭제 여부와 같은 작업 의미 체계를 SCIM API 클라이언트에 지정하는 책임을 집니다. 이 메커니즘은 API 클라이언트가 ID 저장소의 사용자에 대해 수행할 작업을 알고 있는 시나리오에 적합합니다.

MS Graph 인바운드 프로비전 /bulkUpload는 세 가지 고유한 요구 사항에 따라 형성된 다양한 기업 ID 통합 시나리오를 처리하도록 설계되었습니다.

1. 대량의 레코드를 비동기식으로 처리하는 기능(예: 50,000개 이상의 레코드 처리)
2. 페이로드에 모든 ID 특성을 포함하는 기능(예: 비용 센터, 급여 등급, 배지 ID)
3. 작업 의미를 인식하지 못하는 API 클라이언트를 지원합니다. 이러한 클라이언트는 원시 원본 데이터(예: CSV 파일의 레코드, SQL 테이블 또는 HR 레코드)에만 액세스할 수 있는 비 SCIM API 클라이언트입니다. 이러한 클라이언트에는 각 레코드를 읽고 ID 저장소에서 Create/Update/Delete의 작업 의미를 결정하는 처리 기능이 없습니다.

MS Graph 인바운드 프로비전/bulkUpload API의 주요 목표는 고객이 Microsoft Entra 프로비전 서비스의 최종 처리를 위해 모든 ID 데이터 원본(예: CSV/SQL/HR)에서 모든 ID 데이터(예: 비용 센터, 급여 등급, 배지 ID)를 보낼 수 있도록 하는 것입니다. Microsoft Entra 프로비전 서비스는 이 엔드포인트에서 수신된 대량 페이로드 데이터를 사용하고, IT 관리자가 구성한 특성 매핑 규칙을 적용하고, 데이터 페이로드가 대상 ID 저장소(Microsoft Entra ID/온-프레미스 AD)에서 작업(만들기, 업데이트, 사용, 사용 안 함)으로 이어지는지 여부를 결정합니다.

프로비전 /bulkUpload API는 온-프레미스 Active Directory 도메인을 대상으로 지원하나요?

예, 프로비전 API는 온-프레미스 AD 도메인을 대상으로 지원합니다.

프로비전 앱에 대한 /bulkUpload API 엔드포인트를 어떻게 가져오나요?

/bulkUpload API는 "Microsoft Entra ID에 대한 API 기반 인바운드 프로비전" 및 "온-프레미스 Active Directory에 대한 API 기반 인바운드 프로비전" 형식의 앱에만 사용할 수 있습니다. 프로비전 블레이드 홈페이지에서 각 프로비전 앱에 대한 고유한 API 엔드포인트를 검색할 수 있습니다. 현재까지의 통계>기술 정보 보기에서 프로비전 API 엔드포인트 URL을 복사합니다.

다음 형식입니다.

https://graph.microsoft.com/beta/servicePrincipals/{servicePrincipalId}/synchronization/jobs/{jobId}/bulkUpload

프로비전 /bulkUpload API를 사용하여 전체 동기화를 어떻게 수행하나요?

전체 동기화를 수행하려면 API 클라이언트를 사용하여 신뢰할 수 있는 원본의 모든 사용자 데이터를 대량 요청으로 API 엔드포인트로 보냅니다. 모든 데이터를 API 엔드포인트로 전송하면 다음 동기화 주기에서 모든 사용자 기록을 처리하고 프로비전 로그 API 엔드포인트를 사용하여 진행 상황을 추적할 수 있습니다.

프로비전 /bulkUpload API를 사용하여 델타 동기화를 어떻게 수행하나요?

델타 동기화를 수행하려면 API 클라이언트를 사용하여 신뢰할 수 있는 원본에서 데이터가 변경된 사용자에 대한 정보만 보냅니다. 모든 데이터를 API 엔드포인트로 전송하면 다음 동기화 주기에서 모든 사용자 기록을 처리하고 프로비전 로그 API 엔드포인트를 사용하여 진행 상황을 추적할 수 있습니다.

프로비전 다시 시작은 어떻게 작동하나요?

필요한 경우에만 프로비전 다시 시작 옵션을 사용합니다. 작동 방법은 다음과 같습니다.

시나리오 1:프로비전 다시 시작 단추를 클릭하고 작업이 현재 실행 중인 경우 작업은 이미 준비된 기존 데이터를 계속 처리합니다. 프로비전 다시 시작 작업은 기존 주기를 중단하지 않습니다. 후속 주기에서 프로비전 서비스는 모든 에스크로를 지우고 처리할 새 대량 요청을 선택합니다.

시나리오 2:프로비전 다시 시작 단추를 클릭했는데 작업이 실행되지 않는 경우 후속 주기를 실행하기 전에 프로비전 엔진은 다시 시작 전의 업로드 데이터를 제거하고 에스크로를 모두 지우며 새로 들어오는 데이터만 처리합니다.

프로비전 /bulkUpload API 엔드포인트를 사용하여 사용자를 어떻게 만드나요?

/bulkUpload API 엔드포인트와 연결된 프로비전 작업이 수신 사용자 페이로드를 처리하는 방법은 다음과 같습니다.

1. 작업은 프로비전 작업에 대한 특성 매핑을 검색하고 일치하는 특성 쌍을 기록합니다(기본적으로 externalId API 특성은 Microsoft Entra ID의 employeeId와 일치하는 데 사용됨).
2. 이 기본 특성 일치 쌍을 변경할 수 있습니다.
3. 작업은 대량 요청 페이로드에 있는 각 작업을 추출합니다.
4. 작업은 요청의 식별자(기본적으로 externalId 특성)와 일치하는 값을 확인하고 이를 사용하여 Microsoft Entra ID에 employeeId 값과 일치하는 사용자가 있는지 확인합니다.
5. 작업에서 일치하는 사용자를 찾지 못하면 동기화 규칙을 적용하고 대상 디렉터리에 새 사용자를 만듭니다.

Microsoft Entra ID에서 올바른 사용자가 만들어지도록 하려면 원본 및 Microsoft Entra ID에서 사용자를 고유하게 식별하는 매핑에서 올바른 일치 특성 쌍을 정의합니다.

UPN에 대한 고유한 값을 어떻게 생성하나요?

프로비전 서비스는 중복된 userPrincipalName(UPN)을 확인하고 충돌을 처리하는 기능을 제공하지 않습니다. UPN 특성에 대한 기본 동기화 규칙이 기존 UPN 값을 만드는 경우 사용자 만들기 작업이 실패합니다.

고유한 UPN을 생성하기 위해 고려할 수 있는 몇 가지 옵션은 다음과 같습니다.

1. API 클라이언트에 고유한 UPN 생성을 위한 논리를 추가합니다.
2. RandomString 함수를 사용하고 적용 매핑 매개 변수를 On object creation only로 설정하려면 UPN 특성에 대한 동기화 규칙을 업데이트합니다. 예시:

Join("", Replace([userName], , "(?<Suffix>@(.)*)", "Suffix", "", , ), RandomString(3, 3, 0, 0, 0, ), "@", DefaultDomain())

3. 온-프레미스 Active Directory에 프로비전하는 경우 SelectUniqueValue 함수를 사용하고 적용 매핑 매개 변수를 On object creation only로 설정할 수 있습니다.

프로비전 /bulkUpload API 엔드포인트에 더 많은 HR 특성을 보내려면 어떻게 해야 하나요?

기본적으로 API 엔드포인트는 SCIM 코어 사용자 및 엔터프라이즈 사용자 스키마의 일부인 모든 특성 처리를 지원합니다. 더 많은 특성을 보내려면 프로비전 앱 스키마를 확장하고, 새 특성을 Microsoft Entra 특성에 매핑하고, 대량 요청을 업데이트하여 해당 특성을 보낼 수 있습니다. API 기반 프로비전을 확장하여 사용자 지정 특성 동기화 자습서를 참조하세요.

프로비전 흐름에서 특정 사용자를 어떻게 제외하나요?

모든 사용자를 API 엔드포인트로 보내지만 프로비전 흐름에 특정 사용자만 포함하고 나머지는 제외하려는 시나리오가 있을 수 있습니다.

범위 지정 필터를 사용하여 이를 달성할 수 있습니다. 원본 개체 범위를 정의하고 "포함 규칙"(예: 부서가 Sales와 같은 사용자만 처리) 또는 "제외 규칙"(예: Sales에 속하고, 부서가 Sales와 같지 않은 사용자 제외)을 사용하여 처리에서 특정 사용자를 제외할 수 있습니다.

범위 지정 필터로 프로비전할 사용자 또는 그룹 범위 지정을 참조하세요.

프로비전 /bulkUpload API 엔드포인트를 사용하여 사용자를 어떻게 업데이트하나요?

/bulkUpload API 엔드포인트와 연결된 프로비전 작업이 수신 사용자 페이로드를 처리하는 방법은 다음과 같습니다.

1. 프로비전 작업은 프로비전 작업에 대한 특성 매핑을 검색하고 일치하는 특성 쌍을 기록합니다(기본적으로 externalId API 특성은 Microsoft Entra ID의 employeeId와 일치하는 데 사용됨). 이 기본 특성 일치 쌍을 변경할 수 있습니다.
2. 작업은 대량 요청 페이로드에서 작업을 추출합니다.
3. 작업은 SCIM 요청(기본적으로 API 특성 externalId)에서 식별자와 일치하는 값을 확인하고 이를 사용하여 Microsoft Entra ID에 employeeId 값과 일치하는 사용자가 있는지 확인합니다.
4. 작업에서 일치하는 사용자를 찾으면 동기화 규칙을 적용하고 원본 프로필과 대상 프로필을 비교합니다.
5. 작업에서 일부 값이 변경된 것으로 확인되면 디렉터리에서 해당 사용자 레코드를 업데이트합니다.

올바른 사용자가 Microsoft Entra ID에서 업데이트되도록 하려면 원본 및 Microsoft Entra ID에서 사용자를 고유하게 식별하는 매핑에서 올바른 일치 특성 쌍을 정의해야 합니다.

API 기반 인바운드 프로비전을 지원하는 앱을 두 개 이상 만들 수 있나요?

예, 가능합니다. 다음은 둘 이상의 프로비전 앱이 필요할 수 있는 몇 가지 시나리오입니다.

시나리오 1: 신뢰할 수 있는 데이터 원본이 세 개(직원용, 계약자용, 공급업체용) 있다고 가정해 보겠습니다. 고유한 특성 매핑을 사용하여 각 ID 유형에 대해 하나씩 세 가지 별도의 프로비전 앱을 만들 수 있습니다. 각 프로비전 앱에는 고유한 API 엔드포인트가 있으며 각 엔드포인트에 해당 페이로드를 보낼 수 있습니다.

프로비전 블레이드 홈페이지에서 각 작업에 대한 고유한 API 엔드포인트를 검색할 수 있습니다. 현재까지의 통계>기술 정보 보기로 이동한 다음 프로비전 API 엔드포인트 URL을 복사합니다.

시나리오 2: 각각 고유한 특성이 설정된 여러 정보 원본이 있다고 가정해 보겠습니다. 예를 들어, HR은 직업 정보 특성(예: jobTitle, EmployeeType)을 제공하고 배지 시스템은 배지 정보 특성(예: 확장 특성을 사용하여 표시되는 badgeId)을 제공합니다. 이 시나리오에서는 두 가지 프로비전 앱을 구성할 수 있습니다.

• 프로비전 앱 #1 HR 원본으로부터 특성을 수신하고 사용자를 만듭니다.

• 프로비전 앱 #2 배지 시스템에서 특성을 수신하고 사용자 특성만 업데이트합니다. 이 앱의 특성 매핑은 배지 정보 특성으로 제한되며 대상 개체 작업에서는 업데이트만 사용하도록 설정됩니다.

• 두 앱 모두 동일한 일치 식별자 쌍(externalId<->employeeId)을 사용합니다.

/bulkUpload API 엔드포인트를 사용하여 종료를 어떻게 처리하나요?

종료를 처리하려면 Microsoft Entra ID에서 accountEnabled 플래그를 설정하는 데 사용될 원본의 특성을 식별합니다. 온-프레미스 Active Directory에 프로비전하는 경우 해당 원본 특성을 accountDisabled 특성에 매핑합니다.

기본적으로 SCIM 코어 사용자 스키마 특성 active와 연관된 값은 대상 디렉터리의 사용자 계정 상태를 결정합니다.

특성이 true로 설정된 경우 기본 매핑 규칙에 따라 계정이 사용하도록 설정됩니다. 특성이 false로 설정된 경우 기본 매핑 규칙에 따라 계정이 사용하지 않도록 설정됩니다.

실수로 사용자를 사용하지 않도록 설정하거나 삭제하는 것을 방지하려면 어떻게 해야 하나요?

실수로 인한 삭제를 방지하고 복구하려면 프로비전 앱에서 실수로 인한 삭제 임계값을 구성하고 온-프레미스 Active Directory 휴지통을 사용하도록 설정하는 것이 좋습니다. 프로비전 앱의 특성 매핑 블레이드에 있는 대상 개체 작업에서 삭제 작업을 사용하지 않도록 설정합니다.

삭제된 계정 복구

• 작업의 대상 디렉터리가 Microsoft Entra ID인 경우 일치하는 사용자가 일시 삭제됩니다. 해당 사용자는 앞으로 30일 동안 Microsoft Entra 관리 센터의 삭제된 사용자 페이지에서 볼 수 있으며 해당 기간 동안 복원될 수 있습니다.
• 작업의 대상 디렉터리가 온-프레미스 Active Directory인 경우 일치하는 사용자가 영구 삭제됩니다. Active Directory 휴지통이 사용하도록 설정된 경우 삭제된 온-프레미스 AD 사용자 개체를 복원할 수 있습니다.

요청할 때마다 HR 시스템의 모든 사용자를 보내야 하나요?

아니요, 모든 요청에서 HR 시스템/"진실 원본"의 모든 사용자를 보낼 필요는 없습니다. 만들거나 업데이트하려는 사용자를 보냅니다.

API는 모든 HTTP 작업(GET/POST/PUT/PATCH)을 지원하나요?

아니요, /bulkUpload 프로비전 API 엔드포인트는 POST HTTP 작업만 지원합니다.

사용자를 업데이트하려면 PUT/PATCH 요청을 보내야 하나요?

아니요, API 엔드포인트는 PUT/PATCH 요청을 지원하지 않습니다. 사용자를 업데이트하려면 POST 대량 요청 페이로드에서 사용자와 연결된 데이터를 보냅니다.

API 엔드포인트에서 수신한 데이터를 처리하는 프로비전 작업은 POST 요청 페이로드에서 수신된 사용자를 구성된 동기화 규칙에 따라 만들기/업데이트/사용/사용 안 함 작업이어야 하는지 자동으로 검색합니다. API 클라이언트로서 사용자 프로필을 업데이트하려는 경우 추가 단계를 수행할 필요가 없습니다.

쓰기 저장은 어떻게 지원되나요?

현재 API는 인바운드 데이터만 지원합니다. 다음은 Microsoft Entra ID에서 생성된 이메일/사용자 이름/전화와 같은 특성의 쓰기 저장을 구현하기 위해 고려해야 할 몇 가지 옵션이며 HR 시스템으로 다시 흐를 수 있습니다.

• 옵션 1 – HR 원본을 업데이트하는 HR 엔드포인트/프록시 서비스에 대한 SCIM 연결

  • 기록 시스템이 사용자 업데이트를 위한 SCIM 엔드포인트를 제공하는 경우 엔터프라이즈 앱 갤러리에서 사용자 지정 SCIM 애플리케이션을 만들고 문서화된 대로 프로비전을 구성할 수 있습니다.
  • 기록 시스템이 SCIM 엔드포인트를 제공하지 않는 경우 업데이트를 수신하고 변경 내용을 HR 시스템에 전파하는 프록시 SCIM 서비스를 설정할 가능성을 살펴봅니다.

• 옵션 2 – 쓰기 저장 시나리오에 Microsoft Entra ECMA 커넥터 사용

  • 고객 요구 사항에 따라 ECMA 커넥터 중 하나를 사용할 수 있는지 살펴봅니다(PowerShell/SQL/웹 서비스).

• 옵션 3 – 입사자 워크플로에서 수명 주기 워크플로 사용자 지정 확장 작업 사용

  • 수명 주기 워크플로에서 입사자 워크플로를 정의하고 HR 시스템을 업데이트하거나 HR 시스템에서 사용하는 CSV 파일을 생성하는 Logic Apps 프로세스를 호출하는 사용자 지정 확장 작업을 정의합니다.

다음 단계

• API 기반 인바운드 프로비전 앱 구성
• API 기반 인바운드 프로비전에 대해 자세히 알아보려면 인바운드 사용자 프로비전 API 개념을 참조하세요.