이중 인증

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed

이중 인증(2FA)은 GitLab 계정에 추가적인 보안 수준을 제공합니다. 다른 사람이 귀하의 계정에 접근하려면 사용자 이름과 암호 그리고 두 번째 인증 요소에 대한 액세스 권한이 필요합니다.

GitLab은 다음과 같은 두 번째 인증 요소를 지원합니다.

  • 시간 기반 일회용 비밀번호(TOTP). 활성화된 경우, GitLab은 로그인할 때 코드를 요청합니다. 코드는 일회용 비밀번호 인증기(예: 기기 중 하나의 암호 관리자)에서 생성됩니다.
  • WebAuthn 기기. 사용자 이름과 암호를 제공하면 WebAuthn 장치를 활성화하라는 메시지가 표시됩니다(일반적으로 버튼을 눌러야 함). 이를 통해 안전한 인증이 수행됩니다.

장치를 설정하면 장치를 분실해도 계정에 여전히 액세스할 수 있도록 TOTP도 설정하세요.

이중 인증과 개인 액세스 토큰 사용

2FA를 활성화하면 HTTPS를 통한 Git 또는 GitLab API로의 암호 사용이 불가능합니다. 대신 개인 액세스 토큰을 사용해야 합니다.

OAuth 자격 증명 도우미

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

Git 자격 증명 관리자

Git 자격 증명 관리자 (GCM)는 기본적으로 OAuth를 사용하여 인증합니다. GCM은 매뉴얼 구성 없이 GitLab.com을 지원합니다. Self-managed GitLab에서 GCM을 사용하려면 GitLab 지원을 참조하세요.

푸시할 때마다 다시 인증해야 하는 상황을 피하기 위해 GCM은 세션 간 유지되는 캐시뿐만 아니라 다양한 플랫폼별 자격 증명 리포지터리도 지원합니다. 이 기능은 개인 액세스 토큰 또는 OAuth를 사용하더라도 유용합니다.

Git for Windows에는 Git 자격 증명 관리자가 포함되어 있습니다.

Git 자격 증명 관리자는 주로 GitHub, Inc.에서 개발되었으며 커뮤니티의 지원을 받고 있는 오픈 소스 프로젝트입니다.

git-credential-oauth

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

많은 리눅스 배포판에는 git-credential-oauth가 패키지로 포함되어 있습니다.

git-credential-oauth는 커뮤니티의 지원을 받고 있는 오픈 소스 프로젝트입니다.

이중 인증 활성화

다음을 사용하여 2FA를 활성화할 수 있습니다:

  • 일회용 비밀번호 인증기. 2FA를 활성화한 후 복구 코드를 백업하세요.
  • WebAuthn 장치.

GitLab 14.3 이상에서 2FA를 활성화하려면 계정 이메일을 확인해야 합니다.

일회용 비밀번호 활성화

2FA를 일회용 비밀번호로 활성화하려면:

  1. GitLab에서:
    1. 사용자 설정에 액세스하세요.
    2. 계정을 선택하세요.
    3. 이중 인증 활성화를 선택하세요.
  2. 기기(보통 핸드폰)에서:
    1. 호환되는 애플리케이션을 설치하세요. 예:
    2. 애플리케이션에 새로운 항목을 추가하는 방법 중 하나로:
      • GitLab이 표시한 코드를 기기 카메라로 스캔하여 항목을 자동으로 추가합니다.
      • 제공된 세부 정보를 입력하여 직접 항목을 추가합니다.
  3. GitLab에서:
    1. 기기의 항목에서 생성된 여섯 자리 핀 번호를 핀 코드에 입력하세요.
    2. 현재 암호를 입력하세요.
    3. 제출을 선택하세요.

올바른 핀을 입력하면 GitLab이 복구 코드 디렉터리을 표시합니다. 이를 다운로드하여 안전한 곳에 보관하세요.

FortiAuthenticator를 사용한 일회용 비밀번호 활성화

플래그: Self-managed GitLab에서는 기본적으로 이 기능을 사용할 수 없습니다. 사용자별로 사용할 수 있도록 하려면 관리자가 forti_authenticator 플래그를 활성화해야 합니다. GitLab.com 및 GitLab Dedicated에서는 이 기능을 사용할 수 없습니다.

GitLab에서 FortiAuthenticator를 일회용 비밀번호 (OTP) 제공자로 사용할 수 있습니다. 사용자는:

  • FortiAuthenticator와 동일한 사용자 이름으로 GitLab 및 FortiAuthenticator에 존재해야 합니다.
  • FortiAuthenticator에서 FortiToken을 구성해야 합니다.

