Okta로 SCIM 구성하는 방법

Okta로 SCIM 구성하는 방법 (How to configure SCIM with Okta)

이 가이드는 Okta와 Hugging Face 조직 사이에서 SCIM을 사용한 사용자·그룹 프로비저닝을 설정하는 방법을 설명해요. Enterprise 및 Enterprise Plus 요금제에서 사용할 수 있습니다.

출처: 문서

본문

이 가이드는 SCIM을 사용해 Okta와 Hugging Face 조직 사이에 사용자·그룹 프로비저닝을 설정하는 방법을 설명합니다.

[!WARNING] 이 기능은 Enterprise 및 Enterprise Plus 요금제의 일부입니다.

0단계: 조직이 제대로 설정되었는지 확인 (Confirm your organization is properly set up)

[!NOTE] 이 단계는 Hugging Face에서 managed 사용자를 설정하는 경우에만 필요합니다.

진행하기 전에 조직이 Hugging Face managed organization으로 전환되었는지 확인하세요. managed 사용자를 위한 SCIM 프로비저닝은 managed organization에서만 사용할 수 있습니다 — 아직 전환되지 않았다면 아래 단계를 계속하기 전에 Hugging Face 계정 팀에 연락하세요.

1단계: Hugging Face에서 SCIM 구성 가져오기 (Get SCIM configuration from Hugging Face)

조직의 소유자인 Hugging Face 계정으로 로그인합니다(managed 사용자의 경우 managed 사용자 전환 후 제공된 소유자 계정 사용).
Hugging Face에서 조직의 settings 페이지로 이동합니다.
SSO 탭으로 간 뒤 SCIM 하위 탭을 클릭합니다.
SCIM Tenant URL을 복사합니다. Okta 구성에 필요합니다.
Generate an access token을 클릭합니다. 새 SCIM 토큰이 생성됩니다. 이 토큰을 즉시 복사해 안전하게 보관하세요 — 다시 볼 수 없기 때문입니다.

2단계: 관리자 자격 증명 입력 (Enter Admin Credentials)

Okta에서 Applications로 가서 Hugging Face 앱을 선택합니다.
General 탭으로 가서 App Settings에서 Edit을 클릭합니다.
Provisioning 옵션에서 SCIM을 선택하고 Save를 클릭합니다.
Provisioning 탭으로 가서 Settings 아래의 Integration을 클릭합니다.
SCIM Tenant URL을 SCIM 커넥터 base URL로 입력합니다.
Unique identifier field for users에 userName을 입력합니다.
Supported provisioning actions에 필요한 모든 작업을 선택합니다.
Authentication Mode에서 HTTP Header를 선택합니다.
생성한 Access Token을 Authorization Bearer Token으로 입력합니다.
Test Connector Configuration을 클릭해 연결을 검증합니다.
변경 사항을 저장합니다.

3단계: SAML 재구성 (Reconfigure SAML)

SAML SSO로 구성된 managed organization에서 SCIM 프로비저닝을 위해, 기존 SAML 애플리케이션의 식별자가 SCIM과 일치하도록 업데이트하세요:

General 탭으로 가서 SAML Settings에서 Edit을 클릭합니다.
Next를 클릭해 2단계 Configure SAML로 이동하고 다음을 설정합니다:
- Name ID format을 EmailAddress로
- Application username을 Custom으로, 표현식은 user.getInternalProperty("id")로
Next를 클릭한 뒤 Finish를 클릭합니다.

4단계: 프로비저닝 구성 (Configure Provisioning)

Provisioning 탭에서 사이드 내비의 To App을 클릭합니다.
Edit을 클릭하고 필요한 기능(즉 Create, Update, Delete Users)을 모두 활성화합니다.
아래쪽의 Save를 클릭합니다.

5단계: 속성 매핑 구성 (Configure Attribute Mappings)

Provisioning 탭에 있는 동안 Attribute Mappings 섹션까지 스크롤합니다.
기본 속성 매핑은 견고한 프로비저닝을 위해 조정이 자주 필요합니다. 다음 구성을 권장합니다. 여기 없는 속성은 삭제해도 됩니다.

6단계: 사용자 또는 그룹 할당 (Assign Users or Groups)

Assignments 탭을 방문해 Assign을 클릭합니다.
Assign to People 또는 Assign to Groups을 클릭합니다.
할당해야 할 User 또는 Group을 찾은 뒤 이름 옆의 Assign을 클릭합니다.
매핑 모달에서 Username을 다음 규칙을 준수하도록 편집해야 합니다.

[!WARNING]

Username에는 일반 문자와 -만 허용됩니다. --(이중 대시)는 금지입니다. -는 이름을 시작하거나 끝낼 수 없습니다. 숫자만으로 된 이름은 허용되지 않습니다. 최소 길이는 2, 최대 길이는 42입니다. Username은 조직 내에서 고유해야 합니다.

스크롤해 Save and Go Back을 클릭합니다.
Done을 클릭합니다.
Hugging Face 조직에서 사용자나 그룹이 예상대로 생성되거나, 업데이트되거나, 비활성화되었는지 확인합니다.

7단계: Okta 그룹을 SCIM으로 Hugging Face에 푸시 (Push Okta Groups to Hugging Face via SCIM)

그룹을 Hugging Face Resource Groups에 연결하기 전에 Push Groups 탭을 사용해 Okta 그룹을 Hugging Face로 푸시해야 해요. 이는 6단계에서 사용자를 앱에 할당하는 것과 별개입니다.

[!WARNING] Okta는 앱 할당(6단계)과 Group Push에 같은 그룹을 사용하는 것을 지원하지 않습니다. 푸시에는 전용 그룹을 사용하세요 — 푸시 그룹을 할당 그룹과 분리해 두세요.

Okta Admin Console에서 Applications로 가서 Hugging Face 앱을 선택합니다.
Push Groups 탭을 클릭합니다.
+ Push Groups을 클릭하고 Find groups by name을 선택합니다.
푸시하려는 Okta 그룹을 검색하고 결과에서 선택합니다.
Hugging Face에서 그룹을 처리할 방법을 선택합니다:
- Create Group: Hugging Face 조직에 새 SCIM 그룹을 생성.
- Link Group: 이미 Hugging Face 조직에 있는 기존 그룹에 연결.
Save를 클릭합니다. 추가 그룹을 푸시하려면 Save & Add Another를 클릭하고 반복합니다.

푸시되면 그룹이 Hugging Face 조직 설정의 SCIM Groups 아래(SSO → SCIM 탭)에 나타납니다. Okta에서 그룹에 하는 멤버십 변경은 Hugging Face에 자동으로 동기화됩니다.

8단계: SCIM 그룹을 Hugging Face Resource Groups에 연결 (Link SCIM Groups to Hugging Face Resource Groups)

그룹이 Okta에서 프로비저닝되면 그룹을 Hugging Face Resource Groups에 연결해 규모에 맞게 권한을 관리할 수 있어요. 이렇게 하면 SCIM 그룹의 모든 멤버가 리소스 모음에 대해 특정 역할(예: read 또는 write)을 자동으로 받습니다.

[!NOTE] 연결하기 전에 연결하려는 Resource Group이 비어 있고(기존 멤버 없음) auto-join이 활성화되지 않았는지 확인하세요. 두 조건 모두 필요하며, 그렇지 않으면 연결이 실패합니다.

Hugging Face 조직 설정에서 SSO -> SCIM 탭으로 이동합니다. SCIM Groups 아래에 프로비저닝된 그룹 목록이 보일 거예요.
구성하려는 그룹을 찾아 그 행에서 Link resource groups을 클릭합니다.
대화 상자가 나타납니다. Link a Resource Group을 클릭합니다.
드롭다운 메뉴에서 연결할 Resource Group과 SCIM 그룹 멤버에게 부여할 Role Assignment를 선택합니다.
Link to SCIM group을 클릭하고 매핑을 저장합니다.

연결되면 Resource Group은 SCIM-managed가 됩니다: SCIM 그룹에 이미 있는 멤버는 즉시 Resource Group에 추가되고(backfill), Okta의 모든 향후 멤버십 변경이 자동으로 반영됩니다. Hub UI나 API를 통한 Resource Group의 수동 멤버십 편집은 차단됩니다.

더 알아보기 (Learn more)

Okta SCIM 프로비저닝은 Hugging Face의 SSO → SCIM 탭에서 SCIM Tenant URL과 토큰을 얻어 Okta 앱에 SCIM 커넥터로 연결하는 방식으로 설정해요. SAML Name ID를 EmailAddress로 맞추고, Push Groups로 Okta 그룹을 푸시한 뒤 이를 빈 Resource Group에 연결하면 멤버 역할이 자동 동기화됩니다. Username 규칙(일반 문자·하이픈만, 2~42자)에 주의하세요.