- SSH 키란
- 사전 준비 사항
- 지원되는 SSH 키 유형
- 기존 SSH 키 쌍 확인
- SSH 키 쌍 생성
- FIDO2 하드웨어 보안 키용 SSH 키페어 생성
- 패스워드 매니저로 SSH 키페어 생성하기
- GitLab 계정에 SSH 키 추가하기
- 연결 가능한지 확인하기
- 다른 리포지터리에 대한 다른 키 사용
- 계정의 SSH 키 보기
- SSH 키 삭제
- 단일 GitLab 인스턴스에서 다른 계정 사용
- 이중 인증(2FA) 구성
- Eclipse에서 EGit 사용
- Microsoft Windows에서 SSH 사용
- GitLab 서버에서 SSH 설정 재정의
- 문제 해결
GitLab을 사용하여 SSH 키로 통신하는 방법
Git은 분산 버전 관리 시스템으로, 로컬에서 작업한 후 변경 사항을 서버에 공유하거나 푸시할 수 있습니다. 이 경우 푸시하는 서버는 GitLab입니다.
GitLab은 SSH 프로토콜을 사용하여 Git과 안전하게 통신합니다. GitLab 원격 서버에 인증하기 위해 SSH 키를 사용하면 매번 사용자 이름과 암호를 제공할 필요가 없습니다.
SSH 키란
SSH는 공개 키와 개인 키 두 가지 키를 사용합니다.
- 공개 키는 배포할 수 있습니다.
- 개인 키는 보호되어야 합니다.
공개 키를 업로드하여 기밀 데이터를 드러내는 것은 불가능합니다. SSH 공개 키를 복사하거나 업로드해야 하는 경우 실수로 개인 키를 복사하거나 업로드하지 않도록 주의하십시오.
개인 키를 사용하여 커밋에 서명하면 GitLab 사용 및 데이터 사용이 더욱 안전해집니다. 이 서명은 공개 키를 사용하여 누구나 확인할 수 있습니다.
세부 사항은 비대칭 암호화(공개 키 암호화로도 알려짐)를 참조하십시오.
사전 준비 사항
GitLab과 SSH로 통신하려면 다음이 필요합니다. - GNU/Linux, macOS 및 Windows 10에 기본으로 설치된 OpenSSH 클라이언트 - SSH 버전 6.5 이상. 이전 버전에서는 안전하지 않은 MD5 서명이 사용되었습니다.
시스템에 설치된 SSH 버전을 확인하려면 ssh -V
를 실행하십시오.
지원되는 SSH 키 유형
GitLab과 통신하려면 다음 SSH 키 유형을 사용할 수 있습니다.
- ED25519
- ED25519_SK
- ECDSA_SK
- RSA
- ECDSA (Go로 작성된 실용적인 암호화와 관련된 보안 문제의 제한 사항을 참조하십시오.)
관리자는 허용되는 키 및 최소 길이를 제한할 수 있습니다.
ED25519 SSH 키
도서 Go로 작성된 실용적인 암호화와 관련된 보안 문제에 따르면 ED25519 키가 RSA 키보다 보안성이 높고 성능이 우수합니다.
OpenSSH 6.5에서 2014년에 ED25519 SSH 키가 도입되었으며 대부분의 운영 체제에서 사용할 수 있어야 합니다.
ED25519_SK SSH 키
GitLab에서 ED25519_SK SSH 키를 사용하려면 로컬 클라이언트와 GitLab 서버에 OpenSSH 8.2 이상이 설치되어 있어야 합니다.
ECDSA_SK SSH 키
GitLab에서 ECDSA_SK SSH 키를 사용하려면 로컬 클라이언트와 GitLab 서버에 OpenSSH 8.2 이상이 설치되어 있어야 합니다.
RSA SSH 키
- GitLab 16.3에서 최대 RSA 키 길이가 변경되었습니다.
사용 가능한 문서에서는 ED25519이 RSA보다 보안성이 더 높다고 제안하고 있습니다.
RSA 키를 사용하는 경우 미국 국립표준기술연구소(NIST)는 출판물 800-57 Part 3 (PDF)에서 적어도 2048 비트 키 권장했습니다. Go의 제한으로 인해 RSA 키는 8192 비트를 초과할 수 없습니다.
기본 키 크기는 ssh-keygen
버전에 따라 다릅니다. 설치된 ssh-keygen
명령어의 man
페이지를 확인하십시오.
기존 SSH 키 쌍 확인
키 쌍을 생성하기 전에 이미 키 쌍이 있는지 확인하십시오.
- 홈 디렉터리로 이동합니다.
-
.ssh/
하위 디렉터리로 이동합니다..ssh/
하위 디렉터리가 없는 경우 홈 디렉터리에 있지 않거나 이전에ssh
를 사용하지 않은 것입니다. 이 경우 SSH 키 쌍을 생성해야 합니다. -
다음 형식의 파일이 있는지 확인합니다.
알고리즘 공개 키 개인 키 ED25519 (선호) id_ed25519.pub
id_ed25519
ED25519_SK id_ed25519_sk.pub
id_ed25519_sk
ECDSA_SK id_ecdsa_sk.pub
id_ecdsa_sk
RSA (적어도 2048비트 키 크기) id_rsa.pub
id_rsa
DSA (사용 중단) id_dsa.pub
id_dsa
ECDSA id_ecdsa.pub
id_ecdsa
SSH 키 쌍 생성
기존 SSH 키 쌍이 없는 경우 새로 생성하십시오.
-
터미널을 연 다음 다음 명령을 실행합니다.
ssh-keygen -t <키 유형> -C "<코멘트>"
이 코멘트는 생성되는
.pub
파일에 포함됩니다. 코멘트로 이메일 주소를 사용해도 됩니다.예를 들어, ED25519의 경우:
ssh-keygen -t ed25519 -C "<코멘트>"
2048비트 RSA의 경우:
ssh-keygen -t rsa -b 2048 -C "<코멘트>"
-
Enter 키를 누릅니다. 다음과 유사한 출력이 표시됩니다.
공개/개인 ed25519 키 쌍을 생성합니다. 키를 저장할 파일 이름을 입력하십시오(/home/user/.ssh/id_ed25519):
-
제안된 파일 이름 및 디렉터리를 수락하십시오. 배포 키를 생성하는 경우나 다른 키를 저장하는 특정 디렉터리가 있는 경우에만 다르게 저장하세요.
또한 SSH 키 쌍을 특정 호스트에 지정할 수도 있습니다.
-
암호구성을 지정합니다.
암호를 입력하십시오(암호 없이 빈칸으로 입력 가능): 다시 한번 암호를 입력하십시오:
파일이 저장된 위치에 대한 정보를 포함한 확인이 표시됩니다.
공개 및 개인 키가 생성됩니다. 공개 SSH 키를 GitLab 계정에 추가하고 개인 키는 안전하게 보관하세요.
SSH를 다른 디렉터리로 지정하기
기본 디렉터리에 SSH 키 쌍을 저장하지 않은 경우 SSH 클라이언트를 개인 키가 저장된 디렉터리로 지정하세요.
-
터미널을 열고 다음 명령을 실행합니다.
eval $(ssh-agent -s) ssh-add <개인 SSH 키가 저장된 디렉터리>
-
이러한 설정을
~/.ssh/config
파일에 저장하세요. 예시:# GitLab.com Host gitlab.com PreferredAuthentications publickey IdentityFile ~/.ssh/gitlab_com_rsa # 사설 GitLab 인스턴스 Host gitlab.company.com PreferredAuthentications publickey IdentityFile ~/.ssh/example_com_rsa
이러한 설정에 대한 자세한 정보는 SSH 구성 메뉴얼의 man ssh_config
페이지를 참조하십시오.
공개 SSH 키는 GitLab에 고유해야 합니다. 이 키는 여러분이 SSH를 사용하여 코드를 푸시할 때 유일한 식별자로 사용됩니다. 이는 단일 사용자에 대응해야 합니다.
SSH 키 암호 변경하기
SSH 키의 암호를 변경할 수 있습니다.
-
터미널을 열고 다음 명령을 실행합니다:
ssh-keygen -p -f /경로/대상/ssh_key
-
프롬프트에서 암호를 입력한 다음 Enter을 누릅니다.
RSA 키 쌍을 보다 안전한 형식으로 업그레이드하기
OpenSSH 버전이 6.5에서 7.8 사이인 경우, 당신의 개인 RSA SSH 키를 더 안전한 OpenSSH 형식으로 저장할 수 있습니다. 이를 위해 터미널을 열고 다음 명령을 실행합니다.
ssh-keygen -o -f ~/.ssh/id_rsa
또는 다음 명령으로 더 안전한 암호화 형식의 새로운 RSA 키를 생성할 수도 있습니다.
ssh-keygen -o -t rsa -b 4096 -C "<comment>"
FIDO2 하드웨어 보안 키용 SSH 키페어 생성
ED25519_SK 또는 ECDSA_SK SSH 키를 생성하려면 OpenSSH 8.2 이상을 사용해야 합니다:
- 컴퓨터에 하드웨어 보안 키를 넣습니다.
- 터미널을 엽니다.
-
ssh-keygen -t
다음에 키 유형과 선택 사항 주석을 입력한 후 enter키를 누릅니다. 이 주석은 생성된 .pub 파일에 포함됩니다. 주석으로 이메일 주소를 사용하는 것이 좋습니다.예를 들어, ED25519_SK의 경우:
ssh-keygen -t ed25519-sk -C "<comment>"
ECDSA_SK의 경우:
ssh-keygen -t ecdsa-sk -C "<comment>"
보안 키가 FIDO2 resident 키를 지원하는 경우 SSH 키를 만들 때 이 기능을 활성화할 수 있습니다.
ssh-keygen -t ed25519-sk -O resident -C "<comment>"
-O resident
는 키가 FIDO 인증자 자체에 저장되어야 함을 나타냅니다. Resident key는 새 컴퓨터에 더 쉽게 가져올 수 있으므로 보안 키에서 직접로드(ssh-add -K
또는ssh-keygen -K
) 할 수 있습니다. -
Enter 키를 누릅니다. 다음과 비슷한 출력이 표시됩니다.
공개/비공개 ed25519-sk 키페어 생성 중. 인증자를 터치하여 키 생성을 승인해야 할 수 있습니다.
-
하드웨어 보안 키의 버튼을 누릅니다.
-
제안된 파일명과 디렉터리를 수락합니다:
키를 저장할 파일 입력(기본: /home/user/.ssh/id_ed25519_sk):
-
암호를 지정합니다:
암호 입력(입력하지 않으면 빈 상태로 남겨두세요): 암호를 다시 입력하세요:
파일이 어디에 저장되었는지에 대한 정보를 포함한 확인이 표시됩니다.
공개 및 비공개 키가 생성됩니다. 공개 SSH 키를 GitLab 계정에 추가합니다.
패스워드 매니저로 SSH 키페어 생성하기
1Password로 SSH 키페어 생성
1Password 및 1Password 브라우저 확장 프로그램을 사용하여 다음을 수행할 수 있습니다:
- 새 SSH 키를 자동으로 생성합니다.
- 1Password 폴더에 있는 기존 SSH 키를 사용하여 GitLab에 인증합니다.
- GitLab에 로그인합니다.
- 왼쪽 사이드바에서 아바타를 선택합니다.
- 프로필 편집을 선택합니다.
- 왼쪽 사이드바에서 SSH 키를 선택합니다.
- 새 키 추가를 선택합니다.
- 키를 선택하면 1Password 도우미가 표시됩니다.
- 1Password 아이콘을 선택하고 1Password를 잠금 해제합니다.
- 그런 다음 SSH 키 생성을 선택하거나 기존 SSH 키를 선택하여 공개 키를 채울 수 있습니다.
-
제목 상자에
Work Laptop
또는Home Workstation
과 같은 설명을 입력합니다. - 선택 사항. 키의 사용 유형을 선택합니다.
Authentication
또는Signing
또는 둘 다 사용할 수 있습니다.Authentication & Signing
이 기본 값입니다. - 선택 사항. 기본 만료 날짜를 수정하려면 만료 날짜를 업데이트합니다.
- 키 추가를 선택합니다.
SSH 키 사용에 대한 자세한 내용은 1Password 문서를 참조하십시오.
GitLab 계정에 SSH 키 추가하기
GitLab에서 SSH를 사용하려면 공개 키를 GitLab 계정에 복사합니다.
-
공개 키 파일의 내용을 복사합니다. 이 작업은 매뉴얼으로 수행하거나 스크립트를 사용할 수 있습니다. 예를 들어, ED25519 키를 클립 보드로 복사하려면:
macOS
tr -d '\n' < ~/.ssh/id_ed25519.pub | pbcopy
Linux (
xclip
패키지가 필요합니다)xclip -sel clip < ~/.ssh/id_ed25519.pub
Windows의 Git Bash
cat ~/.ssh/id_ed25519.pub | clip
파일 이름을 해당하는 것으로 바꿉니다. 예를들어 RSA의 경우
id_rsa.pub
를 사용합니다. - GitLab에 로그인합니다.
- 왼쪽 사이드바에서 아바타를 선택합니다.
- 프로필 편집을 선택합니다.
- 왼쪽 사이드바에서 SSH 키를 선택합니다.
- 새 키 추가를 선택합니다.
-
키 상자에 공개 키의 내용을 붙여넣습니다.
매뉴얼으로 키를 복사하는 경우
ssh-rsa
,ssh-dss
,ecdsa-sha2-nistp256
,ecdsa-sha2-nistp384
,ecdsa-sha2-nistp521
,ssh-ed25519
,sk-ecdsa-sha2-nistp256@openssh.com
또는sk-ssh-ed25519@openssh.com
으로 시작하고 주석으로 끝날 수 있는 전체 키를 복사해야 합니다. -
제목 상자에
Work Laptop
또는Home Workstation
과 같은 설명을 입력합니다. - 선택 사항. 키의 사용 유형을 선택합니다.
Authentication
또는Signing
또는 둘 다 사용할 수 있습니다.Authentication & Signing
이 기본 값입니다. - 선택 사항. 기본 만료 날짜를 수정하려면 만료 날짜를 업데이트합니다.
- 관리자는 만료 날짜를 볼 수 있으며 키를 삭제할 때 안내를 받을 수 있습니다.
- GitLab은 매일 오전 01:00 UTC에 모든 SSH 키를 확인합니다. 7일 후에 만료될 SSH 키에 대해 만료 안내 이메일을 보냅니다.
- GitLab은 매일 오전 02:00 UTC에 현재 날짜에 만료되는 모든 SSH 키에 대해 만료 안내 이메일을 보냅니다.
- 키 추가를 선택합니다.
연결 가능한지 확인하기
SSH 키가 올바르게 추가되었는지 확인합니다.
다음 명령은 예시 호스트 이름 gitlab.example.com
을 사용합니다. 이 예시 호스트 이름을 GitLab 인스턴스의 호스트 이름으로 바꿉니다. 예를들면 git@gitlab.com
과 같이요.
기본적으로 GitLab은 git
사용자명을 사용하여 인증합니다. 이것은 관리자에 의해 변경될 수 있습니다.
- 올바른 서버에 연결되고 있는지 확인하려면 서버의 SSH 호스트 키 지문을 확인합니다.
- GitLab.com의 경우 SSH 호스트 키 지문 설명서를 참조하세요.
- GitLab.com 또는 다른 GitLab 인스턴스의 경우
gitlab.example.com/help/instance_configuration#ssh-host-keys-fingerprints
을 참조하세요.gitlab.example.com
은gitlab.com
(GitLab.com의 경우) 또는 GitLab 인스턴스의 주소로 바꿉니다.
-
터미널을 열고 다음 명령을 실행합니다.
gitlab.example.com
을 GitLab 인스턴스 URL로 바꿉니다.ssh -T git@gitlab.example.com
-
처음 연결하는 경우 GitLab 호스트의 신원을 확인해야 합니다. 다음과 같은 메시지를 보게되면:
호스트 'gitlab.example.com (35.231.145.151)'의 진위를 확인할 수 없습니다. ECDSA 키 지문은 SHA256:HbW3g8zUjNSksFbqTiUWPWg2Bq1x8xdGUrliXFzSnUw입니다. 계속하시겠습니까(yes/no)? yes 경고: 'gitlab.example.com' (ECDSA 형식)가 알려진 호스트 디렉터리에 영구적으로 추가되었습니다.
yes
를 입력하고 Enter을 누릅니다. - 다시
ssh -T git@gitlab.example.com
명령을 실행합니다. 환영 메시지인 _Welcome to GitLab,@username
!_를 받아야 합니다.
환영 메시지가 표시되지 않는 경우 ssh
를 디버깅 모드로 실행하여 문제를 해결할 수 있습니다.
ssh -Tvvv git@gitlab.example.com
다른 리포지터리에 대한 다른 키 사용
각 리포지터리에 대해 다른 키를 사용할 수 있습니다.
터미널을 열고 이 명령을 실행하세요.
git config core.sshCommand "ssh -o IdentitiesOnly=yes -i ~/.ssh/private-key-filename-for-this-repository -F /dev/null"
이 명령은 SSH 에이전트를 사용하지 않으며 Git 2.10 이상이 필요합니다. ssh
명령 옵션에 대한 자세한 정보는 ssh
와 ssh_config
의 man
페이지를 참조하세요.
계정의 SSH 키 보기
계정의 SSH 키를 보려면:
- 왼쪽 사이드바에서 아바타를 선택합니다.
- 프로필 편집을 선택합니다.
- 왼쪽 사이드바에서 SSH 키를 선택합니다.
기존의 SSH 키는 페이지 하단에 나열됩니다. 정보에는 다음이 포함됩니다:
- 키의:
- 이름.
- 공개 지문.
- 만료 날짜.
- 허용된 사용 유형.
- 키를 마지막으로 사용한 시간.
SSH 키 삭제
SSH 키를 영구적으로 삭제하려면:
- 왼쪽 사이드바에서 아바타를 선택합니다.
- 프로필 편집을 선택합니다.
- 왼쪽 사이드바에서 SSH 키를 선택합니다.
- 삭제할 키 옆에서 제거 ()를 선택합니다.
- 삭제를 선택합니다.
단일 GitLab 인스턴스에서 다른 계정 사용
GitLab의 단일 인스턴스에 여러 계정을 연결할 수 있습니다.
이를 위해 이전 주제에서 사용한 명령을 사용할 수 있습니다.
그러나 IdentitiesOnly
를 yes
로 설정했을 때도 IdentityFile
이 Host
블록 외부에 존재하는 경우 로그인할 수 없습니다. 대신 ~/.ssh/config
파일에서 호스트에 별칭을 지정할 수 있습니다.
-
Host
에는user_1.gitlab.com
및user_2.gitlab.com
과 같은 별칭을 사용합니다. 고급 구성은 유지 관리가 더 어렵고 이러한 문자열은git remote
와 같은 도구를 사용할 때 이해하기 쉽습니다. -
IdentityFile
에는 개인 키의 경로를 사용합니다.
# 사용자1 계정 식별
Host <user_1.gitlab.com>
Hostname gitlab.com
PreferredAuthentications publickey
IdentityFile ~/.ssh/<example_ssh_key1>
# 사용자2 계정 식별
Host <user_2.gitlab.com>
Hostname gitlab.com
PreferredAuthentications publickey
IdentityFile ~/.ssh/<example_ssh_key2>
이제 user_1
을 위해 리포지터리를 복제하려면 git clone
명령에서 user_1.gitlab.com
을 사용하세요.
git clone git@<user_1.gitlab.com>:gitlab-org/gitlab.git
이전에 복제한 리포지터리를 origin
으로 별칭 지정해 업데이트하려면:
git remote set-url origin git@<user_1.gitlab.com>:gitlab-org/gitlab.git
이중 인증(2FA) 구성
Git over SSH için 이중 인증(2FA)을 설정할 수 있습니다. ED25519_SK 또는 ECDSA_SK SSH 키를 사용하는 것을 권장합니다.
Eclipse에서 EGit 사용
EGit을 사용하는 경우 Eclipse에 SSH 키 추가할 수 있습니다.
Microsoft Windows에서 SSH 사용
Windows 10을 실행 중이라면, Windows Subsystem for Linux (WSL)을 사용하여 미리 설치된 git
및 ssh
를 사용하거나 Git for Windows를 설치하여 PowerShell을 통해 SSH를 사용할 수 있습니다.
WSL에서 생성된 SSH 키는 Git for Windows에서 직접 사용할 수 없으며 그 반대도 마찬가지로 적용됩니다. 각각 다른 홈 디렉터리를 사용하기 때문입니다:
- WSL:
/home/<user>
- Git for Windows:
C:\Users\<user>
동일한 키를 사용하려면 .ssh/
디렉터리를 복사하거나 각 환경에서 키를 생성할 수 있습니다.
Windows 11을 실행 중이고 OpenSSH for Windows를 사용 중이라면, 환경 변수 HOME
이 올바르게 설정되어 있는지 확인하세요. 그렇지 않으면 개인 SSH 키를 찾을 수 없을 수 있습니다.
대체 도구로는 다음이 있습니다:
GitLab 서버에서 SSH 설정 재정의
GitLab은 시스템에 설치된 SSH 데몬과 통합되어 모든 액세스 요청을 처리하는 사용자(일반적으로 git
이라고 함)를 지정합니다. SSH를 통해 GitLab 서버에 연결하는 사용자는 사용자 이름 대신 SSH 키로 식별됩니다.
GitLab 서버에서 수행한 SSH client 작업은 이 사용자로 실행됩니다. 이 SSH 구성을 수정할 수 있습니다. 예를 들어, 이 사용자가 인증 요청에 사용할 프라이빗 SSH 키를 지정할 수 있습니다. 그러나 이는 지원되지 않으며 심각한 보안 위험이 존재하기 때문에 강하게 권장하지 않습니다.
GitLab은 이 조건을 확인하고 서버가 이러한 방식으로 구성되어 있는 경우 여러분을 이 섹션으로 안내합니다. 예를 들어:
$ gitlab-rake gitlab:check
Git user has default SSH configuration? ... no
Try fixing it:
mkdir ~/gitlab-check-backup-1504540051
sudo mv /var/lib/git/.ssh/id_rsa ~/gitlab-check-backup-1504540051
sudo mv /var/lib/git/.ssh/id_rsa.pub ~/gitlab-check-backup-1504540051
For more information see:
doc/user/ssh.md#overriding-ssh-settings-on-the-gitlab-server
Please fix the error above and rerun the checks.
가능한 빨리 사용자 지정된 구성을 제거하세요. 이러한 사용자 지정은 명시적으로 지원되지 않으며 언제든지 작동을 중단할 수 있습니다.
문제 해결
TLS: 서버가 8192비트보다 큰 RSA 키를 포함한 인증서를 보냄
GitLab 16.3 이상에서 RSA 키를 최대 8192비트로 제한하는 Go가 있습니다. 키의 길이를 확인하려면:
openssl rsa -in <your-key-file> -text -noout | grep "Key:"
8192비트보다 긴 키를 갖는 키를 더 짧은 키로 대체하세요.
git clone
으로 암호 프롬프트 표시
git clone
을 실행하면 git@gitlab.example.com's password:
와 같이 암호를 요청하는 경우 SSH 설정에 문제가 있을 수 있습니다.
- SSH 키 쌍을 올바르게 생성하고 공개 SSH 키를 GitLab 프로필에 추가했는지 확인하세요.
-
ssh-agent
를 사용하여 매뉴얼으로 개인 SSH 키를 등록해 보세요. -
ssh -Tv git@example.com
을 실행하여 연결을 디버깅해 보세요.example.com
을 GitLab URL로 대체하세요. - Microsoft Windows에서 SSH 사용의 모든 지침을 따랐는지 확인하세요.
호스트 이름을 확인할 수 없음
오류
연결이 가능한지 확인하는 중 다음과 같은 오류 메시지를 받을 수 있습니다:
ssh: Could not resolve hostname gitlab.example.com: nodename nor servname provided, or not known
만약 이 오류를 받으면 터미널을 재시작한 후 명령을 다시 실행해 보세요.
키 등록 실패: 유효하지 않은 형식
오류
FIDO2 하드웨어 보안 키용 SSH 키 쌍을 생성하는 중 다음과 같은 오류 메시지를 받을 수 있습니다:
Key enrollment failed: invalid format
다음을 시도하여 문제를 해결할 수 있습니다:
-
sudo
를 사용하여ssh-keygen
명령을 실행합니다. - FIDO2 하드웨어 보안 키가 제공된 키 유형을 지원하는지 확인합니다.
-
ssh -V
를 실행하여 OpenSSH 버전이 8.2 이상인지 확인합니다.