FortiAuthenticator의 사용자 이름과 액세스 토큰이 필요합니다. 아래 access_token은 FortAuthenticator 액세스 키입니다. 토큰을 얻으려면 일치하는 사용자의 REST API 해결 방법을 참조하세요. GitLab 13.5는 FortAuthenticator 버전 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 패키지 설치) 또는 재시작(자체 컴파일된 설치)합니다.

Cisco Duo를 사용하여 일회용 비밀번호(OTP) 활성화

Self-managed GitLab의 경우, 기본적으로 이 기능을 사용할 수 있습니다. 그러나 GitLab.com에서는 이 기능을 사용할 수 없습니다.

GitLab에서 Cisco Duo를 일회용 비밀번호(OTP) 제공자로 사용할 수 있습니다.

DUO®는 Cisco Systems, Inc. 또는 미국 및 특정 다른 국가의 제휴사의 등록 상표입니다.

사전 요구 사항

Cisco Duo를 OTP 제공자로 사용하려면:

  • 계정이 Cisco Duo 및 GitLab 양쪽에 동일한 사용자 이름으로 존재해야 합니다.
  • Cisco Duo를 구성하고 통합 키, 비밀 키 및 API 호스트 이름을 가져야 합니다.

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

GitLab 15.10은 Cisco Duo 버전 D261.14와 테스트되었습니다.

GitLab에서 Cisco Duo 구성

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['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을 다시 시작합니다.

FortiToken Cloud를 사용하여 일회용 비밀번호(OTP) 활성화

Offering: Self-managed
  • GiLab 13.7에서 forti_token_cloud라는 플래그로 소개되었습니다. 기본적으로 비활성화됨.
Self-managed GitLab의 경우, 기본적으로 이 기능을 사용할 수 없습니다. 사용자별로 사용 가능하게 하려면 관리자가 forti_token_cloud라는 피처 플래그를 활성화할 수 있습니다. 그러나 GitLab.com 및 GitLab Dedicated에서 이 기능을 사용할 수 없습니다. 이 기능은 프로덕션 환경에 사용하기에 적합하지 않습니다.

GitLab에서 FortiToken Cloud를 일회용 비밀번호(OTP) 제공자로 사용할 수 있습니다. 사용자는 다음을 준수해야 합니다:

  • 동일한 사용자 이름으로 FortiToken Cloud 및 GitLab 양쪽에 존재해야 합니다.
  • FortiToken이 FortiToken Cloud에서 구성되어 있어야 합니다.

FortiToken Cloud를 구성하려면 client_id와 client_secret이 필요합니다. 이 정보를 얻으려면 Fortinet 문서 라이브러리의 REST API 가이드를 참조하십시오.

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 패키지 설치) 또는 다시 시작합니다(자체 컴파일 설치).

WebAuthn 장치 설정

Self-managed GitLab의 경우, 기본적으로 WebAuthn 장치를 사용할 수 있습니다. 이 기능을 비활성화하려면 관리자가 webauthn이라는 피처 플래그를 비활성화할 수 있습니다. WebAuthn 장치가 등록된 후 WebAuthn 피처 플래그를 비활성화하면 해당 장치를 다시 활성화하기 전까지 사용할 수 없습니다. GitLab.com에서는 WebAuthn 장치를 사용할 수 있습니다.
Self-managed GitLab의 경우, 기본적으로 WebAuthn 장치의 선택적 일회용 비밀번호 인증은 사용할 수 없습니다. 이 기능을 사용하려면 관리자가 webauthn_without_totp이라는 피처 플래그를 활성화할 수 있습니다. GitLab.com에서는 이 기능을 사용할 수 있습니다. 그러나 GitLab Dedicated에서는 이 기능을 사용할 수 없습니다.

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

  • 데스크톱 브라우저:
    • Chrome
    • Edge
    • Firefox
    • Opera
    • Safari
  • 모바일 브라우저:
    • Android용 Chrome
    • Android용 Firefox
    • iOS Safari (iOS 13.3부터)

WebAuthn 호환 장치로 2FA를 설정하려면:

  1. 선택 사항입니다. 일회용 비밀번호를 설정.
  2. 사용자 설정에 액세스합니다.
  3. 계정을 선택합니다.
  4. 이중 인증 활성화를 선택합니다.
  5. WebAuthn 장치를 연결합니다.
  6. 장치 이름을 입력하고 GitLab 15.10 이후에는 GitLab 계정 암호를 입력합니다. 신원 제공자를 통해 로그인한 경우 이 암호를 입력할 필요가 없을 수 있습니다.
  7. 새로운 WebAuthn 장치 설정을 선택합니다.
  8. 장치에 따라 버튼을 누르거나 센서를 터치해야 할 수 있습니다.

