API 기반 인바운드 프로비저닝에 대한 질문과 대답

이 문서에서는 API 기반 인바운드 프로비저닝에 대한 FAQ(질문과 대답)를 제공합니다.

새 인바운드 프로비저닝 /bulkUpload API는 MS Graph 사용자 API와 어떻게 다른가요?

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

• 페이로드 형식: MS Graph 사용자 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 서비스 엔드포인트는 SCIM API 클라이언트에서 ID를 생성/업데이트/삭제할지 여부에 관계없이 작업 의미 체계를 지정합니다. 이 메커니즘은 API 클라이언트가 ID 저장소의 사용자에 대해 수행하려는 작업을 인식하는 시나리오에 적합합니다.

MS Graph 인바운드 프로비저닝 /bulkUpload는 다음과 같은 세 가지 고유한 요구 사항에 따라 다른 엔터프라이즈 ID 통합 시나리오를 처리하도록 설계되었습니다.

1. 대량으로 레코드를 비동기적으로 처리하는 기능(예: 50K+ 레코드 처리)
2. 페이로드에 ID 특성을 포함하는 기능(예: costCenter, pay grade, badgeId)
3. 작업 의미 체계를 인식하지 못하는 API 클라이언트를 지원합니다. 이러한 클라이언트는 원시 원본 데이터 (예: CSV 파일, SQL 테이블 또는 HR 레코드의 레코드)에만 액세스할 수 있는 SCIM이 아닌 API 클라이언트입니다. 이러한 클라이언트에는 각 레코드를 읽고 ID 저장소의 작업 의미 체계 Create/Update/Delete 를 결정하는 처리 기능이 없습니다.

MS Graph 인바운드 프로비전 /bulkUpload API의 주요 목표는 고객이 아이덴티티 데이터 원본(예: CSV/SQL/HR)에서 아이덴티티 데이터(예: costCenter, pay grade, badgeId)를 Microsoft Entra 프로비저닝 서비스에서 최종 처리를 위해 보낼 수 있도록 하는 것입니다. 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)를 확인하고 이를 사용하여 일치하는 employeeId 값을 가진 Microsoft Entra ID에 사용자가 있는지 확인합니다.
5. 작업에서 일치하는 사용자를 찾을 수 없는 경우 작업은 동기화 규칙을 적용하고 대상 디렉터리에 새 사용자를 만듭니다.

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

UPN에 대한 고유 값을 생성하려면 어떻게 해야 할까요?

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

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

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

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 Core 사용자 및 엔터프라이즈 사용자 스키마의 일부인 모든 특성 처리를 지원합니다. 더 많은 특성을 보내려면 프로비전 앱 스키마를 확장하고, 새 특성을 Microsoft Entra 특성에 매핑하고, 대량 요청을 업데이트하여 해당 특성을 보낼 수 있습니다. 사용자 지정 특성을 동기화하려면 API 기반 프로비저닝 확장 자습서를 참조하세요.

프로비저닝 흐름에서 특정 사용자를 제외하려면 어떻게 해야 할까요?

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

범위 지정 필터를 사용하여 이 작업을 수행할 수 있습니다. 프로비저닝 앱 구성에서 소스 개체 범위를 정의하고, "포함 규칙" (예: 부서가 EQUALS Sales인 사용자만 처리) 또는 "제외 규칙" (예: 부서가 NOT EQUALS Sales인 Sales 부서에 속하지 않은 사용자를 제외)을 사용하여 특정 사용자를 처리 대상에서 제외할 수 있습니다.

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

프로비저닝 /bulkUpload API 엔드포인트를 사용하여 사용자를 업데이트하려면 어떻게 해야 할까요?

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

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

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

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

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

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

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

시나리오 2: 각각 고유한 특성이 설정된 여러 소스가 있다고 가정해 보겠습니다. 예를 들어 HR은 작업 정보 특성(예: jobTitle, employeeType)을 제공하고 Badging System은 배지 정보 특성(예: badgeId 확장 특성을 사용하여 표현됨)을 제공합니다. 이 시나리오에서는 다음 두 개의 프로비저닝 앱을 구성할 수 있습니다.

• 프로비저닝 앱 #1은 HR 원본에서 특성을 받아 사용자를 생성합니다.

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

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

/bulkUpload API 엔드포인트를 사용하여 종료를 처리하려면 어떻게 해야 할까요?

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

기본적으로 SCIM Core 사용자 스키마 특성 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는 인바운드 데이터만 지원합니다. 다음은 HR 시스템으로 다시 흐를 수 있는 Microsoft Entra ID에서 생성된 이메일/사용자 이름/전화와 같은 특성의 쓰기 저장을 구현하기 위해 고려할 몇 가지 옵션입니다.

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

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

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

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

• 옵션 3 - 라이프사이클 워크플로 사용자 지정 확장 작업을 가입자 워크플로에서 사용

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

다음 단계

• API 기반 인바운드 프로비전 앱 구성
• API 기반 인바운드 프로비저닝에 대한 자세한 내용은 인바운드 사용자 프로비저닝 API 개념을 참조하세요.