DevOps 지식 허브
DevOps 지식 허브

SSH 및 토큰을 사용하여 일반적인 Git 인증 오류 해결

403 Forbidden 또는 반복적인 자격 증명 프롬프트와 같은 지속적인 Git 인증 오류로 어려움을 겪고 계신가요? 이 가이드는 더 이상 사용되지 않는 암호 로그인에서 벗어나기 위한 전문가 솔루션을 제공합니다. SSH 키의 안전한 설정 방법, HTTPS용 개인 액세스 토큰(PAT) 생성 및 사용 방법, 그리고 macOS, Windows, Linux에서 OS 기본 자격 증명 도우미를 구성하는 모범 사례를 알아보세요. 이 단계를 구현하여 연결을 보호하고 인증 문제를 영구적으로 해결하세요.

41 조회수

SSH 및 토큰을 사용한 일반적인 Git 인증 오류 해결

인증 오류는 Git 사용자가 코드를 복제, 가져오기 또는 푸시할 때 특히 자주 겪는 좌절의 원인입니다. fatal: Authentication failed 또는 403 Forbidden 메시지로 나타나는 지속적인 실패는 Git이 원격 호스팅 서비스(GitHub, GitLab 또는 Bitbucket 등)와 사용자의 신원을 안전하게 확인할 수 없음을 나타냅니다.

이 포괄적인 가이드는 이러한 실패의 핵심 원인을 다룹니다. 이제는 대부분 사용되지 않는 간단한 사용자 이름/비밀번호 프롬프트를 넘어, 현대적이고 안전한 인증 방법인 SSH 키와 개인 액세스 토큰(PAT)에 중점을 둘 것입니다. 이러한 기술을 숙달하는 것은 안정적인 개발 워크플로우를 위해 필수적이며, 자격 증명이 안전하고 Git 제공업체에서 올바르게 인식되도록 보장합니다.

1. 인증 실패 지표 진단

솔루션을 구현하기 전에 Git이 실패하는 이유를 이해하는 것이 중요합니다. 인증 오류는 일반적으로 만료되거나 취소된 자격 증명 또는 저장된 자격 증명에 대해 잘못된 프로토콜(HTTPS vs. SSH) 사용이라는 두 가지 주요 소스에서 발생합니다.

일반적인 오류 메시지

  • 403 Forbidden: 일반적으로 연결 시도는 성공했지만 제공된 자격 증명(비밀번호 또는 토큰)에 작업을 완료하는 데 필요한 권한이 없음을 의미합니다.
  • fatal: Authentication failed for 'https://...': Git이 저장된 자격 증명(종종 자격 증명 도우미를 통해)을 사용하려고 시도했지만 유효하지 않았거나 유효한 자격 증명이 없음을 나타냅니다.
  • 비밀번호 프롬프트 루프: HTTPS를 통해 비밀번호를 반복해서 입력하라는 메시지가 표시되는 경우, 이는 호스팅 제공업체가 더 이상 Git 작업에 비밀번호를 허용하지 않아 대신 개인 액세스 토큰이 필요함을 의미하는 경우가 많습니다.

연결 유형 식별

Git은 원격 URL 구성표에 따라 다르게 인증합니다. 저장소의 원격 URL을 확인하세요:

git remote -v
URL 구성표 필요한 인증 방법
https://github.com/user/repo.git HTTPS를 통한 개인 액세스 토큰 (PAT)
[email protected]:user/repo.git SSH 키 쌍

SSH를 사용하려고 했는데 원격 URL이 HTTPS이거나 그 반대라면 URL을 변경하거나 인증 방법을 전환해야 합니다.

HTTPS에서 SSH로 전환하려면:

git remote set-url origin [email protected]:USERNAME/REPOSITORY.git

2. 솔루션 1: SSH 키 인증 설정

SSH 키는 Git 서비스와 인증하는 가장 안전하고 간소화된 방법을 제공하며, 초기 설정 후 추가적인 비밀번호 프롬프트가 필요하지 않습니다. 공개/개인 키 쌍을 사용합니다.

2.1 기존 SSH 키 확인

기계에 SSH 키 쌍이 이미 생성되었는지 확인하세요:

ls -al ~/.ssh

id_rsa, id_ed25519 또는 유사한 이름의 파일을 찾고 해당 .pub 파일(공개 키)과 쌍을 이루는 것을 확인하세요.

2.2 새 SSH 키 쌍 생성

적절한 키가 없는 경우 새 키를 생성하세요. Ed25519는 권장되는 최신 알고리즘이며, RSA 4096비트도 안전합니다.

# Ed25519 키 생성
ssh-keygen -t ed25519 -C "[email protected]"

# 프롬프트에 따르세요. 강력한 암호를 사용하는 것이 좋습니다.

2.3 Git 호스트에 공개 키 등록

공개 키를 Git 호스트(예: GitHub 설정, GitLab 설정)에 등록해야 합니다.

  1. 공개 키 내용을 클립보드에 복사합니다:
    bash cat ~/.ssh/id_ed25519.pub
  2. 호스팅 서비스의 설정으로 이동하여 SSH 키 섹션을 찾습니다.
  3. 공개 키 파일의 전체 내용을 키 등록 필드에 붙여넣습니다.

2.4 SSH 연결 테스트

등록 후 호스트가 키를 인식하는지 확인하기 위해 연결을 테스트하세요. 필요한 경우 github.com을 바꿔 다음 명령을 사용하세요:

ssh -T [email protected]

성공하면 Hi USERNAME! You've successfully authenticated...와 같이 인증이 확인되었다는 환영 메시지가 표시됩니다.

팁: 연결이 실패하면 SSH 에이전트가 실행 중이고 키가 로드되었는지 확인하세요. eval "$(ssh-agent -s)" 다음에 ssh-add ~/.ssh/id_ed25519(또는 키 경로)를 사용하세요.

3. 솔루션 2: HTTPS용 개인 액세스 토큰(PAT) 사용

HTTPS 원격 URL을 계속 사용하고 싶거나(또는 SSH 사용이 제한된 경우) 계정 비밀번호 대신 개인 액세스 토큰(PAT)을 사용해야 합니다. 2021년부터 주요 플랫폼에서 필수 요구 사항입니다.

3.1 개인 액세스 토큰 생성

PAT는 Git 호스트의 보안 설정 내에서 직접 생성됩니다.

  1. 설정으로 이동: 프로필 설정에서 일반적으로 개발자 설정 또는 액세스 토큰 아래로 이동합니다.
  2. 새 토큰 생성: 설명적인 이름을 제공하고 만료 날짜를 설정합니다(만료 날짜 설정은 모범 사례입니다. 예를 들어 90일).
  3. 범위 정의: 중요한 것은 필요한 권한(범위)을 할당하는 것입니다. 일반적인 저장소 액세스의 경우 일반적으로 repo 범위가 필요합니다.
  4. 토큰 저장: 생성되면 즉시 토큰을 복사하세요. 다시 표시되지 않습니다.

경고: PAT는 비밀번호처럼 취급하세요. 노출되면 할당한 범위에 대한 전체 액세스 권한이 부여됩니다.

3.2 PAT 사용

HTTPS를 통해 Git 작업을 수행할 때 사용자 이름과 비밀번호를 입력하라는 메시지가 표시됩니다.

프롬프트 입력할 값
Username: 실제 Git 사용자 이름
Password: 전체 개인 액세스 토큰(PAT) 문자열

입력하면 Git은 일반적으로 자격 증명 도우미를 사용하여 이 토큰을 안전하게 저장합니다(섹션 4 참조).

4. 자격 증명 도우미를 사용한 자격 증명 관리

긴 PAT를 반복해서 입력하는 것은 비실용적입니다. Git의 자격 증명 도우미는 인증 세부 정보를 안전하게 캐시하거나 저장하여 한 번만 입력하면 되도록 합니다.

4.1 기본 자격 증명 도우미 구성

자격 증명 도우미는 Git이 인증 정보를 저장하는 방법을 관리합니다. 가장 안전한 방법은 운영 체제의 기본 보안 저장소를 활용합니다.

macOS의 경우: 키체인 액세스 도우미를 사용합니다(기본적으로 활성화된 경우가 많음):

git config --global credential.helper osxkeychain

Windows의 경우: Windows 자격 증명 관리자를 사용합니다:

git config --global credential.helper manager

Linux의 경우: cache 도우미는 자격 증명을 일시적으로 저장할 수 있지만 store 도우미는 암호화되지 않은 상태로 저장합니다(주의하여 사용).

# 1시간(3600초) 동안 메모리에 자격 증명을 캐시합니다.
git config --global credential.helper 'cache --timeout=3600'

4.2 저장된 자격 증명 재설정

인증 오류가 계속되면 기존에 저장된(하지만 유효하지 않은) 자격 증명이 문제의 원인일 가능성이 높습니다. Git이 PAT를 다시 입력하도록 강제하려면 저장된 자격 증명을 지워야 합니다.

macOS 키체인을 사용하는 경우:

  1. 키체인 액세스 응용 프로그램을 엽니다.
  2. github.com 또는 Git 호스트를 검색합니다.
  3. 해당 인터넷 비밀번호 항목을 삭제합니다.

Windows 자격 증명 관리자를 사용하는 경우:

  1. 제어판을 열고 자격 증명 관리자로 이동합니다.
  2. Windows 자격 증명 아래에서 git:https://... 또는 호스트 도메인과 관련된 일반 자격 증명을 찾습니다.
  3. 항목을 제거합니다.

이전 자격 증명을 지운 후 다음 Git 작업(예: git pull)은 새 PAT를 입력하라는 메시지를 표시하며, 도우미는 이를 안전하게 저장합니다.

요약 및 다음 단계

지속적인 Git 인증 오류를 해결하는 것은 SSH 키 또는 PAT라는 최신 지원 자격 증명 유형을 원격 URL 프로토콜(SSH 또는 HTTPS)과 일치하도록 보장하는 것으로 귀결됩니다.

| 오류가 지속되면... | 조치 |
| :--- |
| 403 Forbidden | PAT 범위 확인 또는 호스트에서 SSH 키 권한 확인. |
| 반복적인 프롬프트(HTTPS) | 개인 액세스 토큰(PAT)을 생성하고 자격 증명 도우미가 올바르게 저장하고 있는지 확인. |
| SSH 키 실패 | 공개 키가 등록되었는지, ssh-agent가 실행 중이고 개인 키가 로드되었는지 확인. |

이 단계를 따르면 자격 증명 오류를 제거하여 더 원활하고 안전한 Git 워크플로우를 만들 수 있습니다.