이중 인증

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를 사용하더라도 이 기능이 유용합니다.

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

Git 자격 증명 관리자는 주로 GitHub, Inc.에서 개발되었습니다. 이는 오픈 소스 프로젝트이며 커뮤니티에 의해 지원됩니다.

git-credential-oauth

git-credential-oauth는 매뉴얼 구성 없이 GitLab.com 및 다양한 인기 있는 공개 호스트를 지원합니다. Self-Managed GitLab에서 사용하려면 git-credential-oauth 사용자 지정 호스트 문서를 참조하십시오.

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

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

이중 인증 활성화

귀하의 계정 이메일은 2FA를 활성화하려면 확인되어 있어야 합니다.

일회용 암호를 활성화

한 번에 하나의 암호로 2FA를 활성화하려면:

  1. GitLab에서:
    1. 사용자 설정에 액세스합니다.
    2. 계정을 선택합니다.
    3. 이중 인증 활성화를 선택합니다.
  2. 기기에서(일반적으로 귀하의 휴대폰):
    1. 호환되는 애플리케이션을 설치합니다. 예를 들어:
    2. 애플리케이션 내에서 다음 중 하나의 방식으로 새 항목을 추가합니다:
      • GitLab에 의해 표시된 코드를 기기의 카메라로 스캔하여 항목을 자동으로 추가합니다.
      • 제공된 세부 정보를 입력하여 항목을 매뉴얼으로 추가합니다.
  3. GitLab에서:
    1. Pin 코드로부터 6자리 핀 번호를 입력합니다.
    2. 현재 암호를 입력합니다.
    3. 제출을 선택합니다.

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

FortiAuthenticator를 사용하여 일회용 암호 활성화

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

GitLab에서 FortiAuthenticator를 일회용 암호(OTP) 제공자로 사용할 수 있습니다. 사용자는 다음과 같은 조건을 충족해야 합니다:

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

FortiAuthenticator의 사용자 이름과 액세스 토큰이 필요합니다. 아래 표시된 access_token은 FortAuthenticator 액세스 키입니다. 토큰을 얻으려면 Fortinet 문서 라이브러리의 REST API 솔루션 가이드를 참조하십시오. 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를 사용하여 일회용 암호 활성화

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

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

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

Prerequisites

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를 사용하여 일회용 암호 활성화하기

Offering: Self-Managed
Self-Managed GitLab에서는 기본적으로 이 기능을 사용할 수 없습니다. 사용자별로 사용 가능하게 하려면, 관리자가 forti_token_cloud라는 피처 플래그를 활성화할 수 있습니다. GitLab.com 및 GitLab Dedicated에서는 이 기능을 사용할 수 없습니다. 이 기능은 프로덕션 환경에 사용할 준비가 되지 않았습니다.

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

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

FortiToken Cloud를 GitLab에서 구성하려면. 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_without_totp라는 피처 플래그를 활성화할 수 있습니다. GitLab.com에서는이 기능을 사용할 수 있습니다. GitLab Dedicated에서는 이 기능을 사용할 수 없습니다.

WebAuthn은 다음에 의해 지원됩니다:

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

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

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

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

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

처음으로 2FA를 설정하는 경우 계정에 복구 코드를 다운로드해야합니다 귀하의 계정에 액세스를 잃을 경우를 대비하여.

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

복구 코드

한 번 사용 암호로 2FA를 성공적으로 활성화 한 직후, 생성된 복구 코드 세트를 다운로드하라는 메시지가 표시됩니다. 암호 생성기에 액세스를 잃어도 계정에 로그인할 수 있습니다.

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

코드를 복사하고 인쇄하거나 안전한 곳에 저장하려면 코드 다운로드를 사용하십시오. 코드를 다운로드하기로 선택하면 파일의 이름은 gitlab-recovery-codes.txt입니다.

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

복구 코드를 분실하거나 새로 생성하려면 다음 중 하나를 사용할 수 있습니다:

2FA 복구 코드 재생성

2FA 복구 코드를 재생성하려면 데스크톱 브라우저에 액세스해야합니다:

  1. 사용자 설정에 액세스합니다.
  2. 계정 > 이중 인증 (2FA)를 선택합니다.
  3. 이미 2FA를 구성한 경우 이중 인증 관리를 선택합니다.
  4. 이중 인증 해제 섹션에서 현재 비밀번호현재 비밀번호 텍스트 상자에 입력하고 복구 코드 재생성을 선택합니다.
note
2FA 복구 코드를 재생성하면 저장되지 않습니다. 이전에 생성된 2FA 코드를 사용할 수 없습니다.

이중 인증이 활성화된 상태로 로그인하기

2FA(이중 인증)가 활성화된 상태에서의 로그인은 보통의 로그인 절차와 약간 다릅니다. 사용자 이름과 암호를 입력한 후에 두 번째 프롬프트가 표시되는데, 이는 활성화된 2FA의 종류에 따라 다릅니다.

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

요구사항에 따라 일회용 비밀번호 인증기 응용프로그램의 핀 번호 또는 복구 코드를 입력하여 로그인합니다.

WebAuthn 장치를 사용하여 로그인하기

지원되는 브라우저에서 자격 증명을 입력한 후 WebAuthn 장치를 활성화하도록 자동으로 프롬프팅됩니다(예: 터치하거나 버튼을 누릅니다).

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

이중 인증 해제하기

