사용자는 자신의 SAML ID 공급자를 통해 GitLab에 로그인할 수 있습니다.

SCIM은 GitLab.com의 그룹과 사용자를 동기화합니다.

• SCIM 앱에서 사용자를 추가하거나 제거하면 SCIM이 GitLab 그룹에서 해당 사용자를 추가하거나 제거합니다.
• 사용자가 아직 그룹 멤버가 아니라면 로그인 과정의 일부로 그룹에 추가됩니다.

SAML SSO는 최상위 그룹에만 구성할 수 있습니다.

ID 공급자 설정#

SAML 표준을 사용하므로 GitLab에서는 다양한 ID 공급자를 사용할 수 있습니다. 사용 중인 ID 공급자에 관련 문서가 있을 수 있습니다. 일반적인 SAML 문서일 수도 있고 GitLab을 대상으로 작성된 문서일 수도 있습니다.

ID 공급자를 설정할 때는 다음의 공급자별 문서를 사용해 흔한 문제를 피하고 사용되는 용어를 확인합니다.

목록에 없는 ID 공급자는 ID 공급자 구성에 관한 인스턴스 SAML 참고 사항에서 공급자가 요구할 수 있는 정보에 관한 추가 안내를 참고할 수 있습니다.

GitLab이 제공하는 다음 정보는 안내 목적입니다. SAML 앱 구성에 관한 문의는 공급자의 지원 팀에 전달합니다.

ID 공급자 설정에 문제가 있으면 문제 해결 문서를 참고합니다.

Azure#

Azure를 ID 공급자로 사용해 SSO를 설정하려면 다음과 같이 합니다.

1. 상단 바에서 Search or go to를 선택하고 그룹을 찾습니다.

2. 왼쪽 사이드바에서 Settings > SAML SSO를 선택합니다.

3. 이 페이지의 정보를 기록해 둡니다.

4. Azure로 이동해 갤러리에 없는 애플리케이션을 만들고 애플리케이션용 SSO를 구성합니다. 다음 GitLab 설정이 Azure 필드에 대응합니다.

   GitLab 설정	Azure 필드
   Identifier	Identifier (Entity ID)
   Assertion consumer service URL	Reply URL (Assertion Consumer Service URL)
   GitLab single sign-on URL	Sign on URL
   Identity provider single sign-on URL	Login URL
   Certificate fingerprint	Thumbprint

5. 다음 속성을 설정해야 합니다.

   • **Unique User Identifier (Name ID)**를 user.objectID로 설정합니다.
     • Name identifier format을 persistent로 설정합니다. 자세한 내용은 사용자 SAML 아이덴티티 관리를 참고합니다.
   • Additional claims를 지원되는 속성으로 설정합니다.

6. 기존 GitLab 계정을 연결하도록 ID 공급자가 공급자 주도 호출을 사용하게 설정되어 있는지 확인합니다.

7. 선택 사항. 그룹 동기화를 사용한다면 필요한 속성에 맞도록 그룹 클레임의 이름을 사용자 지정합니다.

그룹용 SAML SSO를 사용한 Azure SCIM 프로비저닝 데모를 확인합니다. 이 영상의 objectID 매핑은 최신 내용이 아닙니다. 대신 SCIM용 Microsoft Entra ID 구성 문서의 지침을 따릅니다.

자세한 내용은 Azure 구성 예시를 참고합니다.

Google Workspace#

Google Workspace를 ID 공급자로 설정하려면 다음과 같이 합니다.

1. 상단 바에서 Search or go to를 선택하고 그룹을 찾습니다.

2. 왼쪽 사이드바에서 Settings > SAML SSO를 선택합니다.

3. 이 페이지의 정보를 기록해 둡니다.

4. Google을 ID 공급자로 사용해 SSO 설정하기의 지침을 따릅니다. 다음 GitLab 설정이 Google Workspace 필드에 대응합니다.

   GitLab 설정	Google Workspace 필드
   Identifier	Entity ID
   Assertion consumer service URL	ACS URL
   GitLab single sign-on URL	Start URL
   Identity provider single sign-on URL	SSO URL

5. Google Workspace는 인증서를 가져올 때 SHA256 지문을 표시합니다. 나중에 SHA256 지문을 생성해야 한다면 지문 계산을 참고합니다.

6. 다음 값을 설정합니다.

   • Primary email에는 email.
   • First name에는 first_name.
   • Last name에는 last_name.
   • Name ID format에는 EMAIL.
   • NameID에는 Basic Information > Primary email. 자세한 내용은 지원되는 속성을 참고합니다.

7. 기존 GitLab 계정을 연결하도록 ID 공급자가 공급자 주도 호출을 사용하게 설정되어 있는지 확인합니다.

GitLab SAML SSO 페이지에서 Verify SAML Configuration을 선택했을 때 NameID 형식을 persistent로 설정하라고 권장하는 경고는 무시합니다.

자세한 내용은 Google Workspace 구성 예시를 참고합니다.

