이중 인증(2FA)은 GitLab 계정에 추가적인 보안 수준을 제공합니다. 다른 사람이 계정에 접근하려면 사용자명과 비밀번호 외에 두 번째 인증 수단에도 접근해야 합니다.

GitLab은 다음 2FA 방법을 지원합니다:

• 일회용 비밀번호(OTP) 인증기. 로그인 시 GitLab이 OTP 인증기에서 생성된 코드를 요청합니다.
• WebAuthn 장치. 로그인 시 GitLab이 WebAuthn 장치의 소유권을 증명하도록 요청합니다. 일반적으로 YubiKey, 휴대폰 또는 노트북과 같은 물리적 장치입니다.
• 이메일 OTP. 로그인 시 GitLab이 이메일 주소로 전송된 코드를 요청합니다.

장치를 설정한 경우 장치를 분실해도 계정에 접근할 수 있도록 OTP도 설정하세요.

이중 인증 활성화#

2FA를 활성화하려면 이메일 주소를 확인하고 OTP 인증기, WebAuthn 장치 또는 이메일 OTP를 등록합니다.

OTP 인증기 등록#

OTP 인증기를 등록하려면:

1. GitLab을 구성합니다.
   1. 오른쪽 상단 모서리에서 아바타를 선택합니다.
   2. Edit profile을 선택합니다.
   3. 왼쪽 사이드바에서 Access > Password and authentication을 선택합니다.
   4. One-time password authenticator 섹션에서 Register authenticator를 선택합니다. QR 코드와 OTP 세부 정보가 표시됩니다.
2. 장치를 구성합니다.
   1. 장치에 호환 가능한 OTP 애플리케이션을 설치합니다. 예를 들어:
      • 클라우드 기반(하드웨어 장치를 분실해도 접근을 복구할 수 있으므로 권장):
        • Authy.
        • Cisco Duo.
      • 기타(독점):
        • Google Authenticator.
        • Microsoft Authenticator.
      • 기타(무료 소프트웨어)
        • Aegis Authenticator.
        • FreeOTP.
   2. 애플리케이션에서 두 가지 방법 중 하나로 새 항목을 추가합니다:
      • 장치 카메라로 GitLab에 표시된 코드를 스캔하여 항목을 자동으로 추가합니다.
      • 제공된 세부 정보를 입력하여 항목을 수동으로 추가합니다.
3. 등록을 완료합니다:
   1. 현재 비밀번호를 입력합니다.
   2. 인증기에서 생성된 6자리 PIN을 입력합니다.
   3. Register with two-factor app을 선택합니다.

올바른 PIN을 입력하면 GitLab이 복구 코드 목록을 표시합니다. 이를 다운로드하고 안전한 장소에 보관하세요.

OTP 인증기가 클라우드 백업을 지원하는 경우, 지금 해당 기능을 구성하는 것을 고려하세요. 자세한 내용은 특정 인증기에 대한 문서를 참조하세요.

WebAuthn 장치 등록#

히스토리

• WebAuthn 장치에 대한 선택적 일회용 비밀번호 인증이 webauthn_without_totp라는 기능 플래그와 함께 GitLab 15.10에서 도입되었습니다.
• GitLab 17.6에서 일반 공개되었습니다. 기능 플래그 webauthn_without_totp가 제거되었습니다.

WebAuthn은 다음에서 지원됩니다:

• 데스크톱 브라우저:
  • Chrome
  • Edge
  • Firefox
  • Opera
  • Safari
• 모바일 브라우저:
  • Chrome for Android
  • Firefox for Android
  • iOS Safari (iOS 13.3 이상)

WebAuthn 호환 장치를 등록하려면:

1. 물리적 장치를 사용하는 경우 컴퓨터에 연결합니다.
2. 오른쪽 상단 모서리에서 아바타를 선택합니다.
3. Edit profile을 선택합니다.
4. 왼쪽 사이드바에서 Access > Password and authentication을 선택합니다.
5. WebAuthn devices 섹션에서 Register device를 선택합니다.
6. Set up new device를 선택합니다.
7. 브라우저 창의 지시를 따릅니다.
8. 장치에 따라 버튼을 누르거나 센서를 터치해야 할 수 있습니다.
9. GitLab 계정 비밀번호와 장치 이름을 입력합니다. ID 공급자를 통해 로그인한 경우 이 비밀번호를 입력하지 않아도 될 수 있습니다.
10. Register device를 선택합니다.