2FA를 해제하려면:

  1. 사용자 설정에 들어갑니다.
  2. 계정을 선택합니다.
  3. 이중 인증 관리를 선택합니다.
  4. 이중 인증 해제 섹션에서 현재 암호란에 현재 암호를 입력하고 이중 인증 해제를 선택합니다.

모바일 애플리케이션 및 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. 새 코드를 생성하고자 하는지 확인됩니다. 이 과정에서 이전에 저장된 코드가 무효화됩니다. 예:

    새 2FA 복구 코드를 생성하시겠습니까?
    저장된 복구 코드가 모두 무효화됩니다. (예/아니요)
       
    yes
       
    2FA 복구 코드:
       
    119135e5a3ebce8e
    11f6v2a498810dcd
    3924c7ab2089c902
    e79a3398bfe4f224
    34bd7b74adbc8861
    f061691d5107df1a
    169bf32a18e63e7f
    b510e7422e81c947
    20dbed24c5e74663
    df9d3b9403b9c9f0
       
    로그인할 때 위 코드 중 하나를 사용하여 2FA 코드를 입력하십시오. 그런 다음 프로필 설정을 방문하여 새 장치를 추가하여 계정에 다시 액세스할 수 있도록 합니다.
    
  3. GitLab 로그인 페이지로 이동하여 사용자 이름 또는 이메일과 암호를 입력합니다. 두 번째 인증 코드를 입력하라는 메시지가 표시되면 명령행 출력에서 얻은 복구 코드 중 하나를 입력합니다.

로그인한 후 즉시 새로운 장치로 2FA를 설정합니다.

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

Tier: Premium, Ultimate Offering: GitLab.com

기타 방법을 사용할 수 없는 경우 GitLab 지원 담당자에게 연락하여 계정의 2FA 비활성화를 요청할 수 있습니다. 지원 티켓을 제출하여 2FA를 해제할 수 있습니다:

  • 이 서비스는 GitLab.com 구독 계정에만 제공됩니다. 자세한 내용은 블로그 글을 참조하세요.
  • 이 설정을 일시적으로 비활성화하는 것은 계정을 보호하는 데 덜 안전한 상태로 남겨두기 때문에 가능한 한 빨리 로그인하여 2FA를 다시 활성화해야 합니다.

GitLab 관리자용 정보

Tier: Free, Premium, Ultimate Offering: Self-Managed
  • GitLab 백업을 복원한 후에도 2FA가 계속 작동하도록 주의하세요.
  • 시간 기반 일회용 패스워드(TOTP) 서버와 2FA가 올바르게 인증되도록 하려면 NTP와 같은 서비스를 사용하여 GitLab 서버의 시간을 동기화하세요. 그렇지 않으면 시간 차이 때문에 항상 인증에 실패할 수 있습니다.
  • GitLab WebAuthn 구현은 GitLab 인스턴스가 여러 호스트명이나 FQDN에서 액세스되는 경우 작동하지 않습니다. 각 WebAuthn 등록은 _등록된 현재 호스트명_에 링크되어 있으며 다른 호스트명이나 FQDN에는 사용할 수 없습니다.

    예를 들어, 사용자가 first.host.xyzsecond.host.xyz에서 GitLab 인스턴스에 액세스하려고 하는 경우:

    • 사용자는 first.host.xyz를 사용하여 로그인하고 WebAuthn 키를 등록합니다.
    • 사용자가 로그아웃한 후 first.host.xyz를 사용하여 로그인을 시도하면 WebAuthn 인증이 성공합니다.
    • 사용자가 로그아웃한 후 second.host.xyz를 사용하여 로그인을 시도하면 WebAuthn 인증이 실패합니다. 왜냐하면 WebAuthn 키는 first.host.xyz에만 등록되어 있기 때문입니다.
  • 시스템이나 그룹 수준에서 2FA를 강제하려면 2단계 인증을 강제로 설정을 참조하세요.

문제 해결

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

요청 시 다음과 같은 오류 메시지가 표시될 수 있습니다:

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

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

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

오류: “유효하지 않은 핀 코드”

유효하지 않은 핀 코드 오류를 받는 경우, 이는 인증 애플리케이션과 GitLab 인스턴스 자체 사이에 시간 동기화 문제가 있을 수 있음을 나타낼 수 있습니다. 시간 동기화 문제를 피하려면 코드를 생성하는 기기에서 시간 동기화를 활성화하세요. 예를 들어:

  • 안드로이드(구글 인증앱)의 경우:
    1. 구글 인증앱의 메인 메뉴로 이동합니다.
    2. 설정을 선택합니다.
    3. 코드에 대한 시간 교정을 선택합니다.
    4. 지금 동기화를 선택합니다.
  • iOS의 경우:
    1. 설정으로 이동합니다.
    2. 일반을 선택합니다.
    3. 날짜 및 시간을 선택합니다.
    4. 자동으로 설정을 활성화하세요. 이미 활성화되어 있는 경우 비활성화한 다음 잠시 기다렸다가 다시 활성화하세요.

오류: “퍼미션 거부(publickey)” - 복구 코드 재생성 시

SSH 키를 사용하여 새로운 복구 코드를 생성하려고 시도했을 때 퍼미션 거부(publickey) 오류를 받고 기본이 아닌 SSH 키 페어 파일 경로를 사용하는 경우, ssh-agent를 사용하여 개인 SSH 키를 매뉴얼으로 등록해야 할 수 있습니다.