이중 인증(2FA)은 GitLab 계정에 보안 계층을 하나 더 제공합니다. 다른 사람이 계정에 접근하려면 사용자 이름과 비밀번호는 물론 두 번째 인증 수단에도 접근할 수 있어야 합니다.

GitLab은 다음 2FA 방식을 지원합니다.

• 패스키. 로그인할 때 GitLab은 패스키로 인증하도록 요청합니다. 2FA를 켜면 패스키가 추가 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. 인증기에서 생성된 여섯 자리 PIN을 입력합니다.
   3. Register with two-factor app을 선택합니다.

올바른 PIN을 입력하면 GitLab은 복구 코드 목록을 표시합니다. 이 코드를 내려받아 안전한 곳에 보관합니다.

사용 중인 OTP 인증기가 클라우드 백업을 지원하면 지금 해당 기능을 구성하는 방안을 고려합니다. 자세한 내용은 사용 중인 인증기의 문서를 참고합니다.

WebAuthn 장치 등록#

히스토리

• WebAuthn 장치의 선택적 일회용 비밀번호 인증이 GitLab 15.10에서 webauthn_without_totp 기능 플래그와 함께 도입되었습니다.
• 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 활성화#

히스토리

• GitLab 18.7에서 email_based_mfa 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
• GitLab 18.7에서 GitLab.com에 활성화되었으며, 2026년에 걸쳐 모든 사용자에게 점진적으로 배포됩니다.
• 새 애플리케이션 설정 email_otp_enabled가 GitLab 19.1에서 도입되었습니다. 기본적으로 비활성화되어 있습니다.
• 기능 플래그 email_based_mfa가 GitLab 19.2에서 제거되었습니다. 이제 이메일 OTP는 email_otp_enabled 애플리케이션 설정으로 제어합니다.

이메일 OTP를 사용하면 여섯 자리 확인 코드를 이메일 주소로 보내 본인 인증을 할 수 있습니다.

사전 요구 사항:

• 인스턴스에서 이메일 OTP가 활성화되어 있어야 합니다.

계정에 이메일 OTP를 활성화하려면 다음 단계를 수행합니다.

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

Cisco Duo 인증기 추가#

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

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'] = true
    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에서 FortiAuthenticator를 OTP 공급자로 사용할 수 있습니다. 사용자는 다음 조건을 충족해야 합니다.

• 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에서 FortiToken Cloud를 OTP 공급자로 사용할 수 있습니다. 사용자는 다음 조건을 충족해야 합니다.

• 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 인증기로 로그인#

Enter authenticator app code 화면에서 OTP 인증기가 생성한 여섯 자리 코드를 입력한 다음 Verify code를 선택합니다.

복구 코드로 로그인하려면 Recover your account를 선택한 다음 Enter account recovery code 화면에서 복구 코드를 입력합니다.

WebAuthn 장치로 로그인#

Verify with security device 화면에서 브라우저나 비밀번호 관리자가 WebAuthn 장치를 활성화하라는 안내(예: 장치를 터치하거나 버튼을 누르는 동작)를 표시합니다. 장치가 인증 요청에 응답하면 로그인됩니다.

장치가 응답하지 않으면 Try again을 선택합니다.

이메일 OTP로 로그인#

Authenticate with your email 화면에서 GitLab이 이메일로 여섯 자리 확인 코드를 보냅니다. 코드를 입력한 다음 Verify code를 선택합니다. 이 코드는 60분 동안 유효합니다.

코드가 도착하지 않았거나 만료되었다면 Resend code를 선택하여 새 코드를 요청합니다. 그 밖의 문제는 이메일 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를 선택합니다.

그룹 설정이나 인스턴스 설정에 따라 계정에 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를 사용하든 모두 유용합니다.

Git for Windows에는 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가 계속 동작하는지 확인합니다.

• 2FA가 OTP 서버에서 올바르게 인가되도록 NTP 같은 서비스로 GitLab 서버의 시간을 동기화합니다. 그렇게 하지 않으면 시간 차이 때문에 인가가 항상 실패할 수 있습니다.

• GitLab WebAuthn 구현은 GitLab 인스턴스에 여러 호스트 이름이나 FQDN으로 접근할 때는 동작하지 않습니다. 각 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를 강제하는 방법은 이중 인증 강제를 참고합니다.