Google Workspaces로 SAML을 구성하고 그룹 동기화를 설정하는 방법 데모를 확인합니다.

Okta#

Okta를 ID 공급자로 사용해 SSO를 설정하려면 다음과 같이 합니다.

1. 상단 바에서 Search or go to를 선택하고 그룹을 찾습니다.

2. 왼쪽 사이드바에서 Settings > SAML SSO를 선택합니다.

3. 이 페이지의 정보를 기록해 둡니다.

4. Okta에서 SAML 애플리케이션 생성의 지침을 따릅니다.

   다음 GitLab 설정이 Okta 필드에 대응합니다.

   GitLab 설정	Okta 필드
   Identifier	Audience URI
   Assertion consumer service URL	Single sign-on URL
   GitLab single sign-on URL	Login page URL(Application Login Page 설정 아래)
   Identity provider single sign-on URL	Identity Provider Single Sign-On URL

5. Okta의 Single sign-on URL 필드 아래에서 Use this for Recipient URL and Destination URL 체크박스를 선택합니다.

6. 다음 값을 설정합니다.

   • **Application username (NameID)**에는 Custom user.getInternalProperty("id").
   • Name ID Format에는 Persistent. 자세한 내용은 사용자 SAML 아이덴티티 관리를 참고합니다.
   • email에는 user.email 또는 이와 비슷한 값.
   • 추가 Attribute Statements는 지원되는 속성을 참고합니다.

7. 기존 GitLab 계정을 연결하도록 ID 공급자가 공급자 주도 호출을 사용하게 설정되어 있는지 확인합니다.

App Catalog에서 제공되는 Okta GitLab 애플리케이션은 SCIM만 지원합니다. SAML 지원은 이슈 216173에서 제안되어 있습니다.

SCIM을 포함한 Okta SAML 설정 데모는 Demo: Okta Group SAML & SCIM setup을 참고합니다.

자세한 내용은 Okta 구성 예시를 참고합니다.

OneLogin#

OneLogin은 자체 GitLab.com 애플리케이션을 지원합니다.

OneLogin을 ID 공급자로 설정하려면 다음과 같이 합니다.

1. 상단 바에서 Search or go to를 선택하고 그룹을 찾습니다.

2. 왼쪽 사이드바에서 Settings > SAML SSO를 선택합니다.

3. 이 페이지의 정보를 기록해 둡니다.

4. OneLogin의 일반 SAML Test Connector (Advanced)를 사용한다면 OneLogin SAML Test Connector를 사용해야 합니다. 다음 GitLab 설정이 OneLogin 필드에 대응합니다.

   GitLab 설정	OneLogin 필드
   Identifier	Audience
   Assertion consumer service URL	Recipient
   Assertion consumer service URL	ACS (Consumer) URL
   Assertion consumer service URL (escaped version)	ACS (Consumer) URL Validator
   GitLab single sign-on URL	Login URL
   Identity provider single sign-on URL	SAML 2.0 Endpoint

5. NameID에는 OneLogin ID를 사용합니다. 자세한 내용은 사용자 SAML 아이덴티티 관리를 참고합니다.

6. 필수 및 지원되는 속성을 구성합니다.

7. 기존 GitLab 계정을 연결하도록 ID 공급자가 공급자 주도 호출을 사용하게 설정되어 있는지 확인합니다.

자세한 내용은 OneLogin 구성 예시를 참고합니다.

Keycloak#

Keycloak을 ID 공급자로 설정하려면 다음과 같이 합니다.

1. 상단 바에서 Search or go to를 선택하고 그룹을 찾습니다.
2. 왼쪽 사이드바에서 Settings > SAML SSO를 선택합니다.
3. 이 페이지의 정보를 기록해 둡니다.
4. Keycloak에서 SAML 클라이언트 만들기 지침을 따릅니다.

다음 GitLab 설정이 Keycloak 필드에 대응합니다.

1. Keycloak에서 GitLab 클라이언트를 구성합니다.
   1. Keycloak에서 Clients로 이동해 GitLab 클라이언트 구성을 선택합니다.
   2. Settings 탭의 SAML capabilities 섹션에서 다음과 같이 합니다.
      1. Name ID format을 persistent로 설정합니다.
      2. Force name ID format을 켭니다.
      3. Force POST binding을 켭니다.
      4. Include AuthnStatement를 켭니다.
   3. Signature and Encryption 섹션에서 Sign documents를 켭니다.
   4. Keys 탭에서 모든 섹션이 비활성화되어 있는지 확인합니다.
   5. Client scopes 탭에서 다음과 같이 합니다.
      1. GitLab용 클라이언트 스코프를 선택합니다. 스코프 이름은 https://gitlab.com/groups/your-group-name-dedicated와 비슷한 형태여야 합니다.
      2. Configure a new mapper를 선택하고, 열리는 창에서 User Attribute를 선택합니다.
      3. Add mapper 페이지에서 Name, User Attribute, SAML Attribute Name 필드를 email로 설정합니다.
      4. Save를 선택합니다.
