テクノロジー · 実用ガイド
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も提示した後のPermission deniedはサーバー認可の問題です。ユーザー、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、サーバーポリシーを確認