장치를 성공적으로 설정했다는 메시지가 표시됩니다.

WebAuthn 호환 장치로 2FA를 설정하면 해당 장치는 특정 컴퓨터의 특정 브라우저에 연결됩니다. 브라우저와 WebAuthn 장치에 따라 다른 브라우저나 컴퓨터에서 WebAuthn 장치를 사용하도록 설정을 구성할 수 있습니다.

처음으로 2FA를 설정한 경우 접근 권한을 잃으면 계정을 복구할 수 있도록 복구 코드를 다운로드해야 합니다.

이메일 OTP 활성화#

히스토리

• email_based_mfa라는 기능 플래그와 함께 GitLab 18.7에서 도입되었습니다. 기본적으로 비활성화됩니다.
• GitLab 18.7에서 GitLab.com에서 활성화되었으며, 2026년 내내 모든 사용자에게 점진적으로 롤아웃됩니다.

이메일 OTP를 사용하면 이메일 주소로 6자리 인증 코드를 전송하여 신원을 확인할 수 있습니다.

계정에 이메일 OTP를 활성화하려면:

1. 오른쪽 상단 모서리에서 아바타를 선택합니다.
2. Edit profile을 선택합니다.
3. 왼쪽 사이드바에서 Access > Password and authentication을 선택합니다.
4. Enable email OTP를 선택합니다.
5. 현재 비밀번호를 입력하고 Update email OTP settings를 선택합니다.

Cisco Duo 인증기 추가#

히스토리

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

GitLab에서 OTP 공급자로 Cisco Duo를 사용할 수 있습니다.

DUO®는 미국 및 특정 다른 국가에서 Cisco Systems, Inc. 및/또는 그 계열사의 등록 상표입니다.

사전 요구 사항:

• 두 애플리케이션에서 동일한 사용자명으로 계정이 Cisco Duo와 GitLab 모두에 존재해야 합니다.
• Cisco Duo를 구성했으며 통합 키, 비밀 키 및 API 호스트명이 있어야 합니다.

자세한 내용은 Cisco Duo API 문서를 참조하세요.

1. GitLab 구성 파일을 엽니다.

   Linux 패키지 설치의 경우:

   sudo editor /etc/gitlab/gitlab.rb
   

   자체 컴파일 설치의 경우:

   cd /home/git/gitlab
   sudo -u git -H editor config/gitlab.yml
   

2. 공급자 구성을 추가합니다.

   Linux 패키지 설치의 경우:

    gitlab_rails['duo_auth_enabled'] = false
    gitlab_rails['duo_auth_integration_key'] = '<duo_integration_key_value>'
    gitlab_rails['duo_auth_secret_key'] = '<duo_secret_key_value>'
    gitlab_rails['duo_auth_hostname'] = '<duo_api_hostname>'
   

   자체 컴파일 설치의 경우:

   duo_auth:
     enabled: true
     hostname: <duo_api_hostname>
     integration_key: <duo_integration_key_value>
     secret_key: <duo_secret_key_value>
   

3. 구성 파일을 저장합니다.

4. Linux 패키지 설치의 경우 GitLab을 재구성합니다. 자체 컴파일 설치의 경우 GitLab을 재시작합니다.

FortiAuthenticator 인증기 추가#

GitLab에서 OTP 공급자로 FortiAuthenticator를 사용할 수 있습니다. 사용자는:

• 두 애플리케이션에서 동일한 사용자명으로 FortiAuthenticator와 GitLab 모두에 존재해야 합니다.
• FortiAuthenticator에서 FortiToken이 구성되어 있어야 합니다.

FortiAuthenticator의 사용자명과 액세스 토큰이 필요합니다. 아래의 access_token은 FortiAuthenticator 액세스 키입니다. 토큰을 가져오려면 Fortinet Document Library의 REST API Solution Guide를 참조하세요. FortiAuthenticator 버전 6.2.0으로 테스트되었습니다.

GitLab에서 FortiAuthenticator를 구성합니다. GitLab 서버에서:

1. 구성 파일을 엽니다.

   Linux 패키지 설치의 경우:

   sudo editor /etc/gitlab/gitlab.rb
   

   자체 컴파일 설치의 경우:

   cd /home/git/gitlab
   sudo -u git -H editor config/gitlab.yml
   

