SCIM 2.0으로 사용자 및 팀 관리 자동화하기

Okta 또는 Microsoft Entra ID와 같은 ID 공급자(IdP)를 통해 ProtoPie Enterprise의 사용자 계정과 팀을 자동으로 관리하도록 SCIM 2.0(System for Cross-domain Identity Management)을 구성하는 방법을 알아봅니다.

SCIM이란?

IdP(예: Okta 또는 Microsoft Entra ID)에서 사용자를 추가하거나 비활성화하고 그룹 멤버십을 변경하면 ProtoPie Cloud의 해당 계정과 팀이 자동으로 업데이트됩니다. 퇴사자의 계정에 초대 이메일을 보내거나 직접 비활성화할 필요가 없습니다.

사전 준비 사항

• Enterprise 플랜(Private Cloud 또는 On-Premises)을 사용해야 합니다.

• SCIM은 인증이 아니라 사용자 계정 생성과 수명 주기 관리를 담당하므로, SCIM을 활성화하기 전에 SSO(SAML 또는 OIDC)를 먼저 활성화해야 합니다.

• ProtoPie Enterprise 관리자 계정과 IdP 관리 콘솔의 관리자 권한이 필요합니다.

• 참고: Google Workspace는 맞춤 앱 통합에 SCIM을 지원하지 않습니다.

ProtoPie에서 SCIM 준비하기

1) SCIM 및 그룹 프로비저닝 활성화

1. Organization Settings(조직 설정) → Authentication(인증)으로 이동해 SSO가 활성화되어 있는지 확인합니다.

2. On the User Provisioning screen, toggle SCIM 2.0 to On. If SSO is turned off, the request will be rejected with the message: "Please enable SSO first."

3. To synchronize down to the team level, also enable the Group provisioning toggle. If left disabled, group pushes from the IdP will be rejected, while user synchronization will continue.

2) Issue a Token and Copy the Base URL

1. SCIM 2.0 섹션에서 Update를 눌러 토큰을 발급합니다.

2. Copy 버튼을 눌러 표시된 Bearer Token을 복사하고 비밀번호 관리자와 같은 안전한 장소에 보관합니다. 토큰은 이 화면에서 한 번만 표시되며, 나중에 다시 확인할 수 없습니다.

   
   

   

3. 다음 형식의 Base URL을 복사합니다: https://<your-protopie-host>/api/scim/v2

참고: URL 끝에 /api/scim/v2를 포함하지 않으면 IdP 연결 테스트가 실패합니다.
☝️중요한 토큰 규칙: 새 토큰을 발급하면 기존 토큰은 즉시 폐기됩니다. 조직당 유효한 토큰은 하나만 사용할 수 있습니다. IdP에 연결된 상태에서 토큰을 다시 발급하면, IdP에 저장된 토큰도 새 값으로 업데이트해야 동기화를 계속할 수 있습니다.

3) 연결 상태 확인

SCIM 화면 상단의 상태 배지에는 다음 네 가지 상태 중 하나가 표시됩니다.

Okta 연동

앱 선택 가이드

• 표준 가이드: Okta 카탈로그에서 "SCIM 2.0 Test App (Header Auth)"을 추가합니다. Basic Auth 버전은 사용하지 마세요. ProtoPie SCIM 인증은 Authorization: Bearer 토큰만 허용하므로 Basic Auth 앱의 연결 테스트는 401 오류로 실패합니다.

• 기존 SAML 2.0 또는 SWA 앱: App Integration Wizard로 만든 앱이라면 General App Settings → Edit Provisioning: SCIM에서 SCIM을 활성화해 같은 앱에 연결(카탈로그 앱에는 이 설정이 없으며 Provisioning 탭이 처음부터 표시)합니다. OIDC 앱에는 SCIM 옵션이 없습니다.

• 구성 규칙: Okta에서 수동으로 만든 앱은 하나의 앱에서 OIDC와 SCIM을 함께 사용할 수 없습니다.

• SSO가 OIDC인 경우: 로그인용 OIDC 앱과 프로비저닝용 SCIM 2.0 Test App (Header Auth)을 별도로 사용합니다. 두 앱에 같은 Okta 사용자 그룹을 할당합니다.

