이중 인증

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 Credential Manager (GCM)는 기본적으로 OAuth를 사용하여 인증합니다. GCM은 수동 구성없이 GitLab.com을 지원합니다. 자신의 GitLab을 사용하려면 GitLab support을 참조하십시오.

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

Git for Windows에는 Git Credential Manager가 포함되어 있습니다.

Git Credential Manager는 주로 GitHub, Inc.에서 개발되었습니다. 오픈 소스 프로젝트이며 커뮤니티에서 지원됩니다.

git-credential-oauth

git-credential-oauth는 수동 구성없이 GitLab.com 및 여러 인기있는 공개 호스트를 지원합니다. 자체 관리형 GitLab에서 사용하려면 git-credential-oauth custom hosts documentation을 참조하십시오.

많은 Linux 배포판에는 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를 사용하여 일회용 비밀번호 활성화

플래그: 자체 관리 GitLab의 경우 기본적으로이 기능을 사용할 수 없습니다. 사용자 단위로이 기능을 사용하려면 관리자가 forti_authenticator라는 기능 플래그를 활성화할 수 있습니다. GitLab.com 및 전용 GitLab의 경우이 기능을 사용할 수 없습니다.

당신은 GitLab에서 일회용 비밀번호(OTP) 제공 업체로 FortiAuthenticator를 사용할 수 있습니다. 사용자는 다음을 준수해야합니다.

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

FortiAuthenticator의 사용자 이름과 엑세스 토큰이 필요합니다. 아래 표시된 access_token은 FortAuthenticator 액세스 키입니다. 토큰을 얻으려면 Fortinet Document Library의 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를 사용하여 일회용 비밀번호 활성화

플래그: 자체 관리 GitLab의 경우 기본적으로이 기능을 사용할 수 있습니다. GitLab.com의 경우이 기능을 사용할 수 없습니다.

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

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
  • 이슈에서 GitLab 13.7에서 소개되었으며 기본적으로 비활성화된 forti_token_cloud라는 플래그와 함께 합니다.
Self-managed GitLab의 경우 기본적으로 이 기능을 사용할 수 없습니다. 사용자별로 이 기능을 사용하도록 만들려면 관리자가 forti_token_cloud라는 피처 플래그를 활성화할 수 있습니다. GitLab.com 및 전용 GitLab에서는 이 기능을 사용할 수 없습니다. 해당 기능은 아직 본격적인 사용을 위한 준비가 되지 않았습니다.

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

  • FortiToken Cloud와 GitLab에 동일한 사용자 이름으로 등록되어 있어야 합니다.
  • FortiToken Cloud에서 FortiToken이 구성되어 있어야 합니다.

FortiToken Cloud를 구성하려면 client_id 및 client_secret가 필요합니다. 이 정보는 Fortinet Document Library의 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 장치 설정

  • WebAuthn 장치는 GitLab 13.4에서 이슈를 통해 소개되었으며 기본적으로 비활성화된 webauthn이라는 플래그와 함께 등장했습니다.
  • WebAuthn 장치는 GitLab 14.6에서 GitLab.com 및 자체 관리에서 활성화되었습니다.
  • WebAuthn 장치를 위한 선택적 일회용 암호 인증은 GitLab 15.10에서 이슈를 통해 소개되었으며 기본적으로 활성화된 webauthn_without_totp이라는 플래그와 함께 등장했습니다. GitLab.com 및 자체 관리에서 기본적으로 활성화되었습니다.
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 13.3 이후 Safari

WebAuthn 호환 장치를 사용하여 2단계 인증(2FA)을 설정하려면 다음을 수행하세요:

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

장치를 성공적으로 설정했음을 나타내는 메시지를 받아야 합니다.

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

만약 이번이 2FA를 설정하는 첫 번째 경우이면 브라우저 데이터를 지워 버리면 계정에 액세스 권한을 상실할 수 있으니 복구 코드를 다운로드해야 합니다.

복구 코드

  • GitLab 13.7에서 코드 복사 및 코드 인쇄 버튼이 도입됨.

일회용 암호로 2단계 인증(2FA)을 성공적으로 활성화한 직후에는 생성된 복구 코드 세트를 다운로드하라는 프롬프트가 표시됩니다. 한 번만 사용할 수 있는 복구 코드 중 하나를 사용하여 1회용 암호 인증기에 액세스를 잃는 경우 계정에 로그인할 수 있습니다.

경고: 각 코드는 계정으로 로그인할 때 한 번만 사용할 수 있습니다.

코드를 복사하고 인쇄하거나, 안전한 위치에 보관하기 위해 코드 다운로드를 사용하세요. 코드를 다운로드하는 경우 파일은 gitlab-recovery-codes.txt라고 합니다.

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

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

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

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

  1. 사용자 설정에 액세스하세요.
  2. 계정 > 2단계 인증 (2FA)을 선택하세요.
  3. 이미 2FA를 구성한 경우 2단계 인증 관리를 선택하세요.
  4. 2단계 인증기 등록 창에서 현재 암호를 입력하고 복구 코드 재생성을 선택하세요.

참고: 2FA 복구 코드를 다시 생성하면 저장하세요. 이전에 생성된 2FA 코드를 사용할 수 없습니다.

2단계 인증 활성화된 상태에서 로그인

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

일회용 암호를 사용하여 로그인

요청시, 1회용 암호 인증기 애플리케이션의 핀 또는 복구 코드를 입력하여 로그인하세요.

WebAuthn 장치를 사용하여 로그인

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

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

2단계 인증 해제

2FA를 해제하려면:

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

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

복구 옵션

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

저장된 복구 코드 사용

복구 코드를 사용하려면:

  1. GitLab 로그인 페이지에서 사용자 이름 또는 이메일과 암호를 입력하세요.
  2. 2단계 코드 입력 시 복구 코드를 입력하세요.

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

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

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

  1. 터미널에서 다음을 실행하세요: 

    ssh git@gitlab.com 2fa_recovery_codes

    자체 호스트된 인스턴스의 경우 위 명령에서 gitlab.com을 GitLab 서버 호스트명(예: gitlab.example.com)으로 바꿉니다.

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

    새로운 2단계 인증 복구 코드를 생성하시겠습니까?
이전에 저장한 복구 코드가 무효화됩니다. (예/아니오)

예

당신의 2단계 인증 복구 코드는 다음과 같습니다:

119135e5a3ebce8e
11f6v2a498810dcd
3924c7ab2089c902
e79a3398bfe4f224
34bd7b74adbc8861
f061691d5107df1a
169bf32a18e63e7f
b510e7422e81c947
20dbed24c5e74663
df9d3b9403b9c9f0

로그인 중에 위 코드 중 하나를 2단계 코드 입력란에 입력하세요.
그런 다음 프로필 설정으로 이동하여 새로운 장치를 추가하여 계정에 다시 액세스하지 못하도록 하세요.

  3. GitLab 로그인 페이지로 이동하고 사용자 이름 또는 이메일과 암호를 입력하세요. 2단계 코드를 입력하라는 프롬프트가 표시되면 명령줄 출력에서 얻은 복구 코드 중 하나를 입력하세요.

로그인 후에 즉시 새 기기로 2FA를 설정하세요.

계정에서 이중 인증을 비활성화

Tier: 프리미엄, 얼티밋 Offering: GitLab.com

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

  • 이 서비스는 GitLab.com 구독 계정에만 제공됩니다. 자세한 정보는 블로그 글을 확인하십시오.
  • 이 설정을 일시적으로 비활성화하면 귀하의 계정이 보안 수준이 낮아집니다. 최대한 빨리 로그인하여 2단계 인증을 다시 활성화해야 합니다.

GitLab 관리자용 정보

Tier: 무료, 프리미엄, 얼티밋 Offering: Self-managed
  • GitLab 백업을 복원한 후에도 2단계 인증이 계속 작동하는지 확인하십시오.
  • 시간 기반 일회용 비밀번호(TOTP) 서버로 2단계 인증을 올바르게 승인하려면 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에서만 사용할 수 있기 때문입니다.
  • 시스템이나 그룹 수준에서 2단계 인증을 강제로 적용하려면 2단계 인증을 강제로 적용을 참조하십시오.

문제 해결

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

요청을 보낼 때 다음 오류 메시지를 받을 수 있습니다: 

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

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

대신 다음을 사용하여 인증하십시오:

오류: “잘못된 핀 코드”

잘못된 핀 코드 오류를 받은 경우, 이는 인증 응용 프로그램과 GitLab 인스턴스 자체 간의 시간 동기화 문제일 수 있습니다. 시간 동기화 문제를 피하려면 코드를 생성하는 장치에서 시간 동기화를 활성화하십시오. 예를 들어:

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

오류: “권한이 거부됨 (공개 키)” 재인증 코드를 다시 생성할 때

SSH 키를 사용하여 새로운 복구 코드를 생성하려고 할 때 권한이 거부됨 (공개 키) 오류를 받는 경우, 기본 SSH 키 쌍 파일 경로를 사용하는 동안 ssh-agent를 수동으로 등록해야 할 수 있습니다.