Uso de la autenticación de clave SSH

Servicios Azure DevOps | Azure DevOps Server | Azure DevOps Server 2022

Use SSH en macOS, Linux o Windows para autenticarse de forma segura en Azure Repos repositorios de Git en Azure DevOps.

En este artículo se muestra cómo crear un par de claves RSA, agregar la clave pública al perfil y clonar repositorios mediante SSH.

Prerrequisitos

Funcionamiento de la autenticación de claves SSH

La autenticación de clave pública SSH funciona con un par asimétrico de claves de cifrado generadas. Comparta la clave pública con Azure DevOps para comprobar la conexión SSH inicial. Mantenga la clave privada segura y protegida en su sistema.

Establecimiento de la autenticación de clave SSH

Para usar SSH con Azure Repos, genere un par de claves RSA, agregue la clave pública al perfil de Azure DevOps, compruebe la huella digital del servidor y, a continuación, clone o actualice el repositorio para usar la dirección URL de SSH.

Si solo necesita la ruta de acceso más rápida, complete el paso 1, el paso 2 y el paso 3 en orden y, a continuación, use Solucionar problemas de autenticación SSH solo si se produce un error en un comando.

En los pasos siguientes se describe la configuración de la autenticación de claves SSH en las siguientes plataformas mediante la línea de comandos (también denominada shell):

• Linux
• macOS
• sistemas Windows que ejecutan Git para Windows

Paso 1: creación de las claves SSH

Para usar la autenticación basada en claves, primero debe generar un par de claves pública y privada para el cliente. OpenSSH puede generar varios tipos de claves, pero Azure DevOps admite claves RSA para la autenticación SSH.

Para generar un par de claves RSA para Azure DevOps, ejecute el siguiente comando desde PowerShell u otro shell como bash en el cliente:

ssh-keygen -t rsa -b 3072

La salida del comando debe mostrar la siguiente salida (donde username es el nombre de usuario):

Generating public/private rsa key pair.
Enter file in which to save the key (C:\Users\username/.ssh/id_rsa):

Presione Entrar para aceptar el valor predeterminado o especifique una ruta de acceso o un nombre de archivo en el que quiera que se generen las claves. Llegados a este punto, se le pedirá que use una frase de contraseña para cifrar los archivos de clave privada. La frase de contraseña puede estar vacía, pero no se recomienda. La frase de contraseña agrega otra capa de protección para la clave privada si se expone el archivo.

Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in C:\Users\username/.ssh/id_rsa.
Your public key has been saved in C:\Users\username/.ssh/id_rsa.pub.
The key fingerprint is:
SHA256:FHK6WjcUkcfQjdorarzlak1Ob/x7AmqQmmx5ryYYV+8 username@LOCAL-HOSTNAME
The key's randomart image is:
+---[RSA 3072]----+
|      . ** o     |
|       +.o= .    |
|      . o+       |
|      .+. .      |
|     .ooS  .     |
|  . .oo.=.o      |
|   =.= O.= .     |
|  . B BoE + . .  |
|   . *+*o. .o+   |
+----[SHA256]-----+

Ahora tiene un par de claves RSA pública o privada en la ubicación especificada. Los .pub archivos son claves públicas y los archivos sin una extensión son claves privadas:

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
-a----        10/11/2022   6:29 PM           2610 id_rsa
-a----        10/11/2022   6:29 PM            578 id_rsa.pub

Paso 2: Agregar la clave pública a Azure DevOps

Asocie la clave pública generada en el paso anterior con su id. de usuario.

1. Abra la configuración de seguridad; para ello, vaya al portal web y seleccione el icono situado junto al avatar en la esquina superior derecha de la interfaz de usuario. Seleccione Claves públicas de SSH en el menú que aparece.

   

2. Seleccione + Nueva clave.

   

3. Copie el contenido de la clave pública (por ejemplo, id_rsa.pub) que generó en el campo Datos de clave pública.

   Importante

   Evite agregar espacios adicionales o saltos de línea en medio del valor de clave, ya que pueden hacer que la clave no sea válida. Si al pegar se añaden artefactos de formato, elimínalos antes de guardar.

   