2. 공급자 구성을 추가합니다.

   Linux 패키지 설치의 경우:

   gitlab_rails['forti_authenticator_enabled'] = true
   gitlab_rails['forti_authenticator_host'] = 'forti_authenticator.example.com'
   gitlab_rails['forti_authenticator_port'] = 443
   gitlab_rails['forti_authenticator_username'] = '<some_username>'
   gitlab_rails['forti_authenticator_access_token'] = 's3cr3t'
   

   자체 컴파일 설치의 경우:

   forti_authenticator:
     enabled: true
     host: forti_authenticator.example.com
     port: 443
     username: <some_username>
     access_token: s3cr3t
   

3. 구성 파일을 저장합니다.

4. 재구성(Linux 패키지 설치) 또는 재시작(자체 컴파일 설치)합니다.

FortiToken Cloud 인증기 추가#

GitLab에서 OTP 공급자로 FortiToken Cloud를 사용할 수 있습니다. 사용자는:

• 두 애플리케이션에서 동일한 사용자명으로 FortiToken Cloud와 GitLab 모두에 존재해야 합니다.
• FortiToken Cloud에서 FortiToken이 구성되어 있어야 합니다.

FortiToken Cloud를 구성하려면 client_id와 client_secret이 필요합니다. 이를 가져오려면 Fortinet Document Library의 REST API Guide를 참조하세요.

GitLab에서 FortiToken Cloud를 구성합니다. GitLab 서버에서:

1. 구성 파일을 엽니다.

   Linux 패키지 설치의 경우:

   sudo editor /etc/gitlab/gitlab.rb
   

   자체 컴파일 설치의 경우:

   cd /home/git/gitlab
   sudo -u git -H editor config/gitlab.yml
   

2. 공급자 구성을 추가합니다.

   Linux 패키지 설치의 경우:

   gitlab_rails['forti_token_cloud_enabled'] = true
   gitlab_rails['forti_token_cloud_client_id'] = '<your_fortinet_cloud_client_id>'
   gitlab_rails['forti_token_cloud_client_secret'] = '<your_fortinet_cloud_client_secret>'
   

   자체 컴파일 설치의 경우:

   forti_token_cloud:
     enabled: true
     client_id: YOUR_FORTI_TOKEN_CLOUD_CLIENT_ID
     client_secret: YOUR_FORTI_TOKEN_CLOUD_CLIENT_SECRET
   

3. 구성 파일을 저장합니다.

4. 재구성(Linux 패키지 설치) 또는 재시작(자체 컴파일 설치)합니다.

복구 코드#

OTP 인증기로 2FA를 성공적으로 활성화한 직후 생성된 복구 코드 세트를 다운로드하라는 메시지가 표시됩니다. OTP 인증기에 대한 접근 권한을 잃은 경우, 이 복구 코드 중 하나를 사용하여 계정에 로그인할 수 있습니다.

코드를 복사하고 인쇄하거나 Download codes를 사용하여 안전한 장소에 보관하기 위해 다운로드해야 합니다. 다운로드를 선택하면 파일 이름은 gitlab-recovery-codes.txt입니다.

복구 코드 재생성 또는 복원에 대한 정보는 복구 옵션 및 2FA 재설정을 참조하세요.

이중 인증으로 로그인#

2FA가 활성화되면 사용자명과 비밀번호를 입력한 다음 두 번째 인증 방법을 사용하여 신원을 확인합니다. 로그인 프로세스는 등록한 2FA 방법에 따라 약간 다릅니다.

OTP 인증기로 로그인#

메시지가 표시되면 OTP 인증기의 PIN 또는 복구 코드를 입력하여 로그인합니다.

WebAuthn 장치로 로그인#

지원되는 브라우저에서 자격 증명을 입력한 후 WebAuthn 장치를 활성화하라는 메시지가 자동으로 표시됩니다(예: 터치하거나 버튼 누르기).

장치가 인증 요청에 응답했음을 나타내는 메시지가 표시되고 자동으로 로그인됩니다.

이메일 OTP로 로그인#

메시지가 표시되면 이메일로 전송된 6자리 인증 코드를 입력합니다. 코드는 60분 동안 유효합니다.

액세스 코드를 사용할 수 없는 경우 다음을 수행할 수 있습니다:

• 새 코드를 요청합니다. 로그인 페이지에서 Resend code를 선택합니다.
• 다른 확인된 이메일 주소로 코드를 전송합니다. 로그인 페이지에서 Send a code to another address associated with this account를 선택합니다.
• 이메일 OTP 문제 해결을 참조합니다.