• SSO가 SAML인 경우: App Integration Wizard에서 SAML 2.0 앱 하나를 만들고 General App Settings → Provisioning에서 SCIM을 활성화하면 로그인과 프로비저닝을 한 앱에서 처리할 수 있습니다.

Okta 단계별 설정

1. SAML 또는 SWA 앱에서 SCIM을 활성화합니다(해당하는 경우). General 탭에서 App Settings → Edit → Provisioning으로 이동하고 SCIM을 선택한 뒤 저장합니다. 프로비저닝이 이미 제공되는 카탈로그 앱을 사용한다면 이 단계를 건너뜁니다.

   
   

   

2. API integration을 구성합니다. Provisioning → Configure API Integration으로 이동해 Enable API Integration을 선택하고 다음 정보를 입력합니다.

• Base URL: ProtoPie에서 복사한 Base URL(https://<host>/api/scim/v2)을 붙여 넣습니다.

• API Token: Bearer 접두사(prefix, 공백 포함) 뒤에 ProtoPie에서 복사한 토큰을 붙여 넣습니다(예: Bearer abc123…). Okta에서는 이 접두사가 필요합니다. Microsoft Entra ID 등 다른 IdP에서는 접두사 없이 토큰 값만 입력합니다.

• SAML 또는 SWA 앱의 경우: Okta에 Integration → Edit 화면이 표시됩니다. 위와 같이 SCIM connector base URL을 입력하고, “Unique identifier field for users”에서 “userName”을 선택합니다. “Supported provisioning actions”에서 “Push New Users”, “Push Profile Updates”, “Push Groups”를 선택합니다. “Authentication Mode”를 “HTTP Header”로 설정하고 “Authorization” 필드에 Bearer 접두사와 토큰 값을 함께 입력합니다.

3. 연결을 테스트하고 저장합니다. Test API Credentials를 누릅니다. SAML 또는 SWA 앱에서는 Test Connector Configuration을 누릅니다. 테스트에 성공하면 Save를 클릭합니다. Okta가 ProtoPie에 GET /Users 요청을 보내면 ProtoPie의 연결 상태가 Connected로 바뀝니다.

4. 사용자 lifecycle 작업을 활성화합니다. Provisioning → To App에서 Create Users, Update User Attributes, Deactivate Users를 켭니다. SAML 또는 SWA 앱에서는 Supported provisioning actions에서 Push New Users를 활성화하고 구성을 저장해야 To App이 표시됩니다. Push Groups를 활성화하면 Push Groups 탭도 추가됩니다. 카탈로그 앱에서는 이러한 옵션을 기본으로 사용할 수 있습니다.

5. 속성 매핑을 검토합니다. 다음 매핑이 구성되어 있는지 확인합니다.

   

userName ← user.email (ProtoPie는 이메일 주소를 사용자 이름으로 사용합니다.)

• givenName ← user.firstName

• familyName ← user.lastName

• 전화번호처럼 ProtoPie에서 사용하지 않는 속성의 매핑은 제거합니다.

6. 사용자 또는 그룹을 할당합니다. Assignments 탭에서 ProtoPie에 액세스할 사용자나 그룹을 할당합니다. 사용자가 할당되면 Okta가 ProtoPie 계정을 생성합니다. OIDC처럼 SSO와 SCIM 앱을 별도로 사용하는 경우 인증과 프로비저닝이 일치하도록 사용자에게 두 앱 모두 할당합니다. 관리 편의를 위해 ProtoPie Users와 같은 Okta 그룹 하나를 만들어 두 앱 모두에 할당할 수 있습니다. SSO 앱에서만 사용자를 제거하면 ProtoPie 계정은 비활성화되지 않습니다. SCIM 앱에서도 해당 사용자를 제거해야 합니다.

7. 그룹을 푸시해 팀을 동기화합니다. Push Groups 탭에서 동기화할 Okta 그룹을 추가합니다. ProtoPie는 Okta 그룹 이름으로 해당 팀을 생성합니다.

☝️Okta는 변경 사항을 즉시 전송합니다. 사용자를 할당하거나 할당 해제한 뒤 몇 초 안에 ProtoPie의 People 목록에서 확인할 수 있습니다. 확인 후 ProtoPie의 연결 상태가 “Connected”로 바뀌었는지도 확인하세요.

Microsoft Entra ID 연동

☝️시작하기 전에 올바른 앱을 선택하세요. Provisioning 메뉴는 Enterprise applications 아래의 비갤러리(non-gallary) 앱에서만 사용할 수 있습니다. SSO에 SAML을 사용한다면 동일한 비갤러리(non-gallary) 앱에서 SSO와 SCIM 프로비저닝을 구성합니다. App registrations를 통한 OIDC를 사용한다면 프로비저닝용 비갤러리(non-gallary) 엔터프라이즈 앱을 별도로 만듭니다. 인증과 계정 프로비저닝이 일치하도록 OIDC 앱과 프로비저닝 앱에 같은 사용자와 그룹을 할당합니다.

1. entra.microsoft.com에 들어가서 → Entra ID → Enterprise applications로 이동한 다음 ProtoPie에 사용할 비갤러리(non-gallery) 앱을 엽니다. 앱이 없다면 + New application → + Create your own application을 선택하고 이름을 입력한 뒤 **Integrate any other application you don’t find in the gallery (Non-gallery)**를 선택하고 Create를 클릭합니다. 앱 생성 후 왼쪽 사이드바의 Manage 아래에 Provisioning이 표시되는지 확인합니다. App registrations에서 만든 OIDC 앱에는 이 메뉴가 표시되지 않습니다.

2. 왼쪽 사이드바에서 Provisioning을 열고 + New configuration을 클릭합니다. 자동 프로비저닝이 기본으로 선택되어 있습니다. 이전 Entra 인터페이스에서는 Get started를 선택한 다음 Provisioning Mode를 Automatic으로 설정합니다.

3. ProtoPie SCIM 자격 증명을 입력합니다.

• Tenant URL: ProtoPie에서 복사한 Base URL(https://<host>/api/scim/v2)을 붙여 넣습니다.

• Secret Token: ProtoPie에서 복사한 토큰을 붙여 넣습니다.

4. Test Connection을 클릭합니다. 테스트에 성공하면 Save를 클릭합니다. Entra가 ProtoPie에 GET /Users?filter=… 요청을 보내면 연결 상태가 Connected로 바뀝니다. 테스트 시간이 초과되면 방화벽에서 Microsoft Entra 프로비저닝 서비스 IP 범위의 트래픽을 허용하는지 확인합니다.

5. Mappings → Provision Microsoft Entra ID Users를 열고 다음 매핑을 확인합니다.

   

   • userName ← mail. ProtoPie는 userName을 로그인 이메일로 사용하므로 기본값인 userPrincipalName 대신 mail을 사용합니다.

   • active ← IsSoftDeleted에 기반한 빌트인(built-in) Switch 표현식을 유지합니다. Entra에서 사용자를 할당 해제하거나 비활성화하면 ProtoPie에 active: false가 전송됩니다.

   • name.givenName ← givenName

   • name.familyName ← surname

   • externalId ← objectId

   • 주소나 전화번호처럼 ProtoPie에서 사용하지 않는 속성의 매핑은 제거합니다.

   6. Provision Microsoft Entra ID Groups를 Enabled로 설정합니다. Entra는 각 그룹의 displayName을 해당 ProtoPie 팀 이름으로 사용합니다.

      

   
   

   7. Provisioning → Overview(이전 이름: Settings)에서 Scope를 Sync only assigned users and groups로 설정합니다. 이렇게 하면 Entra가 디렉터리의 모든 사용자와 그룹을 프로비저닝하려고 시도하지 않습니다.

      

   8. Users and groups를 열고 ProtoPie에 프로비저닝할 사용자와 그룹을 할당합니다. 권장 범위를 선택하면 할당된 개체만 동기화됩니다.

      

   
   

   9. Provisioning status를 On으로 설정하고 Save를 클릭합니다. 이전 인터페이스에서는 Start provisioning을 클릭하는 것과 같습니다. 나중에 동기화를 일시 중지하려면 상태를 Off로 설정합니다.

      

   ☝️Microsoft Entra runs an incremental synchronization cycle approximately every 40 minutes, so newly assigned users and groups may not appear in ProtoPie immediately. To test without waiting for the next cycle, select a user, run Provision on demand, and review the result in Provisioning logs.

   

ProtoPie의 SCIM 관리 계정

사용자 계정 관리

동기화가 완료되면 ProtoPie는 SCIM으로 관리되는 계정을 표시하고 IdP와 충돌할 수 있는 변경을 제한합니다.

• SCIM 관리 사용자를 식별합니다. 관리되는 계정은 People 목록에서 SCIM 배지로 표시됩니다. 목록 상단의 SCIM 필터를 사용하면 전체 사용자, SCIM 관리 사용자만 또는 SCIM으로 관리되지 않는 사용자만 표시할 수 있습니다.

  

  
  

• 계정 상세 정보를 IdP에서 관리합니다. SCIM 관리 사용자의 이름, 이메일 주소, 활성 상태 및 계정 삭제 여부는 ProtoPie에서 변경할 수 없습니다. IdP에서 변경하면 다음 동기화 시 ProtoPie에 반영됩니다. 사용자 행의 메뉴(⋯)에서는 이메일 변경 및 계정 비활성화 옵션이 사라지고 Reset MFA만 남습니다.

  

• 사용자는 관리되는 프로필 상세 정보를 수정할 수 없습니다. 계정 설정에서 SCIM 관리 사용자의 이름과 이메일 입력란은 비활성화되며 Account managed by IdP 메시지가 표시됩니다. 정보를 변경하려면 관리자에게 문의하거나 조직의 ID 관리 절차를 따라야 합니다.

  

• 사용자는 SSO로만 로그인합니다. SCIM 관리 계정에는 ProtoPie 비밀번호가 없으며 ProtoPie 기본 제공 MFA도 적용되지 않습니다. People 목록의 MFA 열에는 Not applicable로 표시됩니다. SCIM 활성화 전에 사용하던 ProtoPie 비밀번호가 제거된다는 점을 기존 사용자에게 안내하세요.

  
  

  

• ProtoPie에서 역할과 프로필 사진은 계속 수정할 수 있습니다. 관리자는 사용자의 ProtoPie 역할(Admin 또는 Member)을 변경할 수 있고, 사용자는 프로필 사진을 업데이트할 수 있습니다.

팀 관리

그룹 프로비저닝이 활성화되면 IdP에서 ProtoPie 팀 생성과 멤버십을 관리합니다.

• 첫 번째 구성원이 동기화될 때 팀이 생성됩니다. IdP 그룹은 첫 구성원이 추가될 때 ProtoPie 팀이 됩니다. 새 팀 구성원은 처음에 Viewer로 참여하며 관리자가 ProtoPie에서 역할을 승격할 수 있습니다.

  

• 팀 멤버십은 IdP에서 관리합니다. ProtoPie에서는 IdP 관리 멤버를 추가하거나 초대 또는 제거할 수 없습니다. SCIM 관리 팀과 구성원에는 SCIM 배지가 표시되고 Invite new member 버튼은 비활성화됩니다. 멤버십을 변경하려면 IdP에서 해당 그룹을 수정합니다.

  

• 자동 지정된 팀 소유자를 확인합니다. 팀이 생성되면 ProtoPie는 계정 생성일이 가장 오래된 조직 관리자를 소유자로 지정합니다. 다른 사람이 팀을 소유해야 한다면 동기화 후 ProtoPie에서 소유자를 변경합니다.

• 팀 이름은 고유해야 합니다. 조직에 같은 이름의 팀이 둘 이상 있으면 이름이 일치하는 IdP 그룹의 동기화가 409 고유성 오류로 실패합니다. ProtoPie에서 기존 팀 이름을 바꿔 각 팀 이름을 고유하게 만든 뒤 IdP에서 그룹 동기화를 다시 시도합니다.

• IdP 그룹을 삭제해도 ProtoPie 콘텐츠는 삭제되지 않습니다. 연결된 팀과 파일은 ProtoPie에 남고 IdP 그룹과의 연결만 제거됩니다.

일상적인 SCIM 관리

SCIM 사용자와 팀 멤버십은 IdP를 기본 관리 위치로 사용합니다.

• 신규 입사자: IdP에서 사용자를 ProtoPie 프로비저닝 앱에 할당합니다. ProtoPie가 계정을 자동 생성하며 사용자는 SSO로 로그인합니다.

• 퇴사자: IdP에서 사용자의 할당을 해제하거나 계정을 비활성화합니다. ProtoPie는 계정을 비활성화하지만 데이터를 보존합니다. 계정을 영구 삭제해야 한다면 ProtoPie 관리자가 별도로 처리해야 합니다.

• 이메일 주소 변경: SCIM 연동 후 IdP에서 변경한 이메일 주소는 ProtoPie에 자동 적용되지 않습니다. 이메일 주소 변경이 필요하면 ProtoPie Support에 문의하세요.

• 팀 멤버십 변경: IdP에서 해당 그룹에 사용자를 추가하거나 제거합니다. SCIM으로 관리되는 멤버십을 ProtoPie에서 변경하지 마세요.

SCIM 문제 해결

• 연결 테스트에서 401 Unauthorized 오류가 발생하는 경우: 토큰이 잘못되었거나 만료되었거나 복사 과정에서 오류가 있었을 수 있습니다. 토큰을 다시 발급하면 기존 토큰이 즉시 무효화됩니다. ProtoPie에 Reconnection required가 표시되면 IdP의 토큰을 업데이트하고 연결 테스트를 다시 실행합니다.

• 연결 테스트에서 403 Forbidden 오류가 발생하는 경우: ProtoPie에서 SCIM 2.0 토글이 꺼져 있습니다. 토글을 켠 다음 연결 테스트를 다시 실행합니다.

• 연결 테스트에서 404 Not Found 오류가 발생하는 경우: Base URL에 /api/scim/v2가 포함되어 있는지, 조직이 대상 Enterprise 플랜을 사용 중인지 확인합니다.

• 그룹 구성원이 ProtoPie 팀에 나타나지 않는 경우: 사용자가 프로비저닝 앱에 할당되지 않았을 수 있습니다. 먼저 사용자를 할당한 다음 IdP에서 그룹을 다시 시도하거나 저장합니다.

• 프로비저닝이 409 고유성 오류로 실패하는 경우: 같은 이메일 주소의 계정이나 같은 이름의 팀이 이미 ProtoPie에 있을 수 있습니다. IdP 로그에서 구체적인 충돌을 확인하고 중복을 해결한 뒤 동기화를 다시 시도합니다.

  • Okta: Apps → Push Groups에서 영향을 받은 그룹을 열거나, Reports → System Log에서 해당 이벤트를 열고 Debug Data의 응답 본문을 확인합니다.

  • Microsoft Entra: Provisioning logs에서 실패 항목을 열고 Troubleshooting & Recommendations를 확인합니다.

  • 충돌을 해결하면 Okta는 그룹 푸시를 다시 시도합니다. Microsoft Entra는 다음 동기화 주기에 변경 사항을 적용하며, Provision on demand를 실행해 즉시 처리할 수도 있습니다.

• Microsoft Entra에서 프로비저닝이 격리 상태(quarantine)가 되는 경우: 일시적인 서버 또는 구성 오류가 반복되면 Entra가 프로비저닝을 일시 중지할 수 있습니다. Provisioning logs에서 최신 오류를 확인하고 원인을 해결한 뒤 Restart provisioning을 클릭합니다.

SCIM 일시 중지 또는 연결 해제

동기화를 잠시 중지할지 SCIM 연결을 완전히 제거할지에 따라 적절한 방법을 선택합니다.

• 동기화를 일시 중지하려면: SCIM 2.0 토글을 끕니다. 매핑과 토큰은 설정된 상태로 유지되지만 SCIM을 다시 켤 때까지 ProtoPie가 프로비저닝 요청을 거부합니다. 동기화가 중지된 동안에도 SCIM 관리 사용자와 팀의 편집 제한은 유지됩니다.

• 사용자 또는 팀 하나의 연결만 해제하려면: People 또는 Teams에서 항목을 찾아 Unlink from IdP를 클릭합니다. 연결 해제된 사용자는 ProtoPie 비밀번호가 없을 수 있으므로 SSO 없이 로그인하기 전에 비밀번호 재설정 절차를 안내합니다.

• 사용자 또는 팀을 다시 연결하려면: IdP의 프로비저닝 앱에 사용자 또는 그룹을 다시 할당한 다음 전체 동기화를 실행합니다.