개방형 표준인 SCIM(System for Cross-domain Identity Management)을 사용하여 다음 작업을 자동화할 수 있습니다:

• 사용자 생성.
• 사용자 제거(SCIM ID 비활성화).
• 사용자 재추가(SCIM ID 재활성화).

GitLab SAML SSO SCIM은 사용자 업데이트를 지원하지 않습니다.

GitLab 그룹에 SCIM이 활성화되면 해당 그룹의 멤버십이 GitLab과 ID 공급자 간에 동기화됩니다.

내부 GitLab 그룹 SCIM API는 RFC7644 프로토콜의 일부를 구현합니다. ID 공급자는 내부 GitLab 그룹 SCIM API로 SCIM 앱을 개발할 수 있습니다.

GitLab Self-Managed에서 SCIM을 설정하려면 GitLab Self-Managed용 SCIM 구성을 참고합니다.

GitLab 구성#

사전 요구 사항:

• 그룹 Single Sign-On이 구성되어 있어야 합니다.

GitLab SAML SSO SCIM을 구성하려면:

1. 상단 바에서 Search or go to를 선택하고 그룹을 찾습니다.
2. 왼쪽 사이드바에서 Settings > SAML SSO를 선택합니다.
3. Generate a SCIM token을 선택합니다.
4. ID 공급자 구성을 위해 다음을 저장합니다:
   • Your SCIM token 필드의 토큰.
   • SCIM API endpoint URL 필드의 URL.

ID 공급자 구성#

GitLab은 여러 ID 공급자에서 SCIM을 지원합니다. 다른 ID 공급자도 GitLab과 동작할 수 있지만 테스트되지 않았으며 지원되지 않습니다. 지원되지 않는 공급자에 대한 도움이 필요하면 해당 공급자에 직접 문의합니다. GitLab 지원팀은 관련 로그 항목 검토를 도울 수 있습니다.

Okta 구성#

Okta의 Single Sign-On 설정 중에 만든 SAML 애플리케이션을 SCIM용으로 설정해야 합니다.

사전 요구 사항:

• Okta Lifecycle Management 제품을 사용해야 합니다. Okta에서 SCIM을 사용하려면 이 제품 티어가 필요합니다.
• GitLab이 구성되어 있어야 합니다.
• Okta용 SAML 애플리케이션이 Okta 설정 참고 사항에 설명된 대로 설정되어 있어야 합니다.
• Okta SAML 설정이 구성 단계와 정확히 일치해야 하며, 특히 NameID 구성이 그렇습니다.

SCIM용으로 Okta를 구성하려면:

1. Okta에 로그인합니다.
2. 오른쪽 위에서 Admin을 선택합니다. 이 버튼은 Admin 영역에서는 보이지 않습니다.
3. Application 탭에서 Browse App Catalog를 선택합니다.
4. GitLab을 검색하여 GitLab 애플리케이션을 찾아 선택합니다.
5. GitLab 애플리케이션 개요 페이지에서 Add를 선택합니다.
6. Application Visibility에서 두 체크박스를 모두 선택합니다. 현재 GitLab 애플리케이션은 SAML 인증을 지원하지 않으므로 아이콘이 사용자에게 표시되지 않아야 합니다.
7. Done을 선택하여 애플리케이션 추가를 마칩니다.
8. Provisioning 탭에서 Configure API integration을 선택합니다.
9. Enable API integration을 선택합니다.
   • Base URL에는 GitLab SCIM 구성 페이지의 SCIM API endpoint URL에서 복사한 URL을 붙여 넣습니다.
   • API Token에는 GitLab SCIM 구성 페이지의 Your SCIM token에서 복사한 SCIM 토큰을 붙여 넣습니다.
10. 구성을 확인하려면 Test API Credentials를 선택합니다.
11. Save를 선택합니다.
12. API 통합 정보를 저장하면 왼쪽에 새 설정 탭이 나타납니다. To App을 선택합니다.
13. Edit를 선택합니다.
14. Create Users와 Deactivate Users 모두에 대해 Enable 체크박스를 선택합니다.
15. Save를 선택합니다.
16. Assignments 탭에서 사용자를 할당합니다. 할당된 사용자는 GitLab 그룹에서 생성되고 관리됩니다.

Microsoft Entra ID 구성#

사전 요구 사항:

• GitLab이 구성되어 있어야 합니다.
• 그룹 Single Sign-On이 구성되어 있어야 합니다.

Azure Active Directory의 Single Sign-On 설정 중에 만든 SAML 애플리케이션을 SCIM용으로 설정해야 합니다. 예시는 예시 구성을 참고합니다.

SCIM용으로 Microsoft Entra ID를 구성하려면:

1. 앱에서 Provisioning 탭으로 이동한 후 Get started를 선택합니다.
2. Provisioning Mode를 Automatic으로 설정합니다.
3. Admin Credentials를 다음 값으로 채웁니다:
   • Tenant URL 필드에는 GitLab의 SCIM API endpoint URL.
   • Secret Token 필드에는 GitLab의 Your SCIM token.