4. Asigne una descripción útil a la clave (esta descripción se muestra en la página Claves públicas SSH del perfil) para que pueda recordarla más adelante. Seleccione Guardar para almacenar la clave pública. Después de guardar la clave, ya no se puede cambiar. Puede eliminarla o crear una entrada nueva para otra clave. No hay restricciones en el número de claves que se pueden agregar al perfil de usuario.

   Nota:

   La directiva de organización puede aplicar la expiración de la clave SSH. Para obtener más información, consulte Cambio de las directivas de seguridad y conexión de aplicaciones para su organización.

5. En la página de información general de Claves públicas SSH se muestran las huellas digitales del servidor. Anote la huella digital SHA256 que se usará cuando se conecte por primera vez a Azure DevOps a través de SSH.

   

6. Pruebe la conexión mediante el comando siguiente:

   ssh -T git@ssh.dev.azure.com
   

   Si es la primera vez que se conecta, debería recibir el siguiente resultado:

   The authenticity of host 'ssh.dev.azure.com (<IP>)' can't be established.
   RSA key fingerprint is SHA256:ohD8VZEXGWo6Ez8GSEJQ9WpafgLFsOfLOtGGQCQo6Og.
   This key is not known by any other names
   Are you sure you want to continue connecting (yes/no/[fingerprint])?
   

   Compare esa huella digital con la huella digital SHA256 que se muestra en la página claves públicas ssh . Continúe solo si los valores coinciden.

7. Escriba yes para continuar. Si todo está configurado correctamente, la salida debe tener este aspecto:

    Warning: Permanently added 'ssh.dev.azure.com' (RSA) to the list of known hosts.
    remote: Shell access is not supported.
    shell request failed on channel 0
   

   Si no es así, consulte la sección Preguntas y solución de problemas.

Paso 3: Clonar el repositorio de Git mediante SSH

1. Copie la dirección URL del clon SSH del portal web. En este ejemplo, la dirección URL del clon SSH es para un repositorio de una organización denominado fabrikam-fiber, como se indica en la primera parte de la dirección URL después de dev.azure.com.

   

   Nota:

   Con Azure DevOps Services, el formato de la dirección URL del proyecto es dev.azure.com/{your organization}/{your project}. Pero todavía se admite el formato anterior que hace referencia al formato visualstudio.com. Para obtener más información, consulte Introducción a Azure DevOps, cambiar las organizaciones existentes para usar el nuevo nombre de dominio URL.

2. Ejecute git clone desde el símbolo del sistema.

   git clone git@ssh.dev.azure.com:v3/fabrikam-fiber/FabrikamFiber/FabrikamFiber
   

   Si no usa un agente SSH, se le pedirá que escriba la frase de contraseña:

   Cloning into 'FabrikamFiber'...
   Enter passphrase for key '/c/Users/username/.ssh/id_rsa':
   remote: Azure Repos
   remote: Found 127 objects to send. (50 ms)
   Receiving objects: 100% (127/127), 56.67 KiB | 2.58 MiB/s, done.
   Resolving deltas: 100% (15/15), done.
   

   Si en su lugar se le pide que compruebe una huella digital, lea Step 2: Agregue la clave pública a Azure DevOps de nuevo. Para otros problemas, lea la sección Preguntas y solución de problemas.

Usa la IA para trabajar con repositorios autenticados mediante SSH

Si usa repositorios de Git con GitHub Copilot o el servidor MCP de Azure DevOps, puede usar mensajes de lenguaje natural para validar la configuración de SSH y diagnosticar problemas de autenticación.

Solución de problemas y preguntas comunes

Use las secciones siguientes para encontrar el problema que coincide con el problema de configuración de SSH.

• Si la clave expiró o no es válida, comience con claves expiradas o no válidas.
• Si SSH no se puede conectar, comience con errores comunes de conexión.
• Si se le solicita repetidamente una frase de contraseña, comience con los problemas del agente SSH y de la frase de contraseña.
• Si usa varias claves o organizaciones, vaya a Administración de varias claves y organizaciones.
• Si necesita instrucciones sobre notificaciones o cuentas, vaya a Notificaciones y problemas de cuenta.