장치 설정에 성공했다는 메시지를 받아야 합니다.

WebAuthn 호환 장치로 2FA를 설정한 경우, 해당 장치는 특정 컴퓨터의 특정 브라우저에 연결됩니다. 브라우저 및 WebAuthn 장치에 따라 해당 장치를 다른 브라우저 또는 컴퓨터에서 사용할 수 있도록 설정할 수 있습니다.

처음으로 2FA를 설정한 경우에는 계정 액세스를 복구할 수 있도록 복구 코드를 다운로드해야 합니다.

caution
브라우저 데이터를 지우면 계정에 액세스할 수 없게 될 수 있습니다.

복구 코드

  • 소개됨 : GitLab 13.7에서는 코드 복사 및 코드 인쇄 버튼.

일회용 비밀번호로 2단계 인증을 성공적으로 활성화한 후에는 생성된 복구 코드 세트를 다운로드하라는 프롬프트가 표시됩니다. 일회용 비밀번호 인증기에 액세스할 수 없게 되는 경우 이러한 복구 코드 중 하나를 사용하여 계정에 로그인할 수 있습니다.

caution
각 코드는 계정에 한 번만 사용할 수 있습니다.

코드를 복사하고 인쇄하거나 안전한 위치에 저장하기 위해 코드 다운로드를 사용하세요. 파일은 gitlab-recovery-codes.txt로 저장됩니다.

note
복구 코드는 WebAuthn 장치에 대해 생성되지 않습니다.

복구 코드를 분실한 경우 또는 새 코드를 생성하려는 경우 다음 중 하나를 사용할 수 있습니다:

2단계 인증 복구 코드 재생성

2단계 인증(2FA) 복구 코드를 다시 생성하려면 데스크톱 브라우저에 액세스해야 합니다:

  1. 사용자 설정에 액세스하세요.
  2. 계정 > 2단계 인증 (2FA)을 선택하세요.
  3. 이미 2FA를 구성했다면 2단계 인증 관리를 선택하세요.
  4. 2단계 인증기 등록 패널에서 현재 암호를 입력하고 복구 코드 재생성을 선택하세요.
note
2FA 복구 코드를 재생성하면 저장해야 합니다. 이전에 생성된 2FA 코드를 사용할 수 없습니다.

2단계 인증으로 로그인

2FA로 로그인하는 것은 일반적인 로그인 프로세스와 약간 다릅니다. 사용자 이름과 암호를 입력한 후에는 활성화한 2FA 유형에 따라 두 번째 프롬프트가 표시됩니다.

일회용 비밀번호 사용하여 로그인

요청된 경우, 일회용 비밀번호 인증기 응용 프로그램의 핀 또는 복구 코드를 입력하여 로그인하십시오.

WebAuthn 장치 사용하여 로그인

지원되는 브라우저에서는 자격 증명을 입력한 후 자동으로 WebAuthn 장치를 활성화하라는 프롬프트가 표시됩니다(예: 터치 또는 버튼을 누름). 장치가 인증 요청에 응답한 메시지가 나타나고 자동으로 로그인됩니다.

2단계 인증 해제

2FA를 해제하려면:

  1. 사용자 설정에 액세스하세요.
  2. 계정을 선택하세요.
  3. 2단계 인증 관리를 선택하세요.
  4. 2단계 인증 해제를 선택하기 전에 2단계 인증기 등록 아래에서 현재 암호를 입력하세요.

이렇게 하면 모바일 응용 프로그램 및 WebAuthn 장치를 포함한 모든 2FA 등록이 지워집니다.

복구 옵션

코드 생성 장치에 액세스할 수 없는 경우 다음을 사용하여 계정에 액세스를 복구할 수 있습니다:

저장된 복구 코드 사용

복구 코드를 사용하려면:

  1. GitLab 로그인 페이지에서 사용자 이름 또는 이메일 및 암호를 입력하세요.
  2. 두 번째 요소 코드를 요청받은 경우, 복구 코드를 입력하세요.

복구 코드를 사용한 후에는 재사용할 수 없습니다. 여전히 다른 복구 코드를 사용할 수 있습니다.

SSH를 사용하여 새 복구 코드 생성