2. Keycloak에서 클라이언트 정보를 가져옵니다.
   1. Action 드롭다운 목록에서 Download adapter config를 선택합니다.
   2. Download adapter config 대화 상자의 드롭다운 목록에서 mod-auth-mellon을 선택합니다.
   3. Download를 선택합니다.
   4. 내려받은 아카이브의 압축을 풀고 idp-metadata.xml을 엽니다.
   5. ID 공급자 단일 로그인 URL을 가져옵니다.
      1. <md:SingleSignOnService> 태그를 찾습니다.
      2. Location 속성의 값을 기록해 둡니다.
   6. 인증서 지문을 가져옵니다.
      1. <ds:X509Certificate> 태그의 값을 기록해 둡니다.
      2. 그 값을 별도 파일로 복사하고 PEM 형식으로 변환합니다. 변환하려면 파일 맨 앞에 -----BEGIN CERTIFICATE-----를, 맨 뒤에 -----END CERTIFICATE-----를 새 줄로 추가합니다.
      3. 지문을 계산합니다.

AWS IAM Identity Center#

AWS IAM Identity Center는 기본적으로 IdP 주도 로그인을 사용합니다. 기존 GitLab 계정을 연결하려면 SP 주도 로그인을 구성해야 합니다. 자세한 내용은 SP 주도 로그인을 참고합니다.

AWS IAM Identity Center를 ID 공급자로 사용해 SSO를 설정하려면 다음과 같이 합니다.

1. 상단 바에서 Search or go to를 선택하고 그룹을 찾습니다.

2. Settings > SAML SSO를 선택하고 이 페이지의 값을 기록해 둡니다.

3. AWS IAM Identity Center 콘솔에서 사용자 지정 SAML 2.0 애플리케이션을 설정합니다. 메타데이터 값을 입력하라는 안내가 나오면 다음을 입력합니다.

   GitLab 설정	AWS IAM Identity Center 필드
   Assertion consumer service URL	Application ACS URL
   Identifier	Application SAML audience

4. SP 주도 로그인을 활성화하려면 Application start URL을 (GitLab SAML SSO 설정 페이지의) GitLab single sign-on URL로 설정합니다.

5. Attribute mappings 아래에서 다음을 구성합니다.

   속성	값	형식
   Subject	${user:email}	unspecified
   email	${user:email}	unspecified
   first_name	${user:givenName}	unspecified
   last_name	${user:familyName}	unspecified

   [!warning] Subject(NameID) 형식은 반드시 unspecified로 설정해야 합니다. 형식을 persistent 또는 transient로 설정하면 계정을 연결하려는 기존 GitLab 사용자에게 인증 오류가 발생합니다.

6. IAM Identity Center SAML metadata 아래에서 IAM Identity Center sign-in URL을 복사하고 인증서를 내려받습니다.

7. 터미널에서 내려받은 인증서로 SHA1 지문을 생성합니다.

   openssl x509 -noout -fingerprint -sha1 -inform pem -in <path-to-downloaded-cert.pem>
   

8. GitLab의 그룹 SAML SSO 설정 페이지에서 다음 필드를 입력합니다.

   • Identity provider single sign-on URL: IAM Identity Center sign-in URL을 입력합니다.
   • Certificate fingerprint: SHA1 지문 값을 입력합니다.

9. AWS IAM Identity Center에서 GitLab 애플리케이션에 사용자를 할당합니다. 기존 GitLab 계정을 연결하려면 사용자가 GitLab single sign-on URL 또는 Application start URL에서 로그인해야 합니다.

자세한 내용은 AWS IAM Identity Center 구성 예시를 참고합니다.

SP 주도 로그인#

사용자가 ID 공급자 대시보드를 통해 로그인하면(IdP 주도 로그인) SAML 응답에 InResponseTo 속성이 포함되지 않습니다. GitLab은 SAML 아이덴티티를 기존 계정에 연결하기 위해 이 속성을 요구합니다.

AWS IAM Identity Center는 기본적으로 IdP 주도 로그인을 사용합니다. Application start URL이 구성되어 있지 않으면 기존 사용자가 로그인을 시도할 때 Request to link SAML account must be authorized 오류를 보게 됩니다.

이를 방지하려면 Application start URL을 GitLab single sign-on URL로 설정합니다. 그러면 사용자가 GitLab에서 로그인 흐름을 시작하므로 SAML 응답에 InResponseTo 속성이 포함됩니다.

어설션 구성#

최소한 다음 어설션을 구성해야 합니다.

1. NameID.
2. 이메일.

선택적으로 SAML 어설션의 속성으로 사용자 정보를 GitLab에 전달할 수 있습니다.

• 사용자의 이메일 주소는 email 또는 mail 속성일 수 있습니다.
• 사용자 이름은 username 또는 nickname 속성일 수 있습니다. 이 중 하나만 지정해야 합니다.