개인 액세스 토큰으로 로그인#

2FA가 활성화되면 HTTPS를 통한 Git 또는 GitLab API를 사용하여 비밀번호로 인증할 수 없습니다. 대신 개인 액세스 토큰을 사용해야 합니다.

이중 인증 비활성화#

히스토리

• OTP 인증기와 WebAuthn 장치를 개별적으로 또는 동시에 비활성화하는 기능이 GitLab 17.6에서 도입되었습니다.

OTP 인증기와 WebAuthn 장치를 개별적으로 또는 동시에 비활성화할 수 있습니다. 동시에 비활성화하려면:

1. 오른쪽 상단 모서리에서 아바타를 선택합니다.
2. Edit profile을 선택합니다.
3. 왼쪽 사이드바에서 Access > Password and authentication을 선택합니다.
4. Disable 2FA를 선택합니다.
5. 대화 상자에서 현재 비밀번호를 입력하고 Disable 2FA를 선택합니다.

이렇게 하면 모바일 애플리케이션 및 WebAuthn 장치를 포함한 모든 2FA 등록이 지워집니다.

그룹 또는 인스턴스 설정에 따라 계정에 2FA 사용이 요구될 수 있습니다. GitLab.com에서는 비밀번호 기반 로그인 시 이메일 OTP 인증을 완료해야 합니다.

OAuth 자격 증명 도우미#

다음 Git 자격 증명 도우미는 OAuth를 사용하여 GitLab에 인증합니다. 이는 이중 인증과 호환됩니다. 처음 인증할 때 도우미가 웹 브라우저를 열고 GitLab이 앱을 승인하도록 요청합니다. 이후 인증은 상호작용이 필요하지 않습니다.

Git Credential Manager#

Git Credential Manager(GCM)는 기본적으로 OAuth를 사용하여 인증합니다. GCM은 수동 구성 없이 GitLab.com을 지원합니다. GitLab Self-Managed와 함께 GCM을 사용하려면 GitLab 지원을 참조하세요.

모든 푸시에서 재인증할 필요가 없도록 GCM은 세션 간에 지속되는 캐싱 및 다양한 플랫폼별 자격 증명 저장소를 지원합니다. 이 기능은 개인 액세스 토큰이나 OAuth를 사용하는 경우 모두 유용합니다.

Windows용 Git에는 Git Credential Manager가 포함됩니다.

Git Credential Manager는 주로 GitHub, Inc.가 개발합니다. 오픈 소스 프로젝트이며 커뮤니티가 지원합니다.

git-credential-oauth#

git-credential-oauth는 수동 구성 없이 GitLab.com 및 여러 인기 있는 공개 호스트를 지원합니다. GitLab Self-Managed와 함께 사용하려면 git-credential-oauth 사용자 정의 호스트 문서를 참조하세요.

많은 Linux 배포판에는 패키지로 git-credential-oauth가 포함됩니다.

git-credential-oauth는 커뮤니티가 지원하는 오픈 소스 프로젝트입니다.

GitLab 관리자를 위한 정보#

• GitLab 백업 복원 후 2FA가 계속 작동하도록 주의하세요.

• OTP 서버에서 2FA가 올바르게 인증되도록 하려면 NTP와 같은 서비스를 사용하여 GitLab 서버의 시간을 동기화하세요. 그렇지 않으면 시간 차이로 인해 인증이 항상 실패할 수 있습니다.

• GitLab WebAuthn 구현은 여러 호스트명이나 FQDN에서 GitLab 인스턴스에 접근할 때 작동하지 않습니다. 각 WebAuthn 등록은 등록 시 현재 호스트명과 연결되며, 다른 호스트명이나 FQDN에 사용할 수 없습니다.

  예를 들어, 사용자가 first.host.xyz와 second.host.xyz에서 GitLab 인스턴스에 접근하려는 경우:

  • 사용자가 first.host.xyz를 사용하여 로그인하고 WebAuthn 키를 등록합니다.
  • 사용자가 로그아웃하고 first.host.xyz를 사용하여 로그인을 시도하면 WebAuthn 인증이 성공합니다.
  • 사용자가 로그아웃하고 second.host.xyz를 사용하여 로그인을 시도하면 WebAuthn 인증이 실패합니다. WebAuthn 키가 first.host.xyz에만 등록되어 있기 때문입니다.

• 시스템 또는 그룹 수준에서 2FA를 적용하려면 이중 인증 적용을 참조하세요.