사용자 프로비저닝

사용자 프로비저닝 (SCIM)

[!WARNING] 이 기능은 Enterprise 및 Enterprise Plus 플랜의 일부예요.

SCIM(System for Cross-domain Identity Management)은 사용자 프로비저닝을 자동화하는 표준이에요. Identity Provider(IdP)를 Hugging Face에 연결해서 조직의 구성원을 관리할 수 있게 해줘요.

SCIM은 SSO 모델에 따라 다르게 동작해요. 자세한 비교는 SSO 개요를 참고해요.

출처: 문서

본문

기본 SSO: 초대 기반 프로비저닝

기본 SSO (Enterprise 플랜)에서 SCIM은 기존 Hugging Face 사용자를 조직에 초대하는 과정을 자동화해요.

  • 사용자는 SCIM으로 프로비저닝되기 전에 Hugging Face 계정이 이미 있어야 해요
  • IdP가 사용자를 프로비저닝하면 Hugging Face가 조직 가입 초대 이메일을 보내요
  • 사용자는 구성원이 되려면 초대를 수락해야 해요 — 프로비저닝이 즉시 접근 권한을 주는 건 아니에요
  • SCIM은 사용자 프로필 정보(이름, 이메일, 사용자명)를 수정할 수 없고 — 사용자가 자기 Hugging Face 계정을 완전히 통제해요
  • IdP에서 사용자를 디프로비저닝하면 초대가 비활성화되고 조직에 대한 접근이 철회돼요

관리형 SSO: 전체 수명주기 프로비저닝

관리형 SSO (Enterprise Plus 플랜)에서 SCIM은 Hugging Face에서 전체 사용자 수명주기를 관리해요.

  • 사용자가 프로비저닝될 때 SCIM이 새 Hugging Face 계정을 생성해요 — 사전 생성 계정이 필요 없어요
  • 사용자는 초대 단계 없이 즉시 조직 구성원으로 추가돼요
  • IdP에서 변경이 발생하면 SCIM이 사용자 프로필 정보(이름, 이메일, 사용자명)를 업데이트할 수 있어요
  • IdP에서 사용자를 디프로비저닝하면 Hugging Face 계정이 비활성화되고 접근이 철회돼요

SCIM 활성화 방법

SCIM을 활성화하려면 조직 설정으로 가서 SSO 탭으로 이동한 다음 SCIM 하위 탭을 선택해요.

SCIM Tenant URL과 SCIM 토큰을 생성하는 버튼을 찾을 수 있어요. IdP를 구성하려면 둘 다 필요해요. SCIM 토큰은 비밀이므로 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 버튼(아직 연결이 없을 때) 또는 현재 연결된 Resource Group 수(예: "2 resource groups")를 보여줘요. 둘 중 하나를 클릭하면 하나 이상의 Resource Group을 추가할 수 있는 모달이 열리고, 각각 자체 역할 할당이 있어요. 같은 모달에서 기존 연결을 변경하거나 제거할 수도 있어요.

연결하기 전에 다음 조건이 충족되는지 확인해요:

  • Resource Group에 기존 구성원이 없어야 해요. 비어 있지 않은 Resource Group에 대한 연결은 허용되지 않아요.
  • Resource Group에 auto-join이 활성화되어 있지 않아야 해요. Auto-join(모든 새 조직 구성원을 RG에 자동 추가)은 SCIM 관리와 상호 배타적이에요. 연결 전에 RG의 auto-join을 비활성화해요.

SCIM 그룹은 각각 자체 역할을 가진 여러 Resource Group에 연결될 수 있어요.

연결 후 무슨 일이 일어나나요

SCIM 그룹이 Resource Group에 연결되면:

  • 백필(Backfill): SCIM 그룹에 이미 있는 구성원이 설정된 역할로 즉시 Resource Group에 추가돼요.
  • 지속 동기화: IdP의 구성원 변경이 자동으로 반영돼요:
    • IdP에서 사용자가 그룹에 추가되면 연결된 모든 Resource Group에 추가돼요.
    • IdP에서 사용자가 그룹에서 제거되면 다른 SCIM 그룹을 통해 연결된 경우를 제외하고 연결된 모든 Resource Group에서 제거돼요. 그런 경우 사용자 역할은 다른 SCIM 그룹이 부여하는 "최상위(highest)" 역할로 업데이트돼요.
    • IdP에서 SCIM 그룹이 삭제되면 다른 SCIM 그룹을 통해 해당 Resource Group에 속한 사용자를 제외하고 모든 구성원이 연결된 Resource Group에서 제거돼요. 각 Resource Group에 대해 사용자 역할은 다른 SCIM 그룹이 부여하는 "최상위" 역할로 업데이트돼요.
  • 역할 변경: 링크의 역할을 업데이트하면 해당 Resource Group의 모든 현재 그룹 구성원 역할이 즉시 업데이트돼요.