2FA를 활성화할 때 복구 코드를 저장하는 것을 잊었거나 GitLab 계정에 SSH 키를 추가한 경우 SSH를 사용하여 새로운 복구 코드 세트를 생성할 수 있습니다:

  1. 터미널에서 다음을 실행합니다: 

    ssh git@gitlab.com 2fa_recovery_codes

    Self-managed 인스턴스의 경우 위 명령어에서 gitlab.com을 GitLab 서버 호스트 이름(gitlab.example.com)으로 바꿉니다.

  2. 새 코드를 생성하려는지 확인하라는 프롬프트가 표시됩니다. 이 프로세스는 이전에 저장한 코드를 무효화합니다. 예를 들어: 

    새로운 2단계 복구 코드를 생성하시겠습니까?
이전에 저장한 복구 코드는 무효화됩니다. (예/아니요)
   
예
   
귀하의 2단계 인증 복구 코드는:
   
119135e5a3ebce8e
11f6v2a498810dcd
3924c7ab2089c902
e79a3398bfe4f224
34bd7b74adbc8861
f061691d5107df1a
169bf32a18e63e7f
b510e7422e81c947
20dbed24c5e74663
df9d3b9403b9c9f0
   
로그인 중에 위 코드 중 하나를 사용하여 2단계 코드를 요청받은 후
자신의 프로필 설정으로 이동하여 새로운 장치를 추가하여 계정에 다시 액세스하는 것을 잊지 마십시오.

  3. GitLab 로그인 페이지로 이동하고 사용자 이름 또는 이메일과 암호를 입력하세요. 2단계 코드를 요청받은 경우 명령줄 출력에서 얻은 복구 코드 중 하나를 입력하세요.

로그인한 후에는 즉시 새로운 장치로 2FA를 설정하세요.

귀하의 계정에서 2단계 인증 비활성화

Tier: Premium, Ultimate Offering: GitLab.com

다른 방법을 사용할 수 없는 경우 GitLab 지원 담당자에게 지원 티켓을 제출하여 계정의 2FA를 비활성화할 것을 요청하십시오:

  • 이 서비스는 GitLab.com 구독을 한 계정에만 제공됩니다. 자세한 내용은 블로그 게시물을 참조하세요.
  • 이 설정을 일시적으로 비활성화하면 계정이 덜 안전한 상태가 됩니다. 가능한 빨리 로그인하여 2단계 인증을 다시 활성화하세요.

GitLab 관리자를 위한 정보

Tier: Free, Premium, Ultimate Offering: Self-managed
  • GitLab 백업을 복원한 후 2FA가 계속 작동하는지 확인하세요.
  • 시간 기반 일회용 비밀번호(TOTP) 서버로 2FA가 올바르게 인가되도록 하려면 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 인증은 first.host.xyz에서만 등록되었기 때문에 실패합니다.
  • 시스템 또는 그룹 수준에서 2FA를 강제로 적용하려면 이 두 요소 인증을 강제로 적용을 참조하세요.

문제 해결

오류: “HTTP 기본: 액세스가 거부되었습니다. 제공된 비밀번호 또는 토큰 …”

요청을 할 때 다음 오류를 받을 수 있습니다: 

HTTP 기본: 액세스가 거부되었습니다. 제공된 비밀번호 또는 토큰이 잘못되었거나 계정에 2FA가 활성화되어 비밀번호 대신 개인 액세스 토큰을 사용해야 합니다.

이 오류는 다음 시나리오에서 발생합니다:

대신 다음을 사용하여 인증할 수 있습니다:

오류: “잘못된 핀 코드”

잘못된 핀 코드 오류를 받으면, 이는 인증 애플리케이션과 GitLab 인스턴스 사이에 시간 동기화 문제가 있을 수 있음을 나타낼 수 있습니다. 시간 동기화 문제를 피하려면 코드를 생성하는 장치에서 시간 동기화를 활성화하십시오. 예를 들어:

  • Android (Google Authenticator)의 경우:
    1. Google Authenticator의 메인 메뉴로 이동합니다.
    2. 설정을 선택합니다.
    3. 코드의 시간 보정을 선택합니다.
    4. 지금 동기화를 선택합니다.
  • iOS의 경우:
    1. 설정으로 이동합니다.
    2. 일반을 선택합니다.
    3. 날짜 및 시간을 선택합니다.
    4. 자동으로 설정을 활성화합니다. 이미 활성화되어 있는 경우 비활성화하고, 몇 초를 기다린 후 다시 활성화합니다.

오류: “권한이 거부되었습니다 (공개 키)” 복구 코드를 다시 생성할 때

SSH 키를 사용하여 새로운 복구 코드를 생성 시 권한이 거부되었습니다 (공개 키) 오류가 발생하고 비정상적인 SSH 키파일 경로를 사용하는 경우, ssh-agent를 사용하여 개인 SSH 키를 매뉴얼으로 등록해야 할 수 있습니다.