Tecnología · GUÍA PRÁCTICA
¿SSH agent refused operation? Demuestra el socket, la clave y la ruta de firma
El cliente llegó a un agente, pero este no completó la firma. Identifica el socket activo, compara la huella, prueba la firma local y verifica la ruta real de SSH antes de cambiar permisos, borrar claves o tocar el reenvío.
“Agent refused operation” es más concreto que un fallo genérico de clave pública. El cliente SSH contactó con un agente, eligió una clave pública y pidió firmar el desafío de autenticación, pero no recibió una firma utilizable. Puede estar usando otro agente, otra clave, una aprobación pendiente, un socket reenviado oculto o un token que no puede firmar ahora.
No empieces borrando claves o configuración, desactivando protecciones, copiando una clave privada al servidor ni habilitando ForwardAgent para todos los hosts. Conserva la terminal que falla y localiza el primer límite que no supera la prueba.
1. Mantén el contexto e identifica el agente
Haz las pruebas en la misma terminal, shell del IDE o sesión remota que produjo el error. Anota el alias del host, si hay reenvío de agente y la etiqueta de clave mostrada antes del rechazo.
Ejecuta `printf '%s\n' "$SSH_AUTH_SOCK"` y `test -n "$SSH_AUTH_SOCK" && test -S "$SSH_AUTH_SOCK" && echo agent-socket-present`. Un socket existente puede pertenecer a OpenSSH, GNOME Keyring, gpg-agent, 1Password, KeePassXC, un token o una sesión reenviada.
Usa `ssh-add -l` para las huellas y `ssh-add -L` para las claves públicas. El código de salida 2 significa que ssh-add no pudo contactar con el agente: es un problema de socket o sesión.
2. Compara la huella y demuestra que puede firmar
No confíes en el comentario de la clave. Ejecuta `ssh-keygen -lf ~/.ssh/id_ed25519.pub` para el archivo y `ssh-add -l -E sha256` para el agente. Si la huella ofrecida por SSH no aparece, corrige la carga o elegibilidad antes de tocar el servidor.
Si aparece, ejecuta `ssh-add -T ~/.ssh/id_ed25519.pub`. OpenSSH actual pide una firma y la verifica. Si falla, investiga bloqueo, ventana de aprobación, pinentry, toque/PIN y el registro del provider.
Versiones antiguas pueden no tener -T y algunos agentes de terceros implementan solo parte del protocolo. Una opción desconocida no es una firma fallida; registra `ssh -V` y usa la prueba oficial del producto.
3. Demuestra qué selecciona realmente SSH
Ejecuta `ssh -G your-host | grep -Ei '^(identityagent|identityfile|identitiesonly|forwardagent) '` para ver la configuración efectiva del alias. Host, Match e Include pueden cambiar el resultado final.
Después ejecuta una vez `ssh -vvv user@your-host` y localiza el agente, la huella ofrecida y la línea de rechazo. Si la huella difiere de la que superó -T, corrige solo IdentityFile/IdentityAgent para ese host.
IdentityAgent puede tener prioridad sobre SSH_AUTH_SOCK. En una sesión reenviada, un agente local del equipo remoto puede ocultar el socket del portátil; corrige la ruta específica y no copies la clave privada.
4. Sigue la primera prueba que falla
Sin socket o sin contacto: inicia o reconecta el agente previsto en esta sesión; no reutilices un socket antiguo de otro inicio de sesión.
Clave ausente: carga solo la identidad prevista o hazla elegible en el agente de terceros. Cambia permisos únicamente si hay una advertencia explícita sobre el archivo privado; no apliques el mismo chmod a todo el directorio.
Clave presente pero -T falla: revisa bloqueo, aprobación, pinentry, toque/PIN, provider y registros del mismo momento.
-T funciona pero SSH rechaza: compara huella e IdentityAgent; con reenvío o restricciones de destino, comprueba cada salto y autoriza la terminal o IDE que solicita la firma.
La misma clave firma y SSH la ofrece, pero el servidor responde Permission denied: revisa usuario, authorized_keys, principals del certificado y política del servidor.
5. Conserva la seguridad del reenvío y del hardware
El reenvío transmite capacidad de firma, no la clave privada. Limita ForwardAgent a hosts de confianza y aprueba en el equipo que posee la clave.
Un rechazo FIDO o PKCS#11 puede ser una barrera deliberada. Puede requerir toque, PIN, provider o permiso de destino. No desactives protecciones web ni cargues providers remotos solo para ocultar el error.
Tras corregirlo, repite los mismos ssh-add -T y ssh -vvv y registra socket, huella y configuración efectiva que funcionaron.
Tabla de decisión
ssh-add no puede contactar con el agente — Fallo de socket o sesión. Inicia o reconecta el agente previsto y vuelve a comprobar SSH_AUTH_SOCK
La clave no aparece en ssh-add -l — Agente incorrecto o clave no disponible. Carga o configura únicamente la identidad prevista
La clave aparece, pero ssh-add -T falla — El agente/provider no puede firmar ahora. Desbloquea, aprueba, toca o introduce el PIN; revisa los registros del provider
ssh-add -T funciona, pero SSH ofrece otra clave — Ruta del cliente incorrecta. Revisa ssh -G y ssh -vvv; corrige IdentityAgent/IdentityFile para ese host
ssh-add -T funciona, ofrece la misma clave y el servidor rechaza — Rama de autorización del servidor. Revisa usuario, authorized_keys, principals del certificado y política del servidor