사용할 수 있는 속성에 관한 자세한 내용은 GitLab Self-Managed용 SAML SSO를 참고합니다.

메타데이터 사용#

일부 ID 공급자를 구성하려면 GitLab 메타데이터 URL이 필요합니다. 이 URL을 찾으려면 다음과 같이 합니다.

1. 상단 바에서 Search or go to를 선택하고 그룹을 찾습니다.
2. 왼쪽 사이드바에서 Settings > SAML SSO를 선택합니다.
3. 제공된 GitLab metadata URL을 복사합니다.
4. ID 공급자의 문서를 따르고, 메타데이터 URL을 요청하면 붙여 넣습니다.

GitLab 메타데이터 URL을 지원하는지는 ID 공급자의 문서에서 확인합니다.

ID 공급자 관리#

ID 공급자를 설정한 뒤에는 다음을 할 수 있습니다.

• ID 공급자 변경.
• 이메일 도메인 변경.

ID 공급자 변경#

다른 ID 공급자로 변경할 수 있습니다. 변경 과정에서는 사용자가 어떤 SAML 그룹에도 액세스할 수 없습니다. 이를 완화하려면 SSO 적용을 비활성화할 수 있습니다.

ID 공급자를 변경하려면 다음과 같이 합니다.

1. 새 ID 공급자로 그룹을 구성합니다.
2. 선택 사항. NameID가 동일하지 않으면 사용자의 NameID를 변경합니다.

이메일 도메인 변경#

사용자를 새 이메일 도메인으로 마이그레이션하려면 사용자에게 다음을 안내합니다.

1. 계정에 새 이메일을 추가해 기본 이메일로 설정하고 확인합니다.
2. 선택 사항. 계정에서 이전 이메일을 제거합니다.

NameID가 이메일 주소로 구성되어 있으면 사용자의 NameID를 변경합니다.

GitLab 구성#

GitLab과 연동되도록 ID 공급자를 설정한 뒤에는 인증에 ID 공급자를 사용하도록 GitLab을 구성해야 합니다.

1. 상단 바에서 Search or go to를 선택하고 그룹을 찾습니다.
2. 왼쪽 사이드바에서 Settings > SAML SSO를 선택합니다.
3. 다음 필드를 입력합니다.
   • Identity provider single sign-on URL 필드에 ID 공급자의 SSO URL을 입력합니다.
   • Certificate fingerprint 필드에 SAML 토큰 서명 인증서의 지문을 입력합니다.
4. GitLab.com의 그룹인 경우: Default membership role 필드에서 다음을 선택합니다.
   1. 신규 사용자에게 할당할 권한.
   2. 그룹에 SAML Group Links가 구성되어 있을 때 매핑된 SAML 그룹의 멤버가 아닌 사용자에게 할당할 권한.
5. GitLab Self-Managed 인스턴스의 그룹인 경우: Default membership role 필드에서 신규 사용자에게 할당할 권한을 선택합니다. 기본 권한은 Guest입니다. 이 권한이 그룹에 추가되는 모든 사용자의 시작 권한이 됩니다. 그룹 Owner는 사용자 지정 역할을 기본 멤버십 권한으로 설정할 수 있습니다.
6. Enable SAML authentication for this group 체크박스를 선택합니다.
7. 권장 사항. 다음을 선택합니다.
   • GitLab 17.4 이상에서는 Disable password and passkey authentication for enterprise users. 자세한 내용은 엔터프라이즈 사용자의 비밀번호 및 패스키 인증 비활성화 문서를 참고합니다.
   • Enforce SSO-only authentication for web activity for this group.
   • Enforce SSO-only authentication for Git and Dependency Proxy activity for this group. 자세한 내용은 SSO 적용 문서를 참고합니다.
8. Save changes를 선택합니다.

GitLab 구성에 문제가 있으면 문제 해결 문서를 참고합니다.

사용자 액세스 및 관리#

그룹 SSO를 구성하고 활성화하면 사용자는 ID 공급자의 대시보드를 통해 GitLab.com 그룹에 액세스할 수 있습니다. SCIM이 구성되어 있으면 SCIM 페이지의 사용자 액세스를 참고합니다.

사용자가 그룹 SSO로 로그인을 시도하면 GitLab은 다음을 기준으로 사용자를 찾거나 생성하려고 시도합니다.

• SAML 아이덴티티가 일치하는 기존 사용자를 찾습니다. 이는 해당 사용자의 계정이 SCIM으로 생성되었거나, 그 사용자가 이전에 그룹의 SAML IdP로 로그인했다는 뜻입니다.
• 같은 이메일 주소의 계정이 아직 없으면 새 계정을 자동으로 생성합니다. GitLab은 기본 이메일 주소와 보조 이메일 주소를 모두 대조합니다.
• 같은 이메일 주소의 계정이 이미 있으면 다음을 위해 사용자를 로그인 페이지로 리디렉션합니다.
  • 다른 이메일 주소로 새 계정을 생성합니다.
  • 기존 계정에 로그인해 SAML 아이덴티티를 연결합니다.

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