4. Test Connection을 선택합니다. 테스트가 성공하면 계속하기 전에 구성을 저장하고, 실패하면 문제 해결 정보를 참고합니다.
5. Save를 선택합니다.

저장하면 Mappings와 Settings 섹션이 나타납니다.

매핑 구성#

Mappings 섹션에서 먼저 그룹을 프로비저닝합니다:

1. Provision Microsoft Entra ID Groups를 선택합니다.

2. Attribute Mapping 페이지에서 Enabled 토글을 끕니다. GitLab은 SCIM 그룹 프로비저닝을 지원하지 않습니다. 그룹 프로비저닝을 켜 두어도 SCIM 사용자 프로비저닝이 중단되지는 않지만, Entra ID SCIM 프로비저닝 로그에 혼란을 주는 오해의 소지가 있는 오류가 발생합니다.

   [!note] Provision Microsoft Entra ID Groups가 비활성화되어 있어도 매핑 섹션에 "Enabled: Yes" 가 표시될 수 있습니다. 이는 표시상의 버그이므로 무시해도 됩니다.

3. Save를 선택합니다.

다음으로 사용자를 프로비저닝합니다:

1. Provision Microsoft Entra ID Users를 선택합니다.
2. Enabled 토글이 Yes로 설정되어 있는지 확인합니다.
3. 모든 Target Object Actions가 활성화되어 있는지 확인합니다.
4. Attribute Mappings에서 구성된 속성 매핑과 일치하도록 매핑을 구성합니다:
   1. 선택 사항. customappsso Attribute 칼럼에서 externalId를 찾아 삭제합니다.
   2. 첫 번째 속성을 다음과 같이 편집합니다:
      • source attribute: objectId
      • target attribute: externalId
      • matching precedence: 1
   3. 기존 customappsso 속성을 구성된 속성 매핑과 일치하도록 갱신합니다.
   4. 다음 표에 없는 추가 속성은 삭제합니다. 삭제하지 않아도 문제가 되지는 않지만 GitLab은 해당 속성을 사용하지 않습니다.
5. 매핑 목록 아래에서 Show advanced options 체크박스를 선택합니다.
6. Edit attribute list for customappsso 링크를 선택합니다.
7. id가 기본이자 필수 필드이고 externalId도 필수인지 확인합니다.
8. Save를 선택하면 Attribute Mapping 구성 페이지로 돌아갑니다.
9. Attribute Mapping 구성 페이지를 닫으려면 오른쪽 위의 X를 선택합니다.

설정 구성#

Settings 섹션에서:

1. 선택 사항. 필요하면 Send an email notification when a failure occurs 체크박스를 선택합니다.
2. 선택 사항. 필요하면 Prevent accidental deletion 체크박스를 선택합니다.
3. 필요하면 Save를 선택하여 모든 변경 사항이 저장되었는지 확인합니다.

매핑과 설정을 구성한 후 앱 개요 페이지로 돌아가 Start provisioning을 선택하면 GitLab에서 사용자의 자동 SCIM 프로비저닝이 시작됩니다.

속성 매핑 구성#

SCIM용 Entra ID 구성 과정에서 속성 매핑을 구성합니다. 예시는 예시 구성을 참고합니다.

다음 표는 GitLab에 필요한 속성 매핑을 보여 줍니다.

각 속성 매핑은 다음으로 구성됩니다:

• target attribute에 해당하는 customappsso Attribute.
• source attribute에 해당하는 Microsoft Entra ID Attribute.
• 일치 우선순위.

각 속성에 대해:

1. 기존 속성을 편집하거나 새 속성을 추가합니다.
2. 드롭다운 목록에서 필요한 소스 및 대상 속성 매핑을 선택합니다.
3. Ok를 선택합니다.
4. Save를 선택합니다.

SAML 구성이 권장 SAML 설정과 다르면 매핑 속성을 선택하여 그에 맞게 수정합니다. externalId 대상 속성에 매핑하는 소스 속성은 SAML NameID에 사용된 속성과 일치해야 합니다.

표에 없는 매핑은 Microsoft Entra ID 기본값을 사용합니다. 필수 속성 목록은 내부 그룹 SCIM API 문서를 참고합니다.

사용자 액세스#

동기화 과정에서 모든 신규 사용자는:

• GitLab 계정을 받습니다.
• 초대 이메일로 그룹에 초대됩니다. 검증된 도메인으로 이메일 확인을 생략할 수 있습니다.

제한된 액세스로 프로비저닝 동작#

제한된 액세스가 활성화되어 있고 사용 가능한 구독 좌석이 없으면, SCIM으로 프로비저닝된 사용자에게 Minimal Access 권한이 부여됩니다.

이 경우 사용자는 Minimal Access로 정상 생성되며(응답 HTTP 201 Created), 사용자의 roles 속성에 이 할당이 반영됩니다. 사용 가능한 좌석이 없으면 이후의 권한 갱신 작업은 실패할 수 있습니다.