SCIM 관리 Resource Group

SCIM 그룹에 연결된 Resource Group은 SCIM-managed로 간주돼요. IdP가 정규 사용자의 유일한 진실 소스(source of truth)예요. 결과적으로:

  • Hub UI나 API를 통한 수동 구성원 변경은 정규 사용자에게 차단돼요 — SCIM-managed Resource Group에서 정규 사용자를 추가·제거·역할 변경하려는 시도는 403 오류를 반환해요.
  • Service accounts는 예외예요: SCIM을 통해 프로비저닝된 적이 없으므로 SCIM-managed Resource Group에서 서비스 계정을 수동으로 추가·제거·역할 변경할 수 있어요.
  • SCIM-managed Resource Group에서는 auto-join을 활성화할 수 없어요. auto-join을 다시 켜려면 먼저 SCIM 연결을 제거해요.

Resource Group 설정에서 SCIM-managed Resource Group은 SCIM synced 배지를 표시하고, 구성원 양식에는 서비스 계정만 수동으로 추가·제거할 수 있다고 안내해요.

그룹 프로비저닝은 기본 SSO와 관리형 SSO 모두에서 동일하게 동작해요.

지원되는 사용자 속성

Hugging Face SCIM 엔드포인트는 다음 사용자 속성을 지원해요:

속성 설명 기본 SSO 관리형 SSO
userName Hugging Face 사용자명 읽기 전용 읽기/쓰기
name.givenName 이름 읽기 전용 읽기/쓰기
name.familyName 성 읽기 전용 읽기/쓰기
emails[type eq "work"].value 이메일 주소 읽기 전용 읽기/쓰기
externalId IdP가 할당한 식별자 읽기/쓰기 읽기/쓰기
active 활성 구성원 여부 읽기/쓰기 읽기/쓰기

기본 SSO에서는 SCIM으로 active와 externalId만 수정할 수 있고, 다른 모든 속성은 사용자가 자기 Hugging Face 계정에서 통제해요.

그룹 프로비저닝에서 지원되는 속성은 displayName, members, externalId예요.

디프로비저닝

디프로비저닝 동작은 사용자를 제거하는 방식과 사용하는 SSO 모델에 따라 달라져요.

active를 false로 설정 (소프트 디프로비저닝):

  • 사용자는 조직에 대한 접근을 잃어요
  • 기본 SSO: 초대가 비활성화돼요
  • 관리형 SSO: 사용자는 조직에서 제거되지만 계정과 콘텐츠는 보존돼요 — active를 다시 true로 설정하면 되돌릴 수 있어요

SCIM으로 사용자 삭제 (하드 디프로비저닝):

  • 기본 SSO: 사용자는 조직과 모든 resource group에서 제거돼요. Hugging Face 계정과 개인 콘텐츠는 영향을 받지 않고 — 단순히 조직 구성원 자격을 잃어요.
  • 관리형 SSO: 사용자의 Hugging Face 계정은 생성한 모든 콘텐츠와 함께 영구 삭제돼요. 이 작업은 되돌릴 수 없어요.

지원되는 Identity Provider

SCIM 2.0 프로토콜을 구현하는 모든 IdP와 SCIM을 지원해요. 가장 인기 있는 몇 가지 제공자에 대한 구체적인 가이드가 있어요:

더 알아보기 (Learn more)

  • SCIM으로 IdP와 연동해 사용자·그룹 프로비저닝을 자동화할 수 있어요.
  • 기본 SSO(초대 기반)와 관리형 SSO(전체 수명주기)의 차이를 이해해 두면 좋아요.
  • SSO 개요와 Resource Groups 문서를 함께 참고해 보세요.