히스토리

• GitLab 18.6에서 bso_minimal_access_fallback이라는 이름의 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
• GitLab 18.10에서 기본적으로 활성화되었습니다.
• GitLab 19.5에서 일반 공급되었습니다. 기능 플래그 bso_minimal_access_fallback이 제거되었습니다.

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

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

SAML을 기존 GitLab.com 계정에 연결#

SAML을 기존 GitLab.com 계정에 연결하려면 다음과 같이 합니다.

1. GitLab.com 계정에 로그인합니다. 필요하면 비밀번호를 재설정 합니다.
2. 로그인하려는 그룹의 GitLab single sign-on URL을 찾아 방문합니다. 그룹 Owner는 그룹의 Settings > SAML SSO 페이지에서 이 URL을 확인할 수 있습니다. 로그인 URL이 구성되어 있으면 사용자는 ID 공급자에서 GitLab 앱에 연결할 수 있습니다.
3. 선택 사항. GitLab에 2주간 로그인 상태를 유지하려면 Remember me 체크박스를 선택합니다. 그래도 SAML 공급자로 더 자주 다시 인증하라는 요청을 받을 수 있습니다.
4. Authorize를 선택합니다.
5. 안내가 나오면 ID 공급자에 자격 증명을 입력합니다.
6. 그러면 GitLab.com으로 다시 리디렉션되고 이제 그룹에 액세스할 수 있습니다. 이후에는 SAML로 GitLab.com에 로그인할 수 있습니다.

사용자가 이미 그룹 멤버라면 SAML 아이덴티티를 연결해도 해당 사용자의 권한은 변경되지 않습니다.

이후 방문에서는 SAML로 GitLab.com에 로그인하거나 링크를 직접 방문해 접속할 수 있습니다. SSO 강제 옵션이 켜져 있으면 ID 공급자를 통해 로그인하도록 리디렉션됩니다.

엔터프라이즈 사용자의 자동 아이덴티티 연결#

엔터프라이즈 사용자가 그룹에서 제거된 뒤 다시 돌아오면 자신의 엔터프라이즈 SSO 계정으로 로그인할 수 있습니다. ID 공급자에 등록된 사용자의 이메일 주소가 기존 GitLab 계정의 이메일 주소와 동일하게 유지되는 한, SSO 아이덴티티가 해당 계정에 자동으로 연결되고 사용자는 문제없이 로그인할 수 있습니다. 이 동작은 엔터프라이즈 사용자로 확정되었으나 아직 그룹에 로그인하지 않은 기존 사용자에게도 적용됩니다.

SAML로 GitLab.com에 로그인#

1. ID 공급자에 로그인합니다.
2. 앱 목록에서 "GitLab.com" 앱을 선택합니다. (이 이름은 ID 공급자의 관리자가 지정합니다.)
3. 그러면 GitLab.com에 로그인되고 그룹으로 리디렉션됩니다.

사용자 SAML 아이덴티티 관리#

GitLab.com은 SAML NameID로 사용자를 식별합니다. NameID는 다음과 같습니다.

• SAML 응답의 필수 필드입니다.
• 대소문자를 구분하지 않습니다.

NameID는 다음 조건을 충족해야 합니다.

• 사용자마다 고유해야 합니다.
• 무작위로 생성된 고유 사용자 ID처럼 절대 변하지 않는 영구 값이어야 합니다.
• 이후 로그인 시도에서도 정확히 일치해야 하므로, 대문자와 소문자가 바뀔 수 있는 사용자 입력에 의존해서는 안 됩니다.

NameID는 다음 이유로 이메일 주소나 사용자 이름이 아니어야 합니다.

• 이메일 주소와 사용자 이름은 시간이 지나면서 바뀔 가능성이 더 큽니다. 예를 들어 사람의 이름이 바뀌는 경우가 그렇습니다.
• 이메일 주소는 대소문자를 구분하지 않으므로 사용자가 로그인하지 못하는 결과로 이어질 수 있습니다.

이메일처럼 다른 형식이 필요한 필드를 사용하는 경우가 아니라면 NameID 형식은 Persistent여야 합니다. Transient를 제외한 어떤 형식이든 사용할 수 있습니다.

사용자 NameID 변경#

그룹 Owner는 SAML API로 그룹 멤버의 NameID를 변경하고 SAML 아이덴티티를 갱신할 수 있습니다.

SCIM이 구성되어 있으면 그룹 Owner는 SCIM API로 SCIM 아이덴티티를 갱신할 수 있습니다.

또는 사용자에게 SAML 계정을 다시 연결하도록 요청합니다.

1. 해당 사용자에게 그룹에서 계정 연결을 해제하도록 요청합니다.
2. 해당 사용자에게 새 SAML 앱에 계정을 연결하도록 요청합니다.