자세한 내용은 SAML, SCIM, LDAP의 프로비저닝 동작을 참고합니다.

다음 다이어그램은 SCIM 앱에 사용자를 추가할 때 일어나는 일을 보여 줍니다:

%%{init: { "fontFamily": "GitLab Sans" }}%%
graph TD
accTitle: Adding users to your SCIM application
accDescr: How GitLab determines whether or not to associate a SCIM identity with a user.
A[Add User to SCIM app] -->|IdP sends user info to GitLab| B(GitLab: Does the email exist?)
B -->|No| C[GitLab creates user with SCIM identity]
B -->|Yes| D(GitLab: Is the user part of the group?)
D -->|No| E(GitLab: Is SSO enforcement enabled?)
E -->|No| G
E -->|Yes| F[GitLab sends message back:
The member's email address is not linked to a SAML account]
D -->|Yes| G[Associate SCIM identity to user]

프로비저닝 중에는:

• GitLab 사용자 계정이 존재하는지 확인할 때 기본 이메일과 보조 이메일을 모두 고려합니다.
• 사용자 이름이 중복되면 사용자를 만들 때 접미사 1을 붙여 처리합니다. 예를 들어 test_user가 이미 존재하면 test_user1 이 사용됩니다. test_user1도 이미 있으면 GitLab은 사용되지 않은 사용자 이름을 찾을 때까지 접미사를 늘립니다. 4회 시도 후에도 찾지 못하면 사용자 이름에 임의의 문자열을 붙입니다.

이후 방문 시 신규 및 기존 사용자는 다음 방법으로 그룹에 접근할 수 있습니다:

• ID 공급자의 대시보드를 통해 접근합니다.
• 링크에 직접 접속합니다.

권한 정보는 그룹 SAML 페이지를 참고합니다.

GitLab 그룹에 대한 SCIM을 통해 생성된 사용자의 비밀번호#

GitLab은 모든 사용자 계정에 비밀번호를 요구합니다. SCIM 프로비저닝으로 생성된 사용자에게는 GitLab이 임의의 비밀번호를 자동으로 생성하므로, 사용자는 첫 로그인 시 비밀번호를 설정할 필요가 없습니다. GitLab 그룹에 대한 SCIM으로 생성된 사용자의 비밀번호를 GitLab이 어떻게 생성하는지는 통합 인증으로 생성된 사용자의 생성된 비밀번호를 참고합니다.

SCIM 및 SAML ID 연결#

그룹 SAML이 구성되어 있고 기존 GitLab.com 계정이 있으면 사용자는 SCIM ID와 SAML ID를 연결할 수 있습니다. 동기화가 활성화된 상태에서는 기존 사용자에게 프로비저닝 오류가 발생할 수 있으므로, 동기화를 켜기 전에 연결하는 것이 좋습니다.

SCIM ID와 SAML ID를 연결하려면:

1. GitLab.com 사용자 계정의 기본 이메일 주소를 ID 공급자의 사용자 프로필 이메일 주소와 일치하도록 갱신합니다.
2. SAML ID를 연결합니다.

액세스 제거#

ID 공급자에서 사용자를 제거하거나 비활성화하면 다음에 대한 액세스가 제거됩니다:

• 최상위 그룹.
• 모든 하위 그룹 및 프로젝트.

ID 공급자가 구성된 일정에 따라 동기화를 수행하면 해당 사용자의 멤버십이 취소되고 액세스 권한을 잃습니다. 사용자의 GitLab 계정은 삭제되지 않으며 GitLab.com에 계속 존재합니다.

SCIM으로 사용자의 프로비저닝을 해제해도 연결된 SAML ID는 제거되지 않습니다.

Enterprise 사용자를 구성했다면 해당 사용자를 삭제할 수 있습니다.

SCIM을 활성화해도 SAML ID가 없는 기존 사용자가 자동으로 제거되지는 않습니다.

%%{init: { "fontFamily": "GitLab Sans" }}%%
graph TD
accTitle: Deprovisioning users
accDescr: How removing users from your SCIM app removes them from GitLab groups.
A[Remove User from SCIM app] -->|IdP sends request to GitLab| B(GitLab: Is the user part of the group?)
B -->|No| C[Nothing to do]
B -->|Yes| D[GitLab removes user from GitLab group]

액세스 재활성화#

SCIM으로 사용자를 제거하거나 비활성화한 후에는 해당 사용자를 SCIM ID 공급자에 다시 추가하여 재활성화할 수 있습니다.

ID 공급자가 구성된 일정에 따라 동기화를 수행하면 사용자의 SCIM ID가 재활성화되고 그룹 멤버십이 복원됩니다. 프로비저닝 해제 중에도 연결된 SAML ID가 유지되므로 사용자는 즉시 SSO로 로그인할 수 있습니다.

GitLab은 SCIM 프로비저닝 해제를 비동기로 처리합니다. 프로세스가 끝나기 전에 사용자를 재활성화하면 재활성화 요청이 실패합니다. 자세한 내용은 오류: User is pending deprovisioning을 참고합니다.