Uso de una clave SSH con GitHub
Equipo editorial de IONOS
El uso de una SSH key con GitHub permite el acceso sin contraseña a los repositorios Git por SSH. En lugar de identificar a un usuario por su nombre de usuario y contraseña, la máquina del desarrollador se autentifica a través de la clave SSH.
Convéncete por ti mismo y elige un servidor virtual.
¿Qué es una clave SSH?
SSH es la herramienta estándar para el acceso cifrado a sistemas remotos. SSH te permite iniciar sesión en un servidor desde otro equipo. Git utiliza SSH como protocolo de transferencia y permite el acceso de lectura y escritura a los repositorios remotos.
Se utiliza una conexión encriptada para permitir la autenticación de la máquina y garantizar que los datos transmitidos no puedan ser falsificados. Sin esto, sería posible que personas no autorizadas hicieran cambios arbitrarios en los repositorios.
Git vía SSH utiliza cifrado asimétrico como método de encriptación. En primer lugar, se crean un par de claves privadas y públicas. También se denomina “Public-Private Keypair”. La clave privada permanece en el propio ordenador del usuario. La clave pública se comparte con terceros, por ejemplo, GitHub.
Si utilizas una clave SSH para acceder a los repositorios de GitHub, no necesitas introducir una contraseña. En general, el inicio de sesión sin contraseña se considera más seguro, ya que los keyloggers o troyanos no pueden capturar ninguna contraseña. En lugar de que una persona conozca la contraseña, se autentifica una máquina en la que se almacena la clave privada.
El uso de Git a través de SSH es extremadamente práctico. Una vez configurada, la clave SSH permite el acceso permanente a GitHub sin más intervención. Otros protocolos y servicios también se benefician de las claves SSH para una conexión de red encriptada. Además de Git vía SSH, se puede utilizar el protocolo seguro SFTP para intercambiar archivos con los servidores sin necesidad de ninguna otra configuración.
La conexión a los repositorios Git se realiza normalmente desde la línea de comandos. Si has configurado una clave SSH, puedes realizar un push al propio repositorio sin problemas:
cd ./carpeta_con_repositorio_git/
git pushAdemás de la aplicación de línea de comandos, las aplicaciones de interfaz gráfica de usuario también se benefician de tener una clave SSH configurada. Los programas FTP modernos soportan el protocolo de transferencia de archivos vía SSH (SFTP por sus siglas en inglés), que se basa en SSH y utiliza las claves SSH existentes.
Cómo utilizar las claves SSH con GitHub
Para acceder con una clave SSH o SSH key a GitHub, debes depositar la clave pública en GitHub. La clave privada permanece en tu propio ordenador. La máquina en la que trabajas se autentifica en GitHub comparando los datos de la clave. Esto te permite tener acceso de escritura a tus propios repositorios. Este método también funciona con alternativas a GitHub como Gitlab o Bitbucket.
Por muy prácticas que sean las claves SSH, hay que tener cuidado al manejarlas. No compartas tu clave privada en ninguna circunstancia. La clave privada puede permitir que otra persona se haga pasar por ti y podría entrar en un servidor o cambiar el código en los repositorios en tu nombre.
Requisitos para utilizar GitHub con la clave SSH
Este artículo está orientado a quienes trabajan en un entorno tipo Linux. Esto incluye Linux/Unix, macOS, así como Windows con WSL2 instalado. Además, deben cumplirse las siguientes condiciones:
- Git instalado
- SSH instalado
- Cuenta de GitHub creada
Primero, hay que asegurarse de que se cumplen los requisitos locales. Con el siguiente comando comprueba si Git y SSH están instalados. A menos que recibas un mensaje de error “git not found” o “git not found”, ambos están presentes:
which git ssh
Además, crea el directorio .ssh en la carpeta del usuario si no existe ya:
mkdir -vp ~/.ssh/A continuación, descubre cómo generar una clave SSH y registrarla, con el comando de ssh-keygen en GitHub. Una vez completado este paso, podrás ver cómo depositar la clave SSH pública en GitHub y cómo acceder a los repositorios Git a través de SSH:
- Crear un par de claves SSH en tu propio sistema
- Depositar la clave SSH pública en GitHub
- Acceder al repositorio de GitHub con la clave SSH
Crear y registrar la clave SSH en tu propio sistema
Como primer paso, crea un par de claves SSH públicas y privadas en nuestro sistema local. Copia los comandos utilizados en el mismo orden y ejecútalos en tu línea de comandos. Para ello, sigue la documentación oficial de GitHub. El procedimiento cambia de vez en cuando. Así que para solucionar errores de SSH no está de más revisar la página cada cierto tiempo.
En primer lugar, iniciamos el generador de claves SSH para crear un par de claves públicas/privadas para GitHub. Utiliza el comando ssh-keygen, que está disponible en el sistema por defecto como parte de la instalación de OpenSSH.
Teclea ssh-keygen en la línea de comandos e inseta tres opciones:
- Opción -f seguida de la ruta y el nombre de la nueva clave
- Opción -t seguida del nombre del algoritmo, en este caso ed25519
- Opción -C seguida de una dirección de correo electrónico como comentario
ssh-keygen -f "$HOME/.ssh/github_id_ed25519" -t ed25519 -C "correo_de_ejemplo@ejemplo.es"Puedes utilizar cualquier dirección de correo electrónico para generar el par de claves. Esto sirve solo como etiqueta; no tiene que ser la misma dirección que usas para iniciar sesión en GitHub.
El comando ssh-keygen pide que especifiques una “frase de contraseña” para la clave privada. A diferencia de una contraseña normal, una frase de contraseña puede contener espacios. La frase de contraseña debe tener varias palabras, para que sea fácil de recordar y difícil de adivinar. Para mayor seguridad, incluye algunos números o caracteres especiales. Escribe la frase de contraseña y pulsa "Intro". Repite el proceso para completar la creación del par de claves SSH.
USA el algoritmo Ed25519 para el par de claves. De hecho, hay toda una gama de algoritmos disponibles. Descubre los métodos de encriptado de un vistazo en un artículo aparte.
Antes de poder utilizar la clave SSH recién creada con GitHub, realiza otro paso. Esto es opcional, pero muy recomendable. Añade la clave privada al llamado “SSH-Agent” o agente SSH. Se trata de un programa en segundo plano que se ejecuta en el sistema local. Teclea el siguiente comando en la línea de comandos y escribe la frase de contraseña cuando se te pida:
- Windows / Linux
ssh-add ~/.ssh/github_id_ed25519- macOS hasta 11 Big Sur
ssh-add -K ~/.ssh/github_id_ed25519- macOS desde 12 Monterey
ssh-add --apple-use-keychain ~/.ssh/github_id_ed25519El agente SSH tiene acceso a las claves privadas añadidas y permite utilizarlas para las conexiones sin tener que introducir la frase de contraseña cada vez. Pero el agente SSH puede hacer aún más:
“ssh-agent is a program that can hold a user's private key, so that the private key passphrase only needs to be supplied once. A connection to the agent can also be forwarded when logging into a server, allowing SSH commands on the server to use the agent running on the user's desktop”. Fuente: https://www.ssh.com/academy/ssh/keygen#adding-the-key-to-ssh-agent
Traducción: “ssh-agent es un programa que puede mantener la clave privada de un usuario, de modo que la frase de contraseña de la clave privada solo tiene que suministrarse una vez. También se puede reenviar una conexión al agente cuando se inicia la sesión en un servidor, lo que permite que los comandos SSH en el servidor utilicen el agente que se ejecuta en el escritorio del usuario.” (traducido por IONOS)
Depositar la clave SSH en GitHub
Has creado un par de de claves SSH en nuestro sistema local. Con esto, la mitad de la comunicación permanece encriptada cuando se utiliza Git por SSH. A continuación, hay que depositar la clave SSH pública en GitHub.
Ahora necesitas el contenido de la clave pública. Pasa a tu línea de comandos local y teclea el siguiente comando:
cat ~/.ssh/github_id_ed25519.pubAtención: el nombre de archivo de una clave pública termina en .pub para “clave pública”. Sin embargo, la clave privada no termina en .priv. En cambio, la clave privada no tiene extensión. Comparte únicamente la clave pública con GitHub y otras personas.
Acceder al repositorio de GitHub con la clave SSH
Tras haber generado las claves SSH de forma local y depositado la clave pública en GitHub, hay que probar si la conexión funciona. Para ello recurre al siguiente comando:
ssh -T git@github.com
Si es la primera vez que te conectas a GitHub desde esa máquina, también tendrás que añadir el servidor a los “known hosts” o hosts conocidos:
Al acceder a los repositorios de GitHub, se distingue entre acceso de lectura y de escritura. Cualquiera puede leer los repositorios públicos; no se requiere autenticación, es decir, no se necesita una clave SSH.
Para descargar un repositorio como copia local, usa el comando git clone. A continuación, se presenta un ejemplo con el repositorio de la popular herramienta de red cURL. Accede a la página de GitHub del repositorio público repositorio cURL y copia la URL del clon:
Equipados con la URL del clon, se vuelve a la línea de comandos local. Crea un repositorio de carpetas de ejemplo en el escritorio y pasa a trabajar en él. A continuación, hay que clonar el repositorio cURL usando git clone con la URL de clonación:
cd ~/Desktop/
mkdir -p repo && cd repo
git clone https://github.com/curl/curl.git
Pasa a la carpeta del repositorio cURL y usa el comando git status para mostrar el estado del repositorio:
cd ~/Desktop/repo/curl/
git status
El comando git pull, que actualiza un repositorio, también requiere un acceso de solo lectura. Para ello, ejecuta git pull en la carpeta del repositorio; en principio esto funciona, aunque probablemente no haya aún cambios:
git pullIntenta escribir en el repositorio de GitHub utilizando el comando git push:
git push¿Por qué sucede esto? La URL de clonación utilizada para clonar el repositorio público cURL comienza con HTTPS. En consecuencia, para el clon local, una URL HTTPS se almacena como “Origin” u origen. Pasa a comprobar el origen con el comando git show::
git remote -v show
Para el acceso de lectura, una URL HTTPS es suficiente, pero se necesita una clave SSH para escribir en los repositorios de GitHub. Esto se debe a que la autenticación de usuarios por nombre de usuario/contraseña no se admite en GitHub desde agosto de 2021.
Para probar git push de todas formas, hay un truco. Primero, crea en GitHub un repositorio vacío:
Siguiendo las instrucciones de GitHub, hay que cambiar la URL push del clon local de cURL en nuestro sistema para utilizar nuestro repositorio vacío de GitHub como origen. También establece la rama como “main” o principal. A continuación, ejecuta git push; la operación se completa con éxito y utiliza la clave SSH previamente creada para la autenticación en GitHub.
git remote set-url origin git@github.com:<user>/test.git</user>
git branch -M main
git push -u origin main
Utilizar varias claves SSH para diferentes cuentas de GitHub
Es posible utilizar una sola clave SSH para diferentes cuentas de GitHub u otras cuentas sin ningún problema. Recuerda: puedes compartir la clave pública.
Técnicamente, puedes utilizar tus propias claves SSH para diferentes servicios. Hay dos métodos posibles:
- Usar el comando SSH con parámetros
- Crear archivo de configuración SSH
Los comandos SSH con parámetros pueden resultar muy largos, por lo que no mostramos este enfoque aquí. En general, es más conveniente trabajar con un archivo de configuración SSH. Esto requiere un poco más de esfuerzo en la configuración de tu propio sistema, pero solo tienes que hacerlo una vez. A continuación, se muestra un resumen de las carpetas y archivos que intervienen en la configuración de SSH:
| Configuración SSH | Ruta | Aclaración |
|---|---|---|
| Carpeta de configuración | ~/.ssh/ | Contiene la configuración de SSH y los pares de claves |
| Clave privada | ~/.ssh/key-name | Clave privada de un par de claves |
| Clave pública | ~/.ssh/key-name.pub | Clave pública de un par de claves |
| Archivo de configuración | ~/.ssh/config | Archivo de configuración SSH |
| Hosts conocidos | ~/.ssh/known_hosts | Lista de hosts conectados en el pasado |
Primero crea el archivo de configuración SSH. Establece los derechos de usuario y abre el archivo en el editor de línea de comandos:
touch ~/.ssh/config
chmod 600 ~/.ssh/config
nano ~/.ssh/configA continuación, copia el siguiente bloque en el editor y sigue las capturas de pantalla para guardar el archivo:
# Github
Host github github.com
HostName github.com
User git
IdentityFile "~/.ssh/github_id_ed25519"
IdentitiesOnly yes
Después de insertar el bloque de configuración de GitHub, puedes establecer una conexión SSH especificando la abreviatura de host definida “github”:
ssh -T githubSigue el esquema mostrado y añade bloques de configuración para servicios o cuentas adicionales al archivo de configuración SSH. A continuación, tienes un resumen de los parámetros utilizados:
| Configuración | Explicación | Ejemplo |
|---|---|---|
| Host | Puede contener cualquier número de nombres | github.com github |
| HostName | Nombre de host del sistema remoto en el que se está ejecutando SSH; también se puede utilizar una dirección IP | github.com |
| User | Usuario Git en el sistema remoto; debe ser copiado exactamente | git |
| IdentityFile | Ruta completa a la clave privada. Ajústala si utiliza varias teclas | ~/.ssh/github_id_ed25519 |
| IdentitiesOnly | Especifica que el acceso para este host solo se permite por clave | yes |
Un último consejo. Si creas configuraciones SSH para varios hosts con tus propias claves, debes añadir un bloque con configuraciones para hosts no listados al final del archivo:
# For all hosts
Host *
IdentitiesOnly no
IgnoreUnknown UseKeychain, AddKeysToAgent
UseKeychain yes
AddKeysToAgent yesEsto permite el acceso sin una clave SSH a hosts no especificados. Así, puedes conectarte a un host a través del comando SSH con tu nombre de usuario e introducir la contraseña al conectarse:
ssh user@hostSin la línea “IdentitiesOnly no” en la configuración final, SSH intenta todas las claves en ~./ssh/ una tras otra para conectarse al servidor. Si no hay ninguna clave que coincida, se produce el error “Too many authentication failures”, que refleja “Demasiados fallos de autenticación”.