Claves expiradas o no válidas

P: Mi clave SSH expiró. ¿Cuál debo hacer?

R: Siga los pasos anteriores para crear y cargar una nueva clave SSH.

Como opción alternativa, un administrador de la colección de proyectos puede deshabilitar la directiva que valida la fecha de expiración de la clave SSH. De forma predeterminada, la política de validación de la expiración de la clave SSH está habilitada. Para más información, consulte Directivas de clave SSH.

Recibirá automáticamente una notificación siete días antes y cuando expire la clave. Junto con estas notificaciones, verá la siguiente mensajería:

remote: Authentication failed: your SSH key has expired. To restore access, visit https://aka.ms/ado-ssh-public-key-expired for guidance.
remote: Public key authentication failed.
fatal:  Could not read from remote repository.

Errores comunes de conexión

P: Veo advertencias relacionadas con ssh-rsa. ¿Cuál debo hacer?

R: Es posible que vea uno de los siguientes mensajes de advertencia:

ssh-rsa is about to be deprecated and your request has been throttled. Please use rsa-sha2-256 or rsa-sha2-512 instead. Your session will continue automatically. For more details see https://devblogs.microsoft.com/devops/ssh-rsa-deprecation.

Or

You’re using ssh-rsa that is about to be deprecated and your request has been blocked intentionally. Any SSH session using ssh-rsa is subject to brown out (failure during random time periods). Please use rsa-sha2-256 or rsa-sha2-512 instead. For more details see https://devblogs.microsoft.com/devops/ssh-rsa-deprecation.

Si ha modificado la configuración de SSH para degradar la configuración de seguridad de Azure DevOps agregando lo siguiente al archivo ~/.ssh/config (%UserProfile%\.ssh\config en Windows):

Host ssh.dev.azure.com vs-ssh.visualstudio.com
  HostkeyAlgorithms +ssh-rsa

Elimina estas líneas ahora y asegúrate de que rsa-sha2-256 y rsa-sha2-512 estén permitidos.

Para obtener más información, consulte la entrada de blog.

Esta solución es la solución canónica para las advertencias de obsolescencia ssh-rsa y los errores no compatibles ssh-rsa. Úselo como primer paso para esos escenarios.

P: SSH no puede establecer una conexión. ¿Cuál debo hacer?

R: Es posible que encuentre varios problemas diferentes:

• Uso de ssh-rsa no compatible

  You’re using ssh-rsa that is unsupported. Please use rsa-sha2-256 or rsa-sha2-512 instead. For more details see https://devblogs.microsoft.com/devops/ssh-rsa-deprecation.
  

  Aplique la misma solución descrita en la pregunta anterior sobre las advertencias de ssh-rsa: quite cualquier anulación de HostkeyAlgorithms +ssh-rsa y use rsa-sha2-256 y/o rsa-sha2-512.

• No hay ninguna clave de host coincidente

  Este problema no debe producirse en Azure DevOps Service o en versiones de Azure DevOps Server más recientes, como se mencionó en la publicación blog.

  Unable to negotiate with <IP> port 22: no matching host key type found. Their offer: ssh-rsa
  

  Modifique la configuración de SSH para degradar la configuración de seguridad de Azure DevOps agregando lo siguiente al archivo ~/.ssh/config (%UserProfile%\.ssh\config en Windows):

  Host ssh.dev.azure.com vs-ssh.visualstudio.com
     HostkeyAlgorithms +ssh-rsa
  

  Use esta solución alternativa solo para escenarios de compatibilidad heredados, normalmente para configuraciones de Azure DevOps Server autohospedados anteriores. Para Azure DevOps Services, mantenga los valores predeterminados seguros y evite invalidaciones persistentesssh-rsa.

  Importante

  OpenSSH desusó el algoritmo de firma de clave pública ssh-rsa en versión 8.2 y lo deshabilitó de forma predeterminada en versión 8.8.

• No hay ningún MAC coincidente

  Unable to negotiate with <IP> port 22: no matching MAC found. Their offer: hmac-sha2-256,hmac-sha2-512
  

  Modifique la configuración de SSH para degradar la configuración de seguridad de Azure DevOps agregando lo siguiente al archivo ~/.ssh/config (%UserProfile%\.ssh\config en Windows):

  Host ssh.dev.azure.com vs-ssh.visualstudio.com
     MACs +hmac-sha2-512,+hmac-sha2-256
  

• No hay ningún método de intercambio de claves coincidente

  Unable to negotiate with <IP> 22: no matching key exchange method found. Their offer: diffie-hellman-group1-sha1,diffie-hellman-group14-sha1,diffie-hellman-group-exchange-sha256
  

  Modifique la configuración de SSH para degradar la configuración de seguridad de Azure DevOps agregando lo siguiente al archivo ~/.ssh/config (%UserProfile%\.ssh\config en Windows):

  Host ssh.dev.azure.com vs-ssh.visualstudio.com
     KexAlgorithms +diffie-hellman-group-exchange-sha256,+diffie-hellman-group14-sha1,+diffie-hellman-group1-sha1
  

  Importante

  El algoritmo diffie-hellman-group1-sha1 de intercambio de claves está deshabilitado de forma predeterminada en la versión 6.9 de OpenSSH y diffie-hellman-group14-sha1 en la versión 8.2.

Problemas de agente SSH y frase de contraseña

P: El agente SSH no se está ejecutando o no se carga mi clave. ¿Cuál debo hacer?

R: Si la clave existe, pero SSH sigue solicitando una frase de contraseña cada vez, o si se produce un error en la clonación después de que la clave se cree correctamente, compruebe si el agente SSH se está ejecutando y si la clave está cargada.

Use el siguiente comando para ver qué identidades ha cargado el agente actualmente:

ssh-add -l

Si la salida indica que el agente no tiene identidades, agregue la clave privada al agente:

ssh-add ~/.ssh/id_rsa

En Windows, si usa PowerShell con el agente openSSH integrado, asegúrese de que el ssh-agent servicio se está ejecutando antes de agregar la clave. Si usa Git Bash u otro cliente SSH, consulte la documentación del cliente para iniciar su agente y cargar claves.

Si prefiere no usar un agente, SSH puede seguir funcionando, pero se le pedirá la frase de contraseña de la clave con más frecuencia.

P: ¿Cómo puedo hacer que Git recuerde la frase de contraseña para mi clave?

R: Use un agente SSH. Linux, macOS y Windows (a partir de Windows 10 (compilación 1809) o mediante Git para Windows con Git Bash) se envían con un agente SSH. El agente SSH puede almacenar en caché las claves SSH para su uso repetido. Consulte el manual del proveedor de SSH para obtener más información sobre cómo usarlo.

P: Uso PuTTY como cliente SSH y genero mis claves con PuTTYgen. ¿Puedo usar estas claves con Azure DevOps Services?

R: Sí. Cargue la clave privada con PuTTYgen, vaya al menú Conversiones y seleccione Exportar clave OpenSSH. Guarde el archivo de clave privada y, a continuación, siga la pregunta posterior de este artículo sobre el uso de una ubicación de clave no predeterminada. Copie la clave pública directamente desde la ventana PuTTYgen y péguela en el campo Datos de clave en la configuración de seguridad.

P: ¿Cómo puedo comprobar que la clave pública que he cargado es la misma que mi clave local?

A: Verifique la huella digital de la clave pública que cargó comparándola con la que se muestra en su perfil. Ejecute el siguiente comando ssh-keygen con su clave pública desde la línea de comandos. Si no usa los valores predeterminados, deberá cambiar la ruta de acceso y el nombre de archivo de la clave pública.

ssh-keygen -l -E md5 -f <path_to_your_public_key>

ssh-keygen -l -E sha256 -f <path_to_your_public_key>

A continuación, compare la firma con la del perfil. Esta comprobación es útil si tiene problemas de conexión o tiene dudas sobre el pegado incorrecto de la clave pública en el campo Datos de clave al agregar la clave a Azure DevOps.

P: ¿Cómo puedo empezar a usar SSH en un repositorio donde actualmente uso HTTPS?

R: Actualice el repositorio remoto origin en Git para que pase de una URL HTTPS a una URL SSH. Después de obtener la dirección URL de clonación de SSH, ejecute el siguiente comando:

git remote set-url origin <SSH URL to your repository>

Los comandos de Git que acceden al repositorio remoto llamado origin usan SSH.

Administración de varias claves y organizaciones

P: Uso Git LFS con Azure DevOps Services y obtengo errores al extraer archivos de seguimiento de Git LFS.

A: Azure DevOps Services actualmente no admite LFS a través de SSH. Use HTTPS para conectarse a repositorios con archivos de seguimiento de Git LFS.

P: ¿Cómo puedo usar una ubicación de clave no predeterminada, es decir, no ~/.ssh/id_rsa y ~/.ssh/id_rsa.pub?

R: Para usar una clave almacenada en un lugar diferente al predeterminado, realice estas dos tareas:

1. Las claves deben estar en una carpeta que solo pueda leer o editar. Si la carpeta tiene permisos más amplios, SSH no usa las claves.

2. Debe permitir que SSH conozca la ubicación de la clave, por ejemplo, especificándola como "Identidad" en la configuración de SSH:

   Host ssh.dev.azure.com
     IdentityFile ~/.ssh/id_rsa_azure
     IdentitiesOnly yes
   

La configuración de IdentitiesOnly yes garantiza que SSH no usará ninguna otra identidad disponible para autenticarse. Esta configuración es especialmente importante si hay más de una identidad disponible.

P: Tengo varias claves SSH. ¿Cómo se usa la clave SSH correcta para Azure DevOps?

R: Por lo general, al configurar varias claves para un cliente SSH, el cliente intenta autenticarse con cada clave secuencialmente hasta que el servidor SSH acepte una.

Sin embargo, este enfoque no funciona con Azure DevOps debido a restricciones técnicas relacionadas con el protocolo SSH y la estructura de nuestras direcciones URL de SSH de Git. Azure DevOps acepta la primera clave proporcionada por el cliente durante la autenticación. Si esa clave no es válida para el repositorio solicitado, se producirá un error en la solicitud sin intentar otras claves disponibles, lo que provoca el siguiente error:

remote: Public key authentication failed.
fatal: Could not read from remote repository.

Para Azure DevOps, debe configurar SSH para usar explícitamente un archivo de clave específico. El procedimiento es el mismo que cuando se usa una clave almacenada en una ubicación no predeterminada. Indique a SSH que use la clave SSH correcta para el host de Azure DevOps.

P: ¿Cómo se usan claves SSH diferentes para diferentes organizaciones en Azure DevOps?

R: Azure DevOps acepta la primera clave que proporciona el cliente durante la autenticación. Si esa clave no es válida para el repositorio solicitado, se producirá este error:

remote: Public key authentication failed.
fatal: Could not read from remote repository.

Este error se produce porque todas las direcciones URL de Azure DevOps comparten el mismo nombre de host (ssh.dev.azure.com), lo que hace imposible que SSH distinga entre ellas de forma predeterminada. Sin embargo, puede modificar la configuración de SSH para diferenciar entre distintas organizaciones proporcionando claves diferentes para cada una. Utilice alias de host para crear secciones Host separadas en el archivo de configuración de SSH.

# The settings in each Host section are applied to any Git SSH remote URL with a
# matching hostname.
# Generally:
# * SSH uses the first matching line for each parameter name, e.g. if there's
#   multiple values for a parameter across multiple matching Host sections
# * "IdentitiesOnly yes" prevents keys cached in ssh-agent from being tried before
#   the IdentityFile values we explicitly set.
# * On Windows, ~/.ssh/your_private_key maps to %USERPROFILE%\.ssh\your_private_key,
#   e.g. C:\Users\<username>\.ssh\your_private_key.

# Imagine that we have the following two SSH URLs:
# * git@ssh.dev.azure.com:v3/Fabrikam/Project1/fab_repo
#   * For this, we want to use `fabrikamkey`, so we'll create `devops_fabrikam` as
#     a Host alias and tell SSH to use `fabrikamkey`.
# * git@ssh.dev.azure.com:v3/Contoso/Project2/con_repo
#   * For this, we want to use `contosokey`, so we'll create `devops_contoso` as
#     a Host alias and tell SSH to use `contosokey`.
#
# To set explicit keys for the two host aliases and to tell SSH to use the correct
# actual hostname, add the next two Host sections:
Host devops_fabrikam
  HostName ssh.dev.azure.com
  IdentityFile ~/.ssh/private_key_for_fabrikam
  IdentitiesOnly yes

Host devops_contoso
  HostName ssh.dev.azure.com
  IdentityFile ~/.ssh/private_key_for_contoso
  IdentitiesOnly yes

Después, en lugar de usar las direcciones URL reales, indique a Git que quiere usar estas direcciones URL para cada repositorio como repositorio remoto reemplazando el nombre de host en los repositorios remotos existentes por devops_fabrikam y devops_contoso respectivamente. Por ejemplo, git@ssh.dev.azure.com:v3/Fabrikam/Project1/fab_repo se convierte en git@devops_fabrikam:v3/Fabrikam/Project1/fab_repo.

Notificaciones y problemas de cuenta

P: ¿Qué notificaciones puedo recibir sobre mis claves SSH?

R: Es posible que reciba algunas notificaciones sobre las claves SSH.

• Se agregó una nueva clave SSH a la organización.

• Una clave SSH asociada a la cuenta expira en 7 días y no es válida para la autenticación.

• Una clave SSH asociada a la cuenta ha expirado y ya no es válida para la autenticación.

  Notificación de ejemplo

  

P: ¿Qué hago si creo que alguien que no sea yo está agregando claves SSH en mi cuenta?

R: Si recibe una notificación de registro de clave SSH que no inició, es posible que las credenciales se vean comprometidas.

El siguiente paso es investigar si la contraseña está en peligro. Cambiar la contraseña siempre es un buen primer paso para defenderse contra este vector de ataque. Si es un usuario de Microsoft Entra, póngase en contacto con el administrador para comprobar si la cuenta se usó desde un origen o ubicación desconocidos.

P: ¿Qué hago si todavía se me pide mi contraseña y GIT_SSH_COMMAND="ssh -v" git fetch muestra no mutual signature algorithm o corresponding algo not in PubkeyAcceptedAlgorithms?

R: Algunas distribuciones de Linux, como Fedora Linux, aplican directivas criptográficas que requieren algoritmos de firma SSH más seguros que la configuración actual de SSH Azure DevOps permite.

Para solucionar el problema, agregue el código siguiente a la configuración de SSH (~/.ssh/config):

Host ssh.dev.azure.com vs-ssh.visualstudio.com
   PubkeyAcceptedAlgorithms +ssh-rsa

Si la versión de OpenSSH solo admite el nombre de configuración anterior, use PubkeyAcceptedKeyTypes en su lugar.

Use este código como solución alternativa de compatibilidad temporal. Si es posible, actualiza tu cliente SSH o la configuración del servidor y quita esta anulación después de probarlo.

Preguntas generales

P: ¿Puedo usar SSH con Azure DevOps Server?

R: Sí. En el caso de las instancias de Azure DevOps Server autohospedadas, use el nombre de host del servidor en la configuración de SSH y las direcciones URL remotas en lugar de ssh.dev.azure.com. Donde este artículo muestra ssh.dev.azure.com o vs-ssh.visualstudio.com, sustituya el nombre de host del servidor.

P: ¿Por qué mi clave SSH de servicios de Azure DevOps detuvo el funcionamiento?

R: La autenticación de clave SSH requiere que inicie sesión periódicamente en Azure DevOps Services mediante el flujo de autenticación completo (web). Iniciar sesión una vez cada 30 días es suficiente para muchos usuarios, pero es posible que tenga que iniciar sesión con más frecuencia en función de la configuración de Microsoft Entra. Si la clave SSH deja de funcionar, intente iniciar sesión en su organización y complete la solicitud de autenticación completa. Si la clave SSH sigue sin funcionar, compruebe si ha expirado.

Contenido relacionado

• Configuración de administradores de credenciales
• Introducción al servidor MCP de Azure DevOps
• Administrar archivos grandes
• Establecimiento de permisos de repositorio de Git