기술 · 실용 가이드
SSH agent refused operation? 초기화 전에 소켓·키·서명 경로를 증명하세요
이 오류는 클라이언트가 에이전트에 도달했지만 서명을 완료하지 못했다는 뜻입니다. 실제 소켓, 키 지문, 로컬 서명 가능성, SSH의 선택 경로를 확인한 뒤 권한·포워딩·하드웨어 토큰을 수정하세요.
‘agent refused operation’은 일반적인 공개 키 실패보다 범위가 좁습니다. SSH 클라이언트가 인증 에이전트에 연결하고 공개 키를 골라 인증 요청 서명을 요구했지만 유효한 서명을 받지 못했습니다. 잘못된 에이전트, 다른 키, 승인 대기, 포워딩 소켓 가림, 하드웨어 토큰 상태가 원인일 수 있습니다.
먼저 키나 설정을 삭제하거나, 에이전트 보호를 끄거나, 개인 키를 원격 호스트에 복사하거나, 모든 호스트에 ForwardAgent를 켜지 마세요. 실패한 같은 터미널에서 첫 번째로 깨지는 경계를 찾습니다.
1. 실패한 세션에서 에이전트 확인
오류가 난 같은 터미널, IDE 셸 또는 원격 세션에서 확인합니다. 호스트 별칭, 포워딩 여부, 오류 직전의 키 레이블을 기록하세요.
`printf '%s\n' "$SSH_AUTH_SOCK"`와 `test -n "$SSH_AUTH_SOCK" && test -S "$SSH_AUTH_SOCK" && echo agent-socket-present`로 소켓을 확인합니다. 경로가 있어도 OpenSSH, GNOME Keyring, gpg-agent, 1Password, KeePassXC, 하드웨어 또는 포워딩 에이전트 중 무엇인지는 별도 확인이 필요합니다.
`ssh-add -l`로 지문을, `ssh-add -L`로 공개 키를 봅니다. 종료 코드 2는 에이전트에 접속하지 못했다는 뜻이며 키나 서버가 틀렸다는 증거가 아닙니다.
2. 지문을 맞추고 서명 가능성을 검증
설명 문자열 대신 지문을 비교합니다. 공개 키에는 `ssh-keygen -lf ~/.ssh/id_ed25519.pub`, 에이전트에는 `ssh-add -l -E sha256`를 사용합니다. SSH가 제시한 지문이 목록에 없으면 로딩이나 서드파티 에이전트의 키 범위를 먼저 수정합니다.
지문이 있으면 `ssh-add -T ~/.ssh/id_ed25519.pub`를 실행합니다. 현재 OpenSSH는 서명을 요청하고 결과를 검증합니다. 실패하면 잠금, 승인 창, pinentry, 터치/PIN, provider 로그를 확인합니다.
오래된 ssh-add에는 -T가 없거나 서드파티 에이전트가 일부만 지원할 수 있습니다. 알 수 없는 옵션을 서명 실패로 오해하지 말고 `ssh -V`와 제품명을 기록해 공식 테스트를 사용하세요.
3. SSH가 실제로 고른 경로 확인
`ssh -G your-host | grep -Ei '^(identityagent|identityfile|identitiesonly|forwardagent) '`로 호스트 별칭의 최종 설정을 봅니다. Host, Match, Include가 기억과 다른 결과를 만들 수 있습니다.
한 번 `ssh -vvv user@your-host`를 실행해 에이전트, 제시한 지문, 거부 줄을 찾습니다. -T를 통과한 키와 다르면 그 호스트의 IdentityFile/IdentityAgent만 수정합니다.
IdentityAgent는 SSH_AUTH_SOCK보다 우선할 수 있습니다. 원격 워크스테이션의 로컬 서드파티 설정이 노트북에서 포워딩된 소켓을 가릴 수 있으므로 세션 또는 호스트별 경로를 고치고 개인 키는 복사하지 마세요.
4. 첫 실패 경계에 따라 분기
소켓이 없거나 접속 불가: 이 세션에서 의도한 에이전트를 시작하거나 다시 연결하고 다른 로그인 세션의 오래된 소켓은 쓰지 않습니다.
키가 목록에 없음: 공식 방식으로 대상 키만 로드하거나 서드파티 에이전트에서 사용 가능하게 합니다. 명확한 권한 경고가 있을 때만 해당 개인 키를 수정하고 디렉터리 전체에 같은 chmod를 적용하지 않습니다.
키가 있지만 -T 실패: 잠금, 승인, pinentry, 터치/PIN, provider와 같은 시각의 로그를 확인합니다.
-T 성공 후 SSH 거부: 실제 지문과 IdentityAgent, 포워딩/목적지 제약, 요청을 보낸 터미널 또는 IDE 승인을 확인합니다.
같은 키가 서명되고 SSH가 제시했는데 서버가 거부: 사용자, authorized_keys, 인증서 principal, 서버 정책으로 이동합니다.
5. 포워딩과 하드웨어 키 보호 유지
에이전트 포워딩은 개인 키가 아니라 서명 능력을 전달합니다. 신뢰하는 호스트에만 제한하고 키를 가진 로컬 기기에서 승인합니다.
FIDO/PKCS#11 거부는 의도된 보안 경계일 수 있습니다. 터치, PIN, provider, 목적지 제약을 확인하고 web-safety 제한을 끄지 마세요.
수정 후 같은 ssh-add -T와 ssh -vvv를 반복하고 작동한 소켓, 지문, 최종 설정을 기록합니다.
결정표
ssh-add가 에이전트에 연결하지 못함 — 소켓 또는 세션 장애. 의도한 에이전트를 시작하거나 다시 연결하고 SSH_AUTH_SOCK 재확인
ssh-add -l에 대상 키가 없음 — 잘못된 에이전트 또는 키 사용 불가. 의도한 ID만 로드하거나 설정
키가 보이지만 ssh-add -T 실패 — 에이전트/provider가 지금 서명할 수 없음. 잠금 해제, 승인, 터치 또는 PIN 후 provider 로그 확인
ssh-add -T는 통과하지만 SSH가 다른 키 제시 — 클라이언트 라우팅 불일치. ssh -G와 ssh -vvv를 확인하고 해당 호스트의 IdentityAgent/IdentityFile 수정
ssh-add -T 통과, 같은 키 제시, 서버 거부 — 서버 권한 분기. 사용자, authorized_keys, 인증서 principals, 서버 정책 확인