특정 ID 공급자에 권장되는 값과 형식에 관한 자세한 내용은 ID 공급자 설정을 참고합니다.

SAML 응답에서 엔터프라이즈 사용자 설정 구성#

GitLab에서는 SAML 응답의 값을 기준으로 특정 사용자 속성을 설정할 수 있습니다. 기존 사용자가 그룹의 엔터프라이즈 사용자라면 그 사용자의 속성이 SAML 응답 값으로 갱신됩니다.

지원되는 사용자 속성#

• can_create_group - 엔터프라이즈 사용자가 새 최상위 그룹을 만들 수 있는지를 나타내는 true 또는 false입니다. 기본값은 true입니다.
• projects_limit - 엔터프라이즈 사용자가 만들 수 있는 개인 프로젝트의 총 개수입니다. 값이 0이면 사용자가 자신의 개인 네임스페이스에 새 프로젝트를 만들 수 없습니다. 기본값은 100000입니다.
• SessionNotOnOrAfter - 사용자 SAML 세션을 종료할 시점을 나타내는 ISO 8601 타임스탬프 값입니다.

SAML 응답 예시#

SAML 응답은 브라우저의 개발자 도구나 콘솔에서 base64로 인코딩된 형태로 확인할 수 있습니다. 원하는 base64 디코딩 도구로 정보를 XML로 변환합니다. SAML 응답 예시는 다음과 같습니다.

   <saml2:AttributeStatement>
      <saml2:Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
         <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">user.email</saml2:AttributeValue>
      </saml2:Attribute>
      <saml2:Attribute Name="username" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
        <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">user.nickName</saml2:AttributeValue>
      </saml2:Attribute>
      <saml2:Attribute Name="first_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
         <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">user.firstName</saml2:AttributeValue>
      </saml2:Attribute>
      <saml2:Attribute Name="last_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
         <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">user.lastName</saml2:AttributeValue>
      </saml2:Attribute>
      <saml2:Attribute Name="can_create_group" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
         <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">true</saml2:AttributeValue>
      </saml2:Attribute>
      <saml2:Attribute Name="projects_limit" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
         <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">10</saml2:AttributeValue>
      </saml2:Attribute>
   </saml2:AttributeStatement>

SAML 세션 타임아웃 사용자 지정#

히스토리

• GitLab 18.2에서 saml_timeout_supplied_by_idp_override라는 이름의 기능 플래그와 함께 도입되었습니다.

기본적으로 GitLab은 24시간 뒤에 SAML 세션을 종료합니다. 이 기간은 SAML2 AuthnStatement의 SessionNotOnOrAfter 속성으로 사용자 지정할 수 있습니다. 이 속성에는 사용자 세션을 종료할 시점을 나타내는 ISO 8601 타임스탬프 값이 들어갑니다. 이 값을 지정하면 기본 SAML 세션 타임아웃 24시간을 재정의합니다.

기본적으로 GitLab은 7일(10080분) 동안 활동이 없으면 세션을 종료합니다. SessionNotOnOrAfter 타임스탬프가 이 시점보다 뒤라면 세션이 종료될 때 사용자가 다시 인증해야 합니다.

응답 예시#

   <saml:AuthnStatement SessionIndex="WDE5aBYjNEj_9IjCFiK0E1YelZT" SessionNotOnOrAfter="2025-08-25T01:23:45.067Z" AuthnInstant="2025-08-24T13:23:45.067Z">
      <saml:AuthnContext>
         <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified</saml:AuthnContextClassRef>
      </saml:AuthnContext>
   </saml:AuthnStatement>

확인된 도메인으로 사용자 이메일 확인 우회#

기본적으로 SAML이나 SCIM으로 프로비저닝된 사용자에게는 본인 확인을 위한 확인 이메일이 전송됩니다. 그 대신 사용자 지정 도메인으로 GitLab을 구성하면 GitLab이 사용자 계정을 자동으로 확인합니다. 사용자는 여전히 엔터프라이즈 사용자 환영 이메일을 받습니다. 다음 두 조건이 모두 참이면 확인 절차를 건너뜁니다.

• 사용자가 SAML이나 SCIM으로 프로비저닝되었습니다.
• 사용자의 이메일 주소가 확인된 도메인에 속합니다.

엔터프라이즈 사용자의 비밀번호 및 패스키 인증 비활성화#

히스토리

• GitLab 17.4에서 도입되었습니다.

사전 요구 사항:

• 엔터프라이즈 사용자가 속한 그룹에 대해 Owner 권한이 있어야 합니다.
• 그룹 SSO가 활성화되어 있어야 합니다.

그룹의 모든 엔터프라이즈 사용자에 대해 비밀번호 인증을 비활성화할 수 있습니다. 이는 그룹의 관리자인 엔터프라이즈 사용자에게도 적용됩니다. 이 설정을 구성하면 엔터프라이즈 사용자는 비밀번호를 변경·재설정하거나 비밀번호로 인증할 수 없습니다. 이러한 사용자는 대신 다음으로 인증할 수 있습니다.

• GitLab 웹 UI에는 그룹 SAML IdP.
• GitLab API와 HTTP 기본 인증을 사용하는 Git에는 개인 액세스 토큰. 다만 그룹에서 엔터프라이즈 사용자의 개인 액세스 토큰을 비활성화한 경우는 예외입니다.

엔터프라이즈 사용자의 비밀번호 및 패스키 인증을 비활성화하려면 다음과 같이 합니다.

1. 상단 바에서 Search or go to를 선택하고 그룹을 찾습니다.
2. 왼쪽 사이드바에서 Settings > SAML SSO를 선택합니다.
3. Configuration 아래에서 Disable password and passkey authentication for enterprise users를 선택합니다.
4. Save changes를 선택합니다.

사용자 액세스 차단#

SAML SSO만 구성되어 있을 때 사용자의 그룹 액세스를 회수하려면 다음 중 하나를 수행합니다.

• 다음에서 (순서대로) 사용자를 제거합니다.
  1. ID 공급자의 사용자 데이터 저장소 또는 특정 앱의 사용자 목록.
  2. GitLab.com 그룹.
• 그룹의 최상위에서 기본 권한을 최소 액세스로 설정한 그룹 동기화를 사용해 그룹의 모든 리소스에 대한 액세스를 자동으로 차단합니다.

SCIM도 함께 사용할 때 사용자의 그룹 액세스를 회수하는 방법은 액세스 제거를 참고합니다.

계정 연결 해제#

사용자는 자신의 프로필 페이지에서 그룹의 SAML 연결을 해제할 수 있습니다. 다음과 같은 경우에 유용합니다.

• 더 이상 특정 그룹이 GitLab.com 로그인을 처리하지 않게 하려는 경우.
• SAML NameID가 변경되어 GitLab이 사용자를 더 이상 찾을 수 없는 경우.

그룹에는 최소 한 명의 Owner가 필요합니다. 그룹에서 자신의 계정이 유일한 Owner라면 계정 연결을 해제할 수 없습니다. 이 경우 다른 사용자를 그룹 Owner로 설정한 뒤 계정 연결을 해제할 수 있습니다.

예를 들어 MyOrg 계정의 연결을 해제하려면 다음과 같이 합니다.

1. 오른쪽 상단에서 자신의 아바타를 선택합니다.
2. Edit profile을 선택합니다.
3. 왼쪽 사이드바에서 Access > Password and authentication을 선택합니다.
4. Service sign-in 섹션에서 연결된 계정 옆의 Disconnect를 선택합니다.

SSO 적용#

GitLab.com에서 SSO는 다음과 같이 적용됩니다.

• SAML SSO가 활성화된 경우.
• 기존 SAML 아이덴티티가 있는 사용자가 조직의 그룹 계층에 있는 그룹과 프로젝트에 액세스하는 경우. 사용자는 GitLab.com 자격 증명으로 SAML SSO를 통해 로그인하지 않고도 조직 밖의 다른 그룹과 프로젝트, 그리고 자신의 사용자 설정을 볼 수 있습니다.

다음 중 하나 이상이 참이면 사용자에게 SAML 아이덴티티가 있습니다.

• GitLab 그룹의 단일 로그인 URL로 GitLab에 로그인한 적이 있습니다.
• SCIM으로 프로비저닝되었습니다.

사용자는 방문할 때마다 SSO로 로그인하라는 요청을 받지는 않습니다. GitLab은 사용자가 SSO로 인증했는지 확인합니다. 마지막 로그인이 24시간을 넘었으면 GitLab은 SSO로 다시 로그인하라고 요청합니다.

SSO는 다음과 같이 적용됩니다.

웹 활동 SSO 전용 적용#

Enforce SSO-only authentication for web activity for this group 옵션이 활성화되면 다음과 같습니다.

• 모든 멤버는 기존 SAML 아이덴티티가 있는지와 무관하게 그룹 리소스에 액세스하려면 GitLab 그룹의 단일 로그인 URL로 GitLab에 접속해야 합니다.
• 사용자가 조직의 그룹 계층에 있는 그룹과 프로젝트에 액세스할 때 SSO가 적용됩니다. 사용자는 SAML SSO를 통해 로그인하지 않고도 조직 밖의 다른 그룹과 프로젝트를 볼 수 있습니다.
• 사용자를 새 멤버로 수동으로 추가할 수 없습니다.
• Owner 권한이 있는 사용자는 표준 로그인 절차로 최상위 그룹 설정에 필요한 변경을 수행할 수 있습니다.
• 비멤버 또는 로그인하지 않은 사용자의 경우:
  • 공개 그룹 리소스에 액세스할 때는 SSO가 적용되지 않습니다.
  • 비공개 그룹 리소스에 액세스할 때는 SSO가 적용됩니다.
• 조직의 그룹 계층에 있는 항목에 대해 대시보드 가시성은 다음과 같습니다.
  • 할 일 목록을 볼 때 SSO가 적용됩니다. SSO 세션이 만료되면 할 일 항목이 가려지고 알림이 표시됩니다.
  • 자신에게 할당된 이슈 목록을 볼 때 SSO가 적용됩니다. SSO 세션이 만료되면 이슈가 숨겨집니다. 이슈 414475는 이슈가 보이도록 이 동작을 변경할 것을 제안합니다.
  • 자신이 담당자 또는 리뷰어인 머지 리퀘스트를 볼 때는 SSO가 적용되지 않습니다. SSO 세션이 만료되어도 머지 리퀘스트를 볼 수 있습니다.
  • Guest, Planner, Reporter, Developer, Maintainer, Owner 권한이 있는 비공개 프로젝트의 스니펫을 볼 때는 SSO가 적용되지 않습니다.

웹 활동 SSO 적용을 활성화하면 다음과 같은 영향이 있습니다.

• 그룹의 경우 프로젝트를 포크했더라도 최상위 그룹 밖으로 그룹 내 프로젝트를 공유할 수 없습니다.
• CI/CD job에서 시작된 Git 활동에는 SSO 확인이 적용되지 않습니다.
• 일반 사용자에 연결되지 않은 자격 증명(예: 프로젝트 및 그룹 액세스 토큰, 서비스 계정, 배포 키)에는 SSO 확인이 적용되지 않습니다.
• 사용자는 Dependency Proxy로 이미지를 풀하기 전에 SSO로 로그인해야 합니다.
• Enforce SSO-only authentication for Git and Dependency Proxy activity for this group 옵션이 활성화되면 Git 활동이 포함된 모든 API 엔드포인트가 SSO 적용 대상입니다. 예를 들어 브랜치, 커밋, 태그를 만들거나 삭제하는 경우가 그렇습니다. SSH와 HTTPS를 통한 Git 활동의 경우, 사용자는 GitLab 리포지터리에 푸시하거나 풀하기 전에 SSO로 로그인한 활성 세션이 최소 하나 있어야 합니다. 이 활성 세션은 다른 장치에 있어도 됩니다.

웹 활동 SSO가 적용되면 SSO를 사용하지 않는 그룹 멤버가 즉시 액세스를 잃는 것은 아닙니다. 해당 사용자가

• 활성 세션이 있으면 ID 공급자 세션이 만료될 때까지 최대 24시간 동안 그룹에 계속 액세스할 수 있습니다.
• 로그아웃된 상태라면 ID 공급자에서 제거된 뒤에는 그룹에 액세스할 수 없습니다.

SSO 적용 시 리포지터리 미러링#

Enforce SSO-only authentication for Git and Dependency Proxy activity for this group을 활성화하면 리포지터리 미러링이 SSO 세션 요구 사항의 대상이 됩니다. 자세한 내용은 SSO 적용 시 풀 미러링을 참고합니다.

새 ID 공급자로 마이그레이션#

새 ID 공급자로 마이그레이션하려면 SAML API로 모든 그룹 멤버의 아이덴티티를 갱신합니다.

예를 들면 다음과 같습니다.

1. 그 시간에 활동 중인 사용자가 없도록 유지 관리 시간대를 설정합니다.
2. SAML API로 각 사용자의 아이덴티티를 갱신합니다.
3. 새 ID 공급자를 구성합니다.
4. 로그인이 동작하는지 테스트합니다.

[!NOTE] 엔터프라이즈 사용자가 아닌 사용자는 아이덴티티가 갱신된 뒤 SAML 비밀번호를 재설정하고 SAML을 계정에 다시 연결해야 합니다.

관련 주제#

• GitLab Self-Managed용 SAML SSO
• 용어집
• 블로그 게시물: GitLab.com에서 SAML과 SSO를 활성화하는 최종 가이드
• GitLab.com과 GitLab Self-Managed의 인증 비교
• 통합 인증으로 생성된 사용자의 비밀번호
• SAML 그룹 동기화

문제 해결#

GitLab과 ID 공급자 사이의 서로 다른 SAML 용어를 맞추기 어렵다면 다음과 같이 합니다.

1. ID 공급자의 문서를 확인합니다. 그들이 사용하는 용어에 관한 정보는 예시 SAML 구성에서 확인합니다.
2. GitLab Self-Managed용 SAML SSO 문서를 확인합니다. GitLab Self-Managed SAML 구성 파일은 GitLab.com 파일보다 더 많은 옵션을 지원합니다. GitLab Self-Managed 인스턴스 파일에 관한 정보는 다음에서 확인할 수 있습니다.
   • 외부 OmniAuth SAML 문서.
   • ruby-saml 라이브러리.
3. 공급자의 XML 응답을 내부 테스트에 사용하는 예시 XML과 비교합니다.

그 밖의 문제 해결 정보는 SAML 문제 해결 가이드를 참고합니다.