Jenkins SSH Credentials 설정

Jenkins에서 SSH로 배포 서버에 접속하려는데 Auth fail 에러가 발생한다면, SSH 키 설정이 제대로 되어 있는지 확인해야 합니다.

문제 상황

Jenkins에서 Publish Over SSH 플러그인을 사용하여 배포 서버를 등록하고, Test Configuration 을 실행했을 때 아래와 같은 에러가 발생할 수 있습니다.

jenkins.plugins.publish_over.BapPublisherException: Failed to connect and initialize SSH connection.
Message: [Failed to connect session for config [${config-name}].
Message [Auth fail for methods 'publickey,gssapi-keyex,gssapi-with-mic,password']]

이 에러는 Jenkins가 대상 서버에 SSH 인증을 시도했지만, 모든 인증 방식(공개키, GSSAPI, 패스워드)이 실패했음을 의미합니다. 대부분의 경우 SSH 키가 올바르게 생성/등록되지 않았거나, 파일 권한에 문제가 있습니다.

SSH 키 생성 및 등록

RSA 방식

# 키 생성 (4096비트)
ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_rsa

# 공개키를 대상 서버의 authorized_keys에 등록
cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

# Jenkins에서 사용하려면 PEM 포맷으로 변환 필요 (OpenSSH 7.8+)
ssh-keygen -p -m PEM -f ~/.ssh/id_rsa

ECDSA 방식

# 키 생성 (521비트)
ssh-keygen -t ecdsa -b 521 -f ~/.ssh/id_ecdsa

# 공개키를 대상 서버의 authorized_keys에 등록
cat ~/.ssh/id_ecdsa.pub >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

RSA vs ECDSA 비교

팁: Jenkins Publish Over SSH 플러그인은 내부적으로 JSch 라이브러리를 사용합니다. JSch의 버전에 따라 지원하는 키 형식이 다를 수 있으므로, RSA + PEM 포맷이 가장 범용적입니다.

인증 실패 디버깅 절차

키를 정상적으로 생성하고 등록했음에도 인증이 실패하는 경우, 아래 순서대로 점검합니다.

Step 1: SSH 직접 접속 테스트

# 상세 디버그 모드로 SSH 접속 시도
ssh -i ~/.ssh/id_rsa -vvv user@target-server

이 명령어로 접속 시도 시 패스워드 인증으로 넘어간다면, 공개키 인증이 정상적으로 동작하지 않는 것입니다.

Step 2: authorized_keys 파일 확인

# 대상 서버에서 확인
ls -la ~/.ssh/authorized_keys

# 파일이 없으면 생성
touch ~/.ssh/authorized_keys

# 공개키가 등록되어 있는지 확인
cat ~/.ssh/authorized_keys

Step 3: 파일/디렉토리 권한 확인

SSH는 보안상 파일 권한이 올바르지 않으면 키 인증을 거부합니다.

# 소유자도 올바른지 확인
chown -R $USER:$USER ~/.ssh

Step 4: Jenkins에서 재시도

위 점검을 완료한 후, Jenkins의 Manage Jenkins > System > SSH Servers 에서 Test Configuration 을 다시 실행합니다. Success가 표시되면 정상적으로 연결된 것입니다.

Jenkins에 Credential 등록

SSH 키 인증이 정상 동작하는 것을 확인한 후, Jenkins에 Credential을 등록합니다.

1. Manage Jenkins > Credentials > System > Global credentials
2. Add Credentials 클릭
3. 아래 항목 입력:

** 주의:** 비밀키를 입력할 때 -----BEGIN RSA PRIVATE KEY-----부터 -----END RSA PRIVATE KEY-----까지 전체 내용을 빠짐없이 붙여넣어야 합니다.

주의할 점

OpenSSH 7.8+ PEM 포맷 필수

OpenSSH 7.8 이후 버전에서 ssh-keygen으로 생성한 RSA 키는 기본적으로 OpenSSH 포맷입니다. Jenkins의 JSch 라이브러리는 이 포맷을 인식하지 못할 수 있으므로, ssh-keygen -p -m PEM -f ~/.ssh/id_rsa로 PEM 포맷으로 변환해야 합니다.

파일 권한이 느슨하면 키 인증 거부

SSH는 보안상 .ssh 디렉토리(700)와 authorized_keys(600)의 권한이 올바르지 않으면 키 인증을 조용히 거부합니다. 에러 로그 없이 패스워드 인증으로 넘어가므로, 원인을 파악하기 어렵습니다.

정리