Hub documentation
사용자 프로비저닝(SCIM)
사용자 프로비저닝(SCIM)
이 기능은 Enterprise 및 Enterprise Plus 플랜의 일부입니다.
SCIM(System for Cross-domain Identity Management)은 사용자 프로비저닝을 자동화하기 위한 표준입니다. 이를 통해 Identity Provider(IdP)를 Hugging Face에 연결하여 조직의 구성원을 관리할 수 있습니다.
SCIM은 SSO 모델에 따라 동작 방식이 다릅니다. 자세한 비교는 SSO 개요를 참고하세요.
기본 SSO: 초대 기반 프로비저닝
Basic SSO(Enterprise 플랜)를 사용하면 SCIM을 통해 기존 Hugging Face 사용자를 조직에 초대하는 과정을 자동화할 수 있습니다.
- SCIM을 통해 프로비저닝하려면 사용자가 이미 Hugging Face 계정을 보유하고 있어야 합니다
- IdP가 사용자를 프로비저닝하면 Hugging Face는 조직에 가입하도록 초대 이메일을 해당 사용자에게 전송합니다
- 사용자는 초대를 수락해야 멤버가 될 수 있으며, 프로비저닝만으로는 즉시 액세스 권한이 부여되지 않습니다
- SCIM 사용자 프로필 정보(이름, 이메일, 사용자 이름)를 수정할 수 없습니다 — 사용자는 자신의 Hugging Face 계정에 대한 완전한 제어권을 유지합니다
- 사용자가 IdP에서 비활성화(deprovision)되면 해당 사용자의 초대장이 비활성화되고 조직에 대한 액세스 권한이 취소됩니다
관리형 SSO: 전체 수명 주기 프로비저닝
Managed SSO(Enterprise Plus 플랜)를 사용하면 SCIM이 Hugging Face의 전체 사용자 수명 주기를 관리합니다.
- SCIM은 사용자가 프로비저닝될 때 새로운 Hugging Face 계정을 생성합니다 — 기존 계정이 필요하지 않습니다
- 사용자는 초대 단계 없이 조직에 멤버로 즉시 추가됩니다
- SCIM 는 IdP에서 변경 사항이 발생하면 사용자 프로필 정보(이름, 이메일, 사용자 이름)를 업데이트할 수 있습니다
- 사용자가 IdP에서 비활성화(deprovision)되면 Hugging Face 계정이 비활성화되고 액세스 권한이 취소됩니다
SCIM 활성화 방법
SCIM을 활성화하려면 조직 설정으로 이동하여 SSO 탭으로 이동한 다음 SCIM 하위 탭을 선택합니다.
SCIM Tenant URL과 SCIM token을 생성하는 버튼을 찾을 수 있습니다. IdP를 구성하려면 이 두 가지가 모두 필요합니다. SCIM token은 비밀 정보이므로 IdP 구성에 안전하게 저장해야 합니다.
IdP에서 SCIM이 활성화되면 프로비저닝된 사용자는 조직 설정의 Users Management 탭에, 프로비저닝된 그룹은 SCIM 탭에 표시됩니다.
그룹 프로비저닝
사용자 프로비저닝 외에도 SCIM은 그룹 프로비저닝을 지원합니다. IdP에서 푸시된 그룹은 Hugging Face에 SCIM 그룹으로 저장되며, 조직 설정의 SCIM 탭에서 Resource Groups와 연결할 수 있습니다.
SCIM 그룹을 Resource Group에 연결
SCIM 그룹을 연결하려면 조직의 SSO → SCIM 탭으로 이동하세요. 프로비저닝된 그룹은 테이블에 나열됩니다. Resource Groups 열에서 각 그룹에는 아직 링크가 없는 경우 Link resource groups 버튼이, 그렇지 않은 경우 현재 연결된 리소스 그룹의 수(예: “2 resource groups”)가 표시됩니다. 이 중 하나를 클릭하면 모달이 열리며, 여기서 각 그룹에 고유한 역할 할당을 지정하여 하나 이상의 Resource Groups를 추가할 수 있습니다. 동일한 모달에서 기존 링크를 변경하거나 제거할 수도 있습니다.
링크를 설정하기 전에 다음 조건이 충족되는지 확인하세요:
- Resource Group에는 기존 멤버가 없어야 합니다. 비어 있지 않은 Resource Group에 링크하는 것은 허용되지 않습니다.
- Resource Group에는 자동 가입이 비활성화되어 있어야 합니다. 자동 가입(모든 새로운 조직 구성원을 RG에 자동으로 추가하는 기능)은 SCIM 관리와 상호 배타적입니다. 연결하기 전에 RG에서 자동 가입을 비활성화하세요.
SCIM 그룹은 각자 고유한 역할을 가진 여러 Resource Group에 연결될 수 있습니다.
링크 후 발생하는 일
SCIM 그룹이 Resource Group에 연결되면:
- Backfill: SCIM 그룹에 이미 포함된 멤버는 설정된 역할로 즉시 Resource Group에 추가됩니다.
- Ongoing sync: IdP의 멤버십 변경 사항은 자동으로 반영됩니다:
- 사용자가 IdP의 그룹에 추가되면, 모든 연결된 Resource Group에도 추가됩니다.
- 사용자가 IdP의 그룹에서 제거되면, 해당 사용자는 다른 SCIM 그룹을 통해 연결된 Resource Groups를 제외하고 모든 연결된 Resource Groups에서 제거됩니다. 다른 SCIM 그룹을 통해 연결된 Resource Groups의 경우, 사용자의 역할은 다른 SCIM 그룹에서 부여된 “가장 높은” 역할로 업데이트됩니다.
- IdP에서 SCIM 그룹이 삭제되면, 해당 그룹의 모든 멤버가 연결된 Resource Group에서 제거됩니다. 단, 다른 SCIM 그룹을 통해 해당 Resource Group에 속한 사용자는 제외됩니다. 이러한 각 Resource Group에 대해, 사용자의 역할은 다른 SCIM 그룹에서 부여한 “가장 높은” 역할로 업데이트됩니다.
- 역할 변경: 링크의 역할을 업데이트하면 해당 Resource Group의 모든 현재 그룹 멤버의 역할이 즉시 업데이트됩니다.
SCIM 관리 리소스 그룹
SCIM 그룹에 연결된 Resource Group은 SCIM 관리된 것으로 간주됩니다. IdP는 해당 그룹의 일반 사용자에 대한 유일한 신뢰할 수 있는 정보 원천입니다. 따라서:
- 일반 사용자의 경우 Hub UI 또는 API를 통한 수동 멤버십 변경은 차단됩니다. SCIM 관리 대상 Resource Group에서 일반 사용자를 추가하거나 제거하거나 역할을 변경하려는 모든 시도는
403오류를 반환합니다. - Service accounts는 예외입니다. SCIM을 통해 프로비저닝되지 않으므로, SCIM 관리 대상 Resource Group에서 서비스 계정을 수동으로 추가, 제거하거나 역할을 변경할 수 있습니다.
- SCIM 관리 대상 Resource Group에서는 자동 가입을 활성화할 수 없습니다. 자동 가입을 다시 활성화하려면 먼저 SCIM 링크를 제거하십시오.
Resource Group 설정에서 SCIM 관리 대상 Resource Group에는 SCIM synced 배지가 표시되며, 멤버십 양식에는 수동으로 추가하거나 제거할 수 있는 계정은 서비스 계정만 가능하다고 명시되어 있습니다.
Group provisioning은 Basic SSO와 Managed SSO 모두 동일한 방식으로 작동합니다.
지원되는 사용자 속성
Hugging Face SCIM 엔드포인트는 다음 사용자 속성을 지원합니다:
| 속성 | 설명 | 기본 SSO | 관리형 SSO |
|---|---|---|---|
userName | Hugging Face 사용자 이름 | 읽기 전용 | 읽기/쓰기 |
name.givenName | 이름 | 읽기 전용 | 읽기/쓰기 |
name.familyName | 성 | 읽기 전용 | 읽기/쓰기 |
emails[type eq "work"].value | 이메일 주소 | 읽기 전용 | 읽기/쓰기 |
externalId | IdP가 할당하는 식별자 | 읽기/쓰기 | 읽기/쓰기 |
active | 사용자가 활성 멤버인지 여부 | 읽기/쓰기 | 읽기/쓰기 |
Basic SSO에서는 SCIM을 통해 active와 externalId만 수정할 수 있으며, 나머지 모든 속성은 사용자가 Hugging Face 계정에서 관리합니다.
그룹 프로비저닝의 경우 지원되는 속성은 displayName, members, externalId입니다.
Deprovisioning
Deprovisioning 동작은 사용자가 제거되는 방식과 사용하는 SSO 모델에 따라 달라집니다.
active를 false(소프트 디프로비저닝)로 설정
- 사용자는 조직에 대한 액세스 권한을 잃습니다
- Basic SSO의 경우: 초대장이 비활성화됩니다
- Managed SSO의 경우: 사용자는 조직에서 제거되지만 계정과 콘텐츠는 유지됩니다.
active를true(으)로 다시 설정하면 되돌릴 수 있습니다.
SCIM을 통한 사용자 삭제(하드 디프로비저닝):
- Basic SSO의 경우: 사용자는 조직 및 모든 리소스 그룹에서 제거됩니다. Hugging Face 계정과 개인 콘텐츠에는 영향이 없습니다 — 단순히 조직 멤버십만 상실하게 됩니다.
- Managed SSO 사용 시: 사용자의 Hugging Face 계정은 사용자가 생성한 모든 콘텐츠와 함께 영구적으로 삭제됩니다. 이 작업은 되돌릴 수 없습니다.
지원되는 Identity Provider
SCIM 2.0 프로토콜을 구현한 모든 IdP에 대해 SCIM을 지원합니다. 가장 인기 있는 일부 프로바이더에 대한 구체적인 가이드를 제공합니다:
Update on GitHub