Hugging Face's logo

Hub documentation

Managed SSO로 마이그레이션

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Managed SSO로 마이그레이션

이 기능은 Enterprise Plus 플랜의 일부입니다.

이 가이드는 기존 조직을 표준 조직에서 Managed SSO 조직으로 전환하는 조직 관리자를 위한 것입니다.

시작하기 전에 가장 중요하게 이해해야 할 점: 멤버의 기존 개인 Hugging Face 계정은 관리 계정으로 전환되지 않습니다. 각 멤버는 Identity Provider(IdP)에 의해 프로비저닝되는 완전히 새로운 관리 계정을 받게 됩니다. 멤버가 프로비저닝되기 전에, 해당 멤버는 개인 계정에서 업무용 이메일 주소를 해제해야 합니다.

이 가이드에서는 my-org을 예시 조직 이름으로 사용합니다.

필수 조건

SSO는 이미 조직에서 설정, 테스트 및 활성화되어 있어야 합니다. 마이그레이션은 기존 OIDC 또는 SAML 애플리케이션을 재사용합니다.

마이그레이션 단계

  1. 멤버들을 준비하세요. 멤버들과 함께 마이그레이션 전 체크리스트를 확인하세요.
  2. Hugging Face에 문의하세요. Hugging Face 팀과 연락하여 전환을 확인합니다. 조직을 변환하고 my-org:owner break-glass 계정의 자격 증명을 보내 드립니다.
  3. 멤버들이 업무용 이메일을 비워 두도록 합니다. 업무용 이메일 주소 해제를 참고하세요. 프로비저닝을 활성화하기 전에 이 작업을 수행해야 합니다. SCIM이 켜지는 즉시 SSO 애플리케이션에 이미 할당된 사용자가 프로비저닝됩니다. Hugging Face 팀은 개인 계정에 여전히 업무용 이메일 주소가 남아 있는 멤버 목록을 보내드릴 수 있으므로, 해당 멤버들에게 후속 조치를 취할 수 있습니다.
  4. Set up SCIM in your IdP. 조직의 SSO → SCIM 설정에서 SCIM Tenant URL과 토큰을 가져와서 기존 OIDC 또는 SAML 애플리케이션에 적용한 후, 해당 IdP에 대한 가이드를 따르세요.
  5. IdP에서 사용자 및 그룹을 지정합니다. 사용자가 프로비저닝될 때 관리 계정이 생성됩니다.
  6. 각 멤버의 관리 계정이 프로비저닝되는 대로 조직에서 남은 개인 계정을 제거하십시오. 개인 계정은 제거될 때까지 액세스를 유지하므로 보안상 이 단계가 필요합니다. 개인 계정을 제거하면 조직의 Resource Groups에서도 함께 제거됩니다.
  7. (선택) 그룹을 Resource Groups 및 역할에 매핑합니다. SCIM 그룹을 Resource Groups에 연결하고, IdP에서 조직 역할을 할당하기 위해 Role Mapping을 설정합니다. Resource Group은 멤버가 없고 auto-join이 꺼져 있는 경우에만 SCIM 그룹에 연결할 수 있습니다. auto-join이 켜져 있으면 새로 프로비저닝된 관리 계정도 해당 그룹에 추가되므로, 사용자를 프로비저닝하기 전에 auto-join을 끄거나 연결하기 전에 남은 멤버를 제거해야 합니다.

변경 사항

변환이 수행하는 작업

  • 변환은 Hugging Face 팀이 수행합니다. 셀프 서비스 전환 옵션은 없습니다. 요청을 하면 Hugging Face 팀이 해당 조직을 관리 모드로 전환합니다.
  • 조직의 콘텐츠와 설정은 그대로 유지됩니다. 저장소, 설정, Resource Groups 및 기존 SSO 설정(OIDC 또는 SAML 앱)이 유지됩니다. 동일한 IdP 애플리케이션을 계속 사용하지만, SCIM을 위해 일부 설정을 조정해야 할 수 있습니다(4단계 참조).
  • break-glass 관리자 계정이 생성됩니다. 이름은 my-org:owner입니다. 이 계정은 사용자 이름과 비밀번호(SSO가 아닌)로 로그인하며 조직의 관리자입니다. Hugging Face 팀이 해당 자격 증명을 공유합니다. 안전하게 보관하세요: 이 계정은 IdP가 사용 불가능하거나 잘못 구성된 경우에도 조직에 액세스할 수 있게 해 줍니다.
  • SSO를 선택적으로 설정할 수 없게 되었습니다. 완전히 비활성화하는 것은 여전히 가능합니다.

관리 대상 조직에서 SSO를 비활성화하면 관리 대상 계정은 비밀번호가 없으므로 모든 관리 대상 사용자가 잠금 상태가 됩니다.

관리되는 계정은 새로운 계정입니다

  • 기존의 개인 Hugging Face 계정은 관리형 계정으로 전환, 병합 또는 연결되지 않습니다. 각 멤버는 IdP에서 사용자를 할당할 때 IdP가 SCIM을 통해 생성하는 새로운 계정을 받게 됩니다.
  • 관리되는 사용자 이름은 조직 이름으로 시작합니다: <org-name>:<username>, 예를 들어 my-org:jdoe.
  • Managed users는 IdP를 통해서만 로그인합니다. Hugging Face 비밀번호가 없으며, “비밀번호 찾기” 기능은 이들에게 적용되지 않습니다.
  • 관리 계정에는 관리 계정 제한 사항이 적용됩니다.

멤버십

  • 일반 멤버는 더 이상 초대 방식으로 추가할 수 없습니다. 내부 멤버는 SCIM을 통해 프로비저닝해야 합니다.
  • 초대는 외부 협력자에게만 제공됩니다.

조직의 기존 개인 계정

변환 후에도 조직의 멤버로 남아 있는 개인 계정은 기존 역할을 유지합니다. SSO와 대조되지 않기 때문에 액세스 토큰, 이미 승인한 OAuth 앱, git over SSH는 계속 작동합니다. 하지만 더 이상 조직에 대한 새로운 SSO 로그인을 시작할 수 없습니다:

  • 사용자가 개인 계정으로 로그인했거나 해당 계정이 이미 사용자의 IdP에 연결된 경우, 다음 메시지가 표시됩니다: You cannot login with SSO with this account because it's not managed by this organization. Contact your organization administrators.
  • 그렇지 않으면 User not found를 확인합니다.

마이그레이션하기 전에

변환을 요청하기 전에 팀원들과 함께 이 체크리스트를 확인하세요:

  • 개인 저장소: 새 관리 계정에서 계속 액세스하려는 개인 네임스페이스의 저장소가 있는 멤버는 전환 전에 해당 저장소를 조직으로 이전해야 합니다. 관리 계정은 개인 네임스페이스의 콘텐츠를 소유할 수 없습니다. 멤버는 여전히 개인(비관리) 계정을 통해 개인 네임스페이스의 모든 저장소에 액세스할 수 있습니다.
  • 토큰 및 자동화: 개인 계정에서 생성된 토큰은 해당 계정이 조직에서 제거될 때까지 조직에 대한 접근 권한을 유지합니다. 스크립트, CI 작업 및 파이프라인을 서비스 계정으로, 또는 전환 후 관리 계정에서 생성된 토큰으로 마이그레이션한 다음 기존 계정을 제거하세요.
  • 다른 조직: 관리된 계정은 다른 조직에 가입할 수 없습니다. 다른 조직에서 계속 작업해야 하는 멤버는 별도의 개인 계정을 유지해야 합니다(아래 옵션 2 참조).
  • 업무용 이메일 주소: 모든 멤버는 프로비저닝되기 전에 자신의 업무용 이메일 주소를 해제해야 합니다. 업무용 이메일 주소 해제를 참조하세요.

업무용 이메일 주소 해제

이메일 주소는 하나의 Hugging Face 계정에만 속할 수 있습니다. 이는 계정의 모든 이메일 주소, 즉 기본 이메일과 보조 이메일 모두에 적용됩니다. 대소문자는 구분하지 않습니다.

SCIM이 이미 개인 계정에서 사용 중인 업무 이메일로 관리 계정을 생성하려고 하면 프로비저닝이 409 오류로 실패합니다:

The email address (jdoe@example.com) is already associated with another Hugging Face account. Please delete the account.

IdP는 해당 사용자의 프로비저닝 오류로 표시합니다.

이를 방지하려면, 각 구성원은 프로비저닝되기 전에 아래 두 옵션 중 하나를 사용하여 업무용 이메일 주소를 해제해야 합니다.

어떤 옵션을 선택해야 하나요?

  • Hugging Face 계정을 이 조직의 업무에만 사용한다면 옵션 1을 선택하세요: 개인 계정을 삭제합니다.
  • 오픈소스 작업, 개인 프로젝트 또는 다른 조직에서도 함께 사용한다면 옵션 2를 선택하세요: 개인 계정을 유지하고 해당 계정에서 업무 이메일을 제거합니다.

옵션 1: 개인 계정 삭제

계정 설정에서 개인 계정을 삭제하세요. 이 작업은 개인 네임스페이스의 모든 저장소를 영구적으로 삭제하고 모든 조직에서 귀하를 제거합니다.

계정을 삭제하면 영구적으로 삭제됩니다. 유지하려는 저장소는 먼저 조직으로 이전하세요.

다른 조직의 유일한 관리자라면 삭제가 차단됩니다. 먼저 해당 조직에 다른 관리자를 추가하거나 조직을 삭제하세요. 마이그레이션 대상 조직은 문제가 되지 않으며, my-org:owner도 관리자이기 때문입니다.

옵션 2: 개인 계정 유지

  1. 계정 설정에서 개인 이메일 주소를 추가하고 인증하세요.
  2. 개인 이메일 주소를 기본 이메일로 설정하세요.
  3. 업무용 이메일 주소를 완전히 제거하세요. 보조 이메일로 설정하는 것만으로는 충분하지 않습니다.

관리 계정 프로비저닝이 완료될 때까지 개인 계정을 조직에 유지하세요. 이후 관리자가 해당 계정을 제거합니다.

조직에 이미 Managed SSO가 활성화되어 있고 인증된 이메일 도메인이 있는 경우, 해당 도메인의 이메일 주소로 로그인하면 조직의 SSO 페이지로 리디렉션됩니다. 개인 계정에 로그인하려면 사용자 이름을 사용하세요.

업무 이메일이 사용 가능해지면, 관리자는 IdP에서 해당 사용자의 프로비저닝을 다시 시도하거나 다음 동기화에서 처리되도록 기다릴 수 있습니다.

마이그레이션 후

사용자 생명 주기는 IdP에서 관리됩니다:

  • IdP에서 사용자를 비활성화하면 해당 사용자가 조직에서 제거됩니다. 나중에 동일한 사용자가 다시 활성화되면 기존 관리 계정이 재사용됩니다.
  • SCIM을 통해 삭제하면 해당 사용자의 관리 계정이 영구적으로 삭제됩니다. Deprovisioning을 참조하세요.
Update on GitHub

←관리형 SSO 사용자 관리→