Centro de Conocimiento DevOps
Centro de Conocimiento DevOps

Resolviendo Errores Comunes de Autenticación de Git Usando SSH y Tokens

¿Luchando con errores persistentes de autenticación de Git como 403 Forbidden o solicitudes repetidas de credenciales? Esta guía proporciona soluciones expertas para dejar de usar los inicios de sesión con contraseña obsoletos. Aprenda la configuración segura para claves SSH, cómo generar y usar Tokens de Acceso Personal (PATs) para HTTPS, y las mejores prácticas para configurar los asistentes de credenciales nativos del sistema operativo en macOS, Windows y Linux. Implemente estos pasos para asegurar su conexión y resolver los problemas de autenticación de forma permanente.

45 vistas

Solución a errores comunes de autenticación de Git usando SSH y Tokens

Los errores de autenticación son una fuente común de frustración para los usuarios de Git, especialmente al clonar, extraer o enviar código. Los fallos persistentes, que a menudo se manifiestan como fatal: Authentication failed (autenticación fallida) o mensajes 403 Forbidden (prohibido), indican que Git no puede verificar de forma segura tu identidad con el servicio de alojamiento remoto (como GitHub, GitLab o Bitbucket).

Esta guía completa aborda las razones principales detrás de estos fallos. Iremos más allá de las simples solicitudes de nombre de usuario/contraseña —que ahora están en gran medida obsoletas— para centrarnos en métodos de autenticación modernos y seguros: claves SSH y Tokens de Acceso Personal (PATs). Dominar estas técnicas es esencial para un flujo de trabajo de desarrollo fiable, asegurando que tus credenciales sean seguras y reconocidas correctamente por tu proveedor de Git.

1. Diagnóstico de Indicadores de Fallo de Autenticación

Antes de implementar una solución, es crucial comprender por qué Git está fallando. Los errores de autenticación suelen provenir de dos fuentes principales: credenciales caducadas o revocadas, o el uso del protocolo incorrecto (HTTPS vs. SSH) para las credenciales almacenadas.

Mensajes de Error Comunes

  • 403 Forbidden: Esto generalmente significa que tu intento de conexión tuvo éxito, pero las credenciales proporcionadas (contraseña o token) no tienen los permisos necesarios para completar la operación.
  • fatal: Authentication failed for 'https://...': Indica que Git intentó usar credenciales almacenadas (a menudo a través de un ayudante de credenciales) pero eran inválidas, o no se encontraron credenciales válidas.
  • Bucle de Solicitud de Contraseña: Si se te solicita repetidamente una contraseña a través de HTTPS, a menudo significa que tu proveedor de alojamiento ya no acepta contraseñas para operaciones de Git, requiriendo en su lugar un Token de Acceso Personal.

Identificación de tu Tipo de Conexión

Git se autentica de manera diferente según el esquema de la URL remota. Comprueba la URL remota de tu repositorio:

git remote -v

| Esquema de URL | Método de Autenticación Requerido |
| :--- | :-------------------------------- | |
| https://github.com/user/repo.git | Token de Acceso Personal (PAT) a través de HTTPS |
| [email protected]:user/repo.git | Par de Claves SSH |

Si tenías la intención de usar SSH pero la URL remota es HTTPS, o viceversa, debes cambiar la URL o cambiar los métodos de autenticación.

Para cambiar de HTTPS a SSH:

git remote set-url origin [email protected]:USERNAME/REPOSITORY.git

2. Solución 1: Establecimiento de Autenticación con Claves SSH

Las claves SSH proporcionan la forma más segura y optimizada de autenticarse con servicios de Git, sin requerir solicitudes de contraseña posteriores a la configuración inicial. Se basan en un par de claves pública/privada.

2.1 Verificación de Claves SSH Existentes

Verifica si ya tienes un par de claves SSH generado en tu máquina:

ls -al ~/.ssh

Busca archivos llamados id_rsa, id_ed25519 o similares, emparejados con un archivo .pub correspondiente (la clave pública).

2.2 Generación de un Nuevo Par de Claves SSH

Si no existe una clave adecuada, genera una nueva. Ed25519 es el algoritmo moderno recomendado, aunque RSA de 4096 bits también es seguro.

# Generar una clave Ed25519
ssh-keygen -t ed25519 -C "[email protected]"

# Sigue las indicaciones. Se recomienda encarecidamente utilizar una frase de contraseña segura.

2.3 Registro de la Clave Pública con tu Host de Git

La clave pública debe registrarse con tu host de Git (por ejemplo, la configuración de GitHub, la configuración de GitLab).

  1. Copia el contenido de la clave pública a tu portapapeles:
    bash cat ~/.ssh/id_ed25519.pub
  2. Navega a la configuración de tu servicio de alojamiento y encuentra la sección de Claves SSH.
  3. Pega todo el contenido del archivo de clave pública en el campo de registro de claves.

2.4 Prueba de la Conexión SSH

Después del registro, prueba la conexión para asegurarte de que el host reconoce tu clave. Utiliza el siguiente comando, reemplazando github.com si es necesario:

ssh -T [email protected]

Si tiene éxito, recibirás un mensaje de bienvenida que confirma tu autenticación, como: Hi USERNAME! You've successfully authenticated... (Hola NOMBRE_DE_USUARIO! Te has autenticado con éxito...)

Consejo: Si la conexión falla, asegúrate de que tu agente SSH esté en funcionamiento y haya cargado tu clave. Usa eval "$(ssh-agent -s)" seguido de ssh-add ~/.ssh/id_ed25519 (o la ruta de tu clave).

3. Solución 2: Uso de Tokens de Acceso Personal (PATs) para HTTPS

Si prefieres continuar usando URLs remotas HTTPS (o tienes restringido el uso de SSH), debes usar un Token de Acceso Personal (PAT) en lugar de la contraseña de tu cuenta. Este es un requisito crucial en las principales plataformas desde 2021.

3.1 Generación del Token de Acceso Personal

Los PAT se generan directamente dentro de la configuración de seguridad de tu host de Git.

  1. Navega a Configuración: Ve a la configuración de tu perfil, generalmente en Configuración del desarrollador o Tokens de acceso.
  2. Generar Nuevo Token: Proporciona un nombre descriptivo y establece una fecha de caducidad (es una buena práctica establecer una caducidad, por ejemplo, 90 días).
  3. Define Ámbitos (Scopes): Fundamentalmente, asigna los permisos necesarios (ámbitos). Para el acceso general al repositorio, normalmente necesitas el ámbito repo.
  4. Guarda el Token: Una vez generado, copia el token inmediatamente. No se volverá a mostrar.

Advertencia: Trata tu PAT como una contraseña. Si se ve comprometido, otorga acceso completo a los ámbitos que asignaste.

3.2 Uso del PAT

Al realizar una operación de Git a través de HTTPS, se te pedirá tu nombre de usuario y contraseña.

Solicitud Valor a Ingresar
Username: Tu nombre de usuario de Git real
Password: La cadena completa del Token de Acceso Personal (PAT)

Una vez introducido, Git generalmente almacenará este token de forma segura utilizando un ayudante de credenciales (ver Sección 4).

4. Gestión de Credenciales con Ayudantes de Credenciales

Introducir repetidamente PATs largos es poco práctico. Los ayudantes de credenciales de Git almacenan de forma segura tus detalles de autenticación para que solo tengas que introducirlos una vez.

4.1 Configuración del Ayudante de Credenciales Predeterminado

Los ayudantes de credenciales gestionan cómo Git guarda la información de tu autenticación. Los métodos más seguros utilizan el almacenamiento seguro del sistema operativo nativo.

Para macOS: Usa el ayudante de Acceso a Llaveros (a menudo habilitado por defecto):

git config --global credential.helper osxkeychain

Para Windows: Usa el Administrador de Credenciales de Windows:

git config --global credential.helper manager

Para Linux: El ayudante cache puede almacenar credenciales temporalmente, pero el ayudante store las almacena sin cifrar (úsalo con precaución).

# Almacena en caché las credenciales en memoria durante 1 hora (3600 segundos)
git config --global credential.helper 'cache --timeout=3600'

4.2 Restablecimiento de Credenciales Almacenadas

Si tus errores de autenticación persisten, es probable que la credencial almacenada existente (pero inválida) sea la culpable. Debes borrar las credenciales almacenadas para forzar a Git a solicitarte nuevamente el PAT.

Si usas el Llavero de macOS:

  1. Abre la aplicación Acceso a Llaveros.
  2. Busca github.com o tu host de Git.
  3. Elimina la entrada de contraseña de Internet correspondiente.

Si usas el Administrador de Credenciales de Windows:

  1. Abre el Panel de Control y navega al Administrador de Credenciales.
  2. En Credenciales de Windows, busca credenciales genéricas relacionadas con git:https://... o el dominio de tu host.
  3. Elimina la entrada.

Después de borrar las credenciales antiguas, la siguiente operación de Git (por ejemplo, git pull) te pedirá que introduzcas el nombre de usuario y el nuevo PAT, que el ayudante almacenará de forma segura.

Resumen y Próximos Pasos

Resolver errores persistentes de autenticación de Git se reduce a asegurar que estás utilizando un tipo de credencial moderno y compatible (clave SSH o PAT) que coincida con el protocolo de tu URL remota (SSH o HTTPS).

Si el Error Persiste... Acción
403 Forbidden Verifica los ámbitos del PAT o comprueba los permisos de la clave SSH en el host.
Solicitudes Repetidas (HTTPS) Genera un Token de Acceso Personal (PAT) y asegúrate de que el ayudante de credenciales lo está almacenando correctamente.
La clave SSH falla Confirma que la clave pública está registrada y que ssh-agent está en funcionamiento y tiene cargada la clave privada.

Siguiendo estos pasos, puedes eliminar los errores de credenciales, lo que conducirá a un flujo de trabajo de Git más fluido y seguro.