GitLab.com 그룹을 위한 SCIM 구성
오픈 표준인 Cross-domain Identity Management (SCIM)을 사용하여 다음을 자동으로 수행할 수 있습니다:
- 사용자 생성
- 사용자 삭제 (SCIM 식별 정보 비활성화)
- 사용자 재추가 (SCIM 식별 정보 다시 활성화)
GitLab SAML SSO SCIM은 사용자 업데이트를 지원하지 않습니다.
GitLab 그룹에 SCIM을 활성화하면 해당 그룹의 구성원이 GitLab과 식별 공급자 간에 동기화됩니다.
내부 GitLab 그룹 SCIM API는 RFC7644 프로토콜의 일부를 구현합니다. 식별 공급자는 내부 GitLab 그룹 SCIM API를 사용하여 SCIM 앱을 개발할 수 있습니다.
GitLab Self-managed에서 SCIM을 설정하려면 Self-managed GitLab 인스턴스를 위한 SCIM 구성을 참조하세요.
GitLab 구성
전제 조건:
- 그룹 단일 로그인을 구성해야 합니다.
GitLab SAML SSO SCIM을 구성하려면 다음을 수행하세요:
- 왼쪽 사이드바에서 검색 또는 이동을 선택하고 그룹을 찾습니다.
- 설정 > SAML SSO를 선택합니다.
- SCIM 토큰 생성을 선택합니다.
- 식별 공급자의 구성을 위해 다음을 저장합니다:
- Your SCIM token 필드의 토큰
- SCIM API endpoint URL 필드의 URL
식별 공급자 구성
다음 중 하나를 식별 공급자로 구성할 수 있습니다:
Microsoft Entra ID (이전 Azure Active Directory) 구성
- 16.10에서 Microsoft Entra ID 용어로 업데이트됨.
전제 조건:
Azure Active Directory용으로 설치된 SAML 애플리케이션은 SCIM으로 설정되어야 합니다. 예제 구성에 대해서는 예제 구성을 참조하세요.
Microsoft Entra ID를 SCIM으로 구성하려면 다음을 수행하세요:
- 앱에서 Provisioning 탭으로 이동하고 Get started를 선택합니다.
- Provisioning Mode를 Automatic으로 설정합니다.
-
Admin Credentials를 다음 값을 사용하여 완료합니다:
- Tenant URL 필드에 GitLab의 SCIM API endpoint URL 값을 사용합니다.
- Secret Token 필드에 GitLab의 Your SCIM token 값을 사용합니다.
- Test Connection을 선택합니다. 테스트가 성공하면 계속하기 전에 구성을 저장하거나 문제 해결 정보를 참조하세요.
- Save를 선택합니다.
저장한 후에는 Mappings 및 Settings 섹션이 나타납니다.
Mappings 구성
Mappings 섹션에서 먼저 그룹을 프로비저닝합니다:
- Provision Microsoft Entra ID Groups를 선택합니다.
-
속성 매핑 페이지에서 Enabled 토글을 끕니다. SCIM 그룹 프로비저닝은 GitLab에서 지원되지 않습니다. 그룹 프로비저닝을 활성화해 두어도 SCIM 사용자 프로비저닝에는 영향을 주지 않지만 Entra ID SCIM 프로비저닝 로그에 오류가 발생할 수 있어 혼동을 줄 수 있습니다.
Provision Microsoft Entra ID Groups가 비활성화되어 있더라도 매핑 섹션이 “Enabled: Yes”로 표시될 수 있습니다. 이 동작은 무시해도 안전한 디스플레이 버그입니다. - Save를 선택합니다.
다음으로 사용자를 프로비저닝합니다:
- Provision Microsoft Entra ID Users를 선택합니다.
- Enabled 토글이 Yes로 설정되어 있는지 확인합니다.
- 모든 Target Object Actions이 활성화되어 있는지 확인합니다.
-
Attribute Mappings 아래에서 구성된 속성 매핑과 일치하도록 매핑을 구성합니다:
-
customappsso Attribute 열에서
externalId
를 찾아 삭제합니다 (선택 사항). - 첫 번째 속성을 편집하여:
-
source attribute:
objectId
-
target attribute:
externalId
-
matching precedence:
1
-
source attribute:
- 기존의 customappsso 속성을 구성된 속성 매핑과 일치하도록 업데이트합니다.
- 다음 표에 없는 추가 속성을 삭제합니다 (선택 사항). 삭제해도 문제가 발생하지는 않지만 GitLab은 해당 속성을 사용하지 않습니다.
-
customappsso Attribute 열에서
- 매핑 디렉터리 아래에서 Show advanced options 확인란을 선택합니다.
- Edit attribute list for customappsso 링크를 선택합니다.
-
id
가 주요 및 필수 필드이며externalId
도 필수 필드인지 확인합니다. - Save를 선택하여 속성 매핑 구성 페이지로 돌아갑니다.
- 우측 상단의
X
를 클릭하여 Attribute Mapping 구성 페이지를 닫습니다.
Settings 구성
Settings 섹션에서:
- 원하는 경우 Send an email notification when a failure occurs 확인란을 선택합니다 (선택 사항).
- 원하는 경우 Prevent accidental deletion 확인란을 선택합니다 (선택 사항).
- 모든 변경 사항이 저장되었는지 확인하려면 필요한 경우 Save를 선택합니다.
매핑 및 설정을 구성한 후에는 앱 개요 페이지로 돌아가서 GitLab의 사용자를 자동으로 SCIM 프로비저닝을 시작하려면 Start provisioning을 선택합니다.
id
와 externalId
에 매핑된 필드를 변경하면 오류가 발생할 수 있습니다. 프로비저닝 오류, 중복 사용자 등이 발생하며 기존 사용자가 GitLab 그룹에 액세스하지 못할 수 있습니다.속성 매핑 구성
SCIM을 위한 Entra ID 구성 중에 속성 매핑을 구성합니다. 예시는 예시 구성을 참조하세요.
다음 표는 GitLab에서 필요로 하는 속성 매핑을 제공합니다.
|
| 원본 속성 | 대상 속성 | 일치 우선순위 |
|:——————|:————————–|:————|
| objectId
| externalId
| 1 |
| userPrincipalName
또는 mail
1 | emails[type eq "work"].value
| |
| mailNickname
| userName
| |
| displayName
또는 Join(" ", [givenName], [surname])
2 | name.formatted
| |
| Switch([IsSoftDeleted], , "False", "True", "True", "False")
3 | active
| |
- `userPrincipalName`이 이메일 주소가 아니거나 전달할 수 없을 때 소스 속성으로 `mail`을 사용합니다.
- `displayName`이 `Firstname Lastname`의 형식과 일치하지 않는 경우 `Join` 표현식을 사용합니다.
- 이것은 직접 매핑이 아닌 표현 매핑 유형입니다. 드롭다운 디렉터리의 `Mapping type`에서 Expression을 선택하세요.
각 속성 매핑에는 다음이 포함되어 있습니다.
- customappsso 속성: 대상 속성에 해당합니다.
- 마이크로소프트 Entra ID 속성: 원본 속성에 해당합니다.
- 일치 우선순위.
각 속성에 대해:
- 기존 속성을 편집하거나 새 속성을 추가합니다.
- 드롭다운 디렉터리에서 필요한 소스 및 대상 속성 매핑을 선택합니다.
- 확인을 선택합니다.
- 저장을 선택합니다.
SAML 구성이 권장 SAML 설정과 다른 경우, 매핑 속성을 선택하고 그에 맞게 수정합니다. externalId
대상 속성에 매핑하는 소스 속성은 SAML NameID
에 사용된 속성과 일치해야 합니다.
표에 없는 매핑이 있는 경우, 마이크로소프트 Entra ID의 기본값을 사용하세요. 필요한 속성 디렉터리은 내부 그룹 SCIM API 문서를 참조하세요.
Okta 구성
Okta의 단일 사인온 설정 중에 만들어진 SAML 애플리케이션은 SCIM에 설정되어 있어야 합니다.
전제 조건:
- Okta Lifecycle Management 제품을 사용해야 합니다. 이 제품 티어는 Okta에서 SCIM을 사용하려면 필요합니다.
- GitLab 구성되어 있어야 합니다.
- Okta용 SAML 애플리케이션이 Okta 설정 노트에 설명된대로 설정돼 있어야 합니다.
- Okta SAML 설정이 구성 단계와 정확하게 일치해야 합니다.
Okta를 SCIM에 설정하는 방법:
- Okta에 로그인합니다.
- 오른쪽 상단에서 관리자를 선택합니다. 이 버튼은 관리자 영역에서는 표시되지 않습니다.
- 애플리케이션 탭에서 앱 카탈로그 찾아보기를 선택합니다.
- GitLab을 검색하여 GitLab 애플리케이션을 찾고 선택합니다.
- GitLab 애플리케이션 개요 페이지에서 추가를 선택합니다.
- 애플리케이션 가시성 아래에서 두 확인란을 선택합니다. 현재 GitLab 애플리케이션은 SAML 인증을 지원하지 않으므로 아이콘이 사용자에게 표시되지 않아야 합니다.
- 애플리케이션 추가를 완료하려면 완료를 선택합니다.
- 프로비저닝 탭에서 API 통합 구성을 선택합니다.
-
API 통합 사용 설정을 선택합니다.
- 기본 URL에는 GitLab SCIM 구성 페이지의 SCIM API 엔드포인트 URL에서 복사한 URL을 붙여넣습니다.
- API 토큰에는 GitLab SCIM 구성 페이지의 Scim 토큰에서 복사한 SCIM 토큰을 붙여넣습니다.
- 구성을 검증하려면 API 자격 증명 테스트를 선택합니다.
- 저장을 선택합니다.
- API 통합 세부 정보를 저장한 후, 왼쪽에 새로운 설정 탭이 나타납니다. 앱으로를 선택합니다.
- 편집을 선택합니다.
- 사용자 생성 및 사용자 비활성화 체크 상자 모두에 대한 활성화 확인란을 선택합니다.
- 저장을 선택합니다.
- 할당 탭에서 사용자에게 할당합니다. 할당된 사용자는 GitLab 그룹에서 생성 및 관리됩니다.
사용자 액세스
동기화 프로세스 중에 모든 새 사용자는 다음과 같습니다:
- GitLab 계정을 받습니다.
- 초대 이메일로 그룹에 환영받습니다. 사용자 이메일 확인을 우회하려면 확인된 도메인으로 이메일 확인 우회할 수 있습니다.
다음 다이어그램은 SCIM 앱에 사용자를 추가할 때 발생하는 일을 설명합니다:
프로비저닝 중에:
- GitLab 사용자 계정이 있는지 확인할 때 기본 및 보조 이메일이 모두 고려됩니다.
- 중복된 사용자 이름은 사용자를 생성할 때
1
접미사가 추가됩니다. 예를 들어,test_user
가 이미 있으면test_user1
가 사용됩니다.test_user1
이 이미 존재하는 경우, GitLab은 사용자를 찾을 때까지 접미사를 증가시킵니다. 4회 시도한 후에도 사용자 이름을 찾을 수 없으면 무작위 문자열이 사용자 이름에 추가됩니다.
이후 방문에서, 새로운 및 기존 사용자는 그룹에 다음을 통해 액세스할 수 있습니다:
- Identity provider의 대시보드를 통해.
- 직접 링크를 방문함으로써.
역할 정보는 그룹 SAML 페이지를 참조하세요.
GitLab 그룹을 통해 SCIM으로 생성된 사용자의 비밀번호
GitLab은 모든 사용자 계정에 대한 비밀번호를 요구합니다. SCIM 프로비저닝을 사용하여 생성된 사용자의 경우 GitLab은 자동으로 임의의 비밀번호를 생성하며, 사용자는 첫 로그인 시 비밀번호를 설정할 필요가 없습니다. GitLab 그룹을 통해 SCIM을 사용하여 생성된 사용자의 비밀번호를 자세히 알아보려면 통합 인증을 통해 생성된 사용자를 위한 생성된 비밀번호을 참조하십시오.
SCIM 및 SAML 식별 정보 링크
만약 그룹 SAML이 구성되어 있고 기존의 GitLab.com 계정이 있다면, 사용자는 그들의 SCIM 및 SAML 식별 정보를 링크시킬 수 있습니다. 동기화가 활성화된 상태에서는 기존 사용자들에 대해 프로비저닝 오류가 발생할 수 있기 때문에 사용자는 동기화가 켜기 전에 이 작업을 수행해야 합니다.
SCIM 및 SAML 식별 정보를 링크하려면 다음을 수행하세요:
- GitLab.com 사용자 계정의 기본 이메일 주소를 사용자 프로필 이메일 주소와 일치하도록 업데이트합니다.
- SAML 식별 정보를 링크하세요.
액세스 제거
식별 공급자에서 사용자의 액세스를 제거하려면 해당 사용자를 제거하거나 비활성화하세요:
- 최상위 그룹.
- 모든 하위 그룹 및 프로젝트.
식별 공급자가 구성된 일정에 따라 동기화를 수행한 후 사용자의 멤버십이 취소되어 액세스 권한이 상실됩니다.
SCIM을 활성화하더라도 SAML 식별 정보가 없는 기존 사용자는 자동으로 제거되지 않습니다.
액세스 재활성화
- GitLab 16.0에서 도입됨 skip_saml_identity_destroy_during_scim_deprovision이라는 플래그로 비활성화되었음 (기본 설정).
- GitLab 16.4에서 일반적으로 사용 가능. 피처 플래그
skip_saml_identity_destroy_during_scim_deprovision
이 제거됨.
SCIM을 통해 사용자를 제거하거나 비활성화한 후, 해당 사용자를 SCIM 식별 공급자에 추가함으로써 사용자를 다시 활성화할 수 있습니다.
식별 공급자가 구성된 일정에 따라 동기화를 수행한 후 해당 사용자의 SCIM 식별 정보가 재활성화되며 그들의 그룹 멤버십이 복원됩니다.