SCIM 프로비저닝 설정하기

SCIM을 사용해 IdP(identity provider)와 Docker 사이에 사용자 정보를 자동으로 동기화해요. SCIM은 사용자 프로비저닝·디프로비저닝을 자동화하고, 팀 구성원 자격을 동기화하며, Docker 조직을 IdP와 동기화 상태로 유지해요.

출처: 문서

본문

구독: Business / 대상: Administrators

지원되는 속성 (Supported attributes)

SCIM은 속성(이름, 이메일 등)을 사용해 IdP와 Docker 사이에 사용자 정보를 동기화해요. IdP에서 이 속성을 올바르게 매핑하면 사용자 프로비저닝이 원활하게 동작하고, 단일 로그온 사용 시 중복 사용자 계정 같은 문제를 방지해요.

Docker가 지원하는 SCIM 속성:

속성	설명
`userName`	사용자의 기본 이메일 주소, 고유 식별자로 사용
`name.givenName`	사용자의 이름
`name.familyName`	사용자의 성
`active`	사용자가 활성·비활성인지 여부. 사용자 디프로비저닝을 위해 `"false"`로 설정

지원되는 속성과 SCIM에 대한 자세한 내용은 Docker Hub API SCIM 레퍼런스를 참고해요.

중요: 기본적으로 Docker는 SSO에 Just-in-Time(JIT) 프로비저닝을 사용해요. SCIM이 활성화되면 JIT 값이 여전히 우선하며 SCIM이 설정한 속성 값을 덮어써요. 충돌을 피하려면 JIT 속성 값이 SCIM 값과 일치하는지 확인하세요. 또는 JIT 프로비저닝을 비활성화하고 SCIM에만 의존할 수도 있어요. 자세한 내용은 Just-in-Time을 참고해요.

Docker에서 SCIM 활성화하기

SCIM을 활성화하려면:

Docker Home에 로그인해요.
Identity & auth, 그다음 SSO and SCIM을 선택해요.
SSO connections 표에서 연결의 Actions 아이콘을 선택한 뒤 Setup SCIM을 선택해요.
SCIM Base URL과 API Token을 복사해 IdP에 값을 붙여넣어요.

IdP에서 SCIM 활성화하기

IdP의 사용자 인터페이스는 다음 단계와 약간 다를 수 있어요. 확인하려면 IdP 문서를 참고할 수 있어요. 자세한 내용은 IdP 문서를 참고해요.

참고: Microsoft는 현재 Entra ID의 같은 비갤러리 애플리케이션에서 SCIM과 OIDC를 지원하지 않아요. 이 페이지는 SCIM 프로비저닝용 별도 비갤러리 앱을 사용하는 검증된 해결 방법을 제공해요. Microsoft가 공식적으로 문서화하지는 않지만, 널리 사용되며 실무에서 지원돼요.

Okta

1단계: SCIM 활성화하기

Okta에 로그인하고 Admin을 선택해 관리 포털을 열어요.
SSO 연결을 구성할 때 만든 애플리케이션을 열어요.
애플리케이션 페이지에서 General 탭을 선택한 뒤 Edit App Settings를 선택해요.
SCIM 프로비저닝을 활성화하고 Save를 선택해요.
Provisioning으로 이동해 Edit SCIM Connection을 선택해요.

다음 값과 설정으로 연결을 구성해요.

SCIM Base URL: SCIM 커넥터 기본 URL(Docker Home에서 복사)
Unique identifier field for users: email
Supported provisioning actions: Push New Users 및 Push Profile Updates
Authentication Mode: HTTP Header
SCIM Bearer Token: HTTP Header Authorization Bearer 토큰(Docker Home에서 복사)

Test Connector Configuration을 선택해요. 테스트 결과를 검토하고 Save를 선택해요.

2단계: 동기화 활성화하기

Okta에서 Provisioning을 선택해요.
To App, 그다음 Edit을 선택해요.
Create Users, Update User Attributes, Deactivate Users를 활성화해요.
Save를 선택해요.
불필요한 매핑을 제거해요. 필요한 매핑은:
- Username
- Given name
- Family name
- Email
다음으로 역할 매핑(role mapping)을 설정해요.

Entra ID/Azure AD (SAML 2.0)

Microsoft는 같은 비갤러리 애플리케이션에서 SCIM과 OIDC를 지원하지 않아요. SCIM 프로비저닝용으로 Entra ID에 두 번째 비갤러리 애플리케이션을 만들어야 해요.

1단계: 별도 SCIM 앱 만들기

Azure Portal에서 Microsoft Entra ID > Enterprise Applications > New application으로 가요.
Create your own application을 선택해요.
애플리케이션 이름을 지정하고 Integrate any other application you don't find in the gallery를 선택해요.
Create를 선택해요.

2단계: SCIM 프로비저닝 구성하기

새 SCIM 애플리케이션에서 Provisioning > Get started로 가요.
Provisioning Mode를 Automatic으로 설정해요.
Admin Credentials 아래:
- Tenant URL: Docker Home의 SCIM Base URL을 붙여넣어요.
- Secret Token: Docker Home의 SCIM API 토큰을 붙여넣어요.
Test Connection을 선택해 확인해요.
Save를 선택해 자격 증명을 저장해요.
다음으로 역할 매핑을 설정해요.

역할 매핑 설정하기

IdP에 선택적 SCIM 속성을 추가해 사용자에게 Docker 역할을 할당할 수 있어요. 이 속성은 SSO 구성에 설정된 기본 역할·팀 값을 덮어써요.

참고: 역할 매핑은 SCIM과 JIT 프로비저닝 모두에서 지원돼요. JIT의 경우 역할 매핑은 사용자를 처음 프로비저닝할 때만 적용돼요.

지원되는 선택적 사용자 수준 속성:

속성	가능한 값	참고
`dockerRole`	`member`, `editor`, `owner`	설정하지 않으면 사용자는 `member` 역할이 기본값. 이 속성을 설정하면 기본값을 덮어씀. 역할 정의는 Roles and permissions 참고
`dockerOrg`	Docker 조직 이름(예: `moby`)	SSO 연결에 구성된 기본 조직을 덮어씀. 설정하지 않으면 사용자는 기본 조직으로 프로비저닝됨. `dockerOrg`와 `dockerTeam`이 모두 설정되면 지정된 조직 내의 팀으로 프로비저닝됨
`dockerTeam`	Docker 팀 이름(예: `developers`)	기본 또는 지정된 조직의 지정된 팀으로 사용자를 프로비저닝. 팀이 없으면 자동으로 생성. 그룹 매핑을 사용해 조직 전반의 여러 팀에 사용자를 할당할 수도 있음

이 속성에 사용되는 외부 네임스페이스는 urn:ietf:params:scim:schemas:extension:docker:2.0:User예요. IdP에서 Docker용 커스텀 SCIM 속성을 만들 때 이 값이 필요해요.

Okta

1단계: Okta에서 역할 매핑 설정하기

먼저 SSO와 SCIM을 설정해요.

Okta 관리 포털에서 Directory로 가서 Profile Editor, 그다음 **User (Default)**를 선택해요.
Add Attribute를 선택하고 추가하려는 역할·조직·팀에 대한 값을 구성해요. 정확한 이름은 필요 없어요.
Profile Editor로 돌아가 애플리케이션을 선택해요.
Add Attribute를 선택하고 필요한 값을 입력해요. External Name과 External Namespace는 정확해야 해요.
- 조직·팀·역할 매핑의 외부 이름 값은 각각 dockerOrg, dockerTeam, dockerRole이에요(위 표 참고).
- 외부 네임스페이스는 모두 같아요: urn:ietf:params:scim:schemas:extension:docker:2.0:User
속성을 만든 뒤 페이지 맨 위로 가서 Mappings, 그다음 Okta User to YOUR APP을 선택해요.
새로 만든 속성으로 가서 변수 이름을 외부 이름에 매핑하고 Save Mappings를 선택해요.

JIT 프로비저닝을 사용한다면 다음 단계를 계속해요.

Applications로 이동해 YOUR APP을 선택해요.
General, 그다음 SAML Settings, Edit을 선택해요.
Step 2를 선택하고 사용자 속성에서 Docker 변수로의 매핑을 구성해요.

2단계: 사용자별로 역할 할당하기

Okta 관리 포털에서 Directory, 그다음 People을 선택해요. Profile, 그다음 Edit을 선택해요. Attributes를 선택하고 속성을 원하는 값으로 업데이트해요.

3단계: 그룹별로 역할 할당하기

Okta 관리 포털에서 Directory, 그다음 People을 선택해요. YOUR GROUP, 그다음 Applications를 선택해요. YOUR APPLICATION을 열고 Edit 아이콘을 선택해요. 속성을 원하는 값으로 업데이트해요. 사용자가 아직 속성을 갖고 있지 않다면, 그룹에 추가된 사용자는 프로비저닝 시 이런 속성을 상속해요.

Entra ID/Azure AD (SAML 2.0 및 OIDC)

1단계: 속성 매핑 구성하기

SCIM 프로비저닝 설정을 완료해요. Azure Portal에서 Microsoft Entra ID > Enterprise Applications를 열고 SCIM 애플리케이션을 선택해요.

Provisioning > Mappings > Provision Azure Active Directory Users로 가요. 다음 매핑을 추가하거나 업데이트해요.

userPrincipalName → userName
mail → emails.value
선택 사항: 매핑 방법 중 하나로 dockerRole, dockerOrg, dockerTeam 매핑
동기화 오류를 막으려면 지원되지 않는 속성을 제거해요.

선택 사항: Mappings > Provision Azure Active Directory Groups로 가요.

그룹 프로비저닝이 오류를 일으키면 Enabled를 No로 설정해요.
활성화하는 경우 그룹 매핑을 주의 깊게 테스트해요.

Save를 선택해 매핑을 적용해요.

2단계: 역할 매핑 방법 선택하기

dockerRole, dockerOrg, dockerTeam을 다음 방법 중 하나로 매핑할 수 있어요.

표현식 매핑 (Expression mapping): member, editor, owner 같은 Docker 역할만 할당하면 되는 경우 이 방법을 사용해요.

Edit Attribute 보기에서 매핑 유형을 Expression으로 설정해요.
Expression 필드에서:
- App Roles가 Docker 역할과 정확히 일치하면: SingleAppRoleAssignment([appRoleAssignments])
- 일치하지 않으면 switch 표현식 사용: Switch(SingleAppRoleAssignment([appRoleAssignments]), "My Corp Admins", "owner", "My Corp Editors", "editor", "My Corp Users", "member")
설정해요.
- Target attribute: urn:ietf:params:scim:schemas:extension:docker:2.0:User:dockerRole
- Match objects using this attribute: No
- Apply this mapping: Always
변경을 저장해요.

경고: 이 방법으로는 dockerOrg나 dockerTeam을 사용할 수 없어요. 표현식 매핑은 하나의 속성에만 호환돼요.

직접 매핑 (Direct mapping): 여러 속성(dockerRole + dockerTeam)을 매핑해야 할 때 이 방법을 사용해요.

각 Docker 속성에 대해 고유한 Entra 확장 속성(extensionAttribute1, extensionAttribute2 등)을 선택해요.

Edit Attribute 보기에서:
- 매핑 유형을 Direct로 설정해요.
- Source attribute를 선택한 확장 속성으로 설정해요.
- Target attribute를 다음 중 하나로 설정해요.
  - dockerRole: urn:ietf:params:scim:schemas:extension:docker:2.0:User:dockerRole
  - dockerOrg: urn:ietf:params:scim:schemas:extension:docker:2.0:User:dockerOrg
  - dockerTeam: urn:ietf:params:scim:schemas:extension:docker:2.0:User:dockerTeam
Apply this mapping을 Always로 설정해요.
변경을 저장해요.

값을 할당하려면 Microsoft Graph API를 사용해야 해요.

3단계: 사용자와 그룹 할당하기

두 매핑 방법 모두에 대해:

SCIM 앱에서 Users and Groups > Add user/group으로 가요.
Docker에 프로비저닝할 사용자 또는 그룹을 선택해요.
Assign을 선택해요.

표현식 매핑을 사용한다면:

App registrations > SCIM 앱 > App Roles로 가요.
Docker 역할과 일치하는 App Roles를 만들어요.
Users and Groups 아래의 App Roles에 사용자나 그룹을 할당해요.

직접 매핑을 사용한다면:

Microsoft Graph Explorer로 가서 테넌트 관리자로 로그인해요.
Microsoft Graph API로 속성 값을 할당해요.

예시 PATCH 요청:

PATCH https://graph.microsoft.com/v1.0/users/{user-id}
Content-Type: application/json
{
  "extensionAttribute1": "owner",
  "extensionAttribute2": "moby",
  "extensionAttribute3": "developers"
}

참고: 각 SCIM 필드에 대해 서로 다른 확장 속성을 사용해야 해요.

SCIM 프로비저닝 테스트하기

역할 매핑을 완료한 뒤 구성을 수동으로 테스트할 수 있어요.

Okta

Okta 관리 포털에서 Directory > People로 가요.
SCIM 애플리케이션에 할당한 사용자를 선택해요.
Provision User를 선택해요.
몇 초 기다린 뒤 Docker Home의 Members에서 Docker 구성원을 확인해요.
사용자가 나타나지 않으면 Reports > System Log의 로그를 검토하고 앱의 SCIM 설정을 확인해요.

Entra ID/Azure AD (OIDC 및 SAML 2.0)

Azure Portal에서 Microsoft Entra ID > Enterprise Applications로 가서 SCIM 앱을 선택해요.
Provisioning > Provision on demand로 가요.
사용자나 그룹을 선택하고 Provision을 선택해요.
사용자가 Docker Home의 Members에 나타나는지 확인해요.
필요하면 Provisioning logs에서 오류를 확인해요.

SCIM 비활성화하기

SCIM을 비활성화하면 SCIM으로 프로비저닝된 사용자는 조직에 남아 있어요. 사용자에 대한 향후 변경은 IdP에서 동기화되지 않아요. 사용자 디프로비저닝은 조직에서 사용자를 수동으로 제거할 때만 가능해요.

Docker Home에 로그인해요.
Identity & auth, 그다음 SSO and SCIM을 선택해요.
SSO connections 표에서 Actions 아이콘을 선택해요.
Disable SCIM을 선택해요.

다음 단계 (Next steps)

그룹 매핑 설정
Troubleshoot provisioning

SCIM 프로비저닝 설정하기