Uso de la autenticación de clave SSH

  • Artículo

Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2019

Es posible conectarse a los repositorios de Git mediante SSH en macOS, Linux o Windows para conectarse de forma segura con la autenticación HTTPS.

Importante

Las direcciones URL de SSH han cambiado, pero las direcciones URL de SSH antiguas siguen funcionando. Si ya ha configurado SSH, actualice las direcciones URL remotas al nuevo formato:

Las direcciones URL de SSH actualizadas comienzan por ssh.dev.azure.com. Las direcciones URL anteriores usan vs-ssh.visualstudio.com.

  • Compruebe qué repositorios remotos usan SSH. Ejecute git remote -v en el shell o use en su lugar un cliente de GUI.
  • Visite el repositorio en la web y seleccione Clonar.
  • Seleccione SSH y copie la nueva dirección URL de SSH.
  • En el shell, ejecute git remote set-url <remote name> <new SSH URL> para cada repositorio remoto de un repositorio que quiera actualizar. Como alternativa, use un cliente de GUI para actualizar las direcciones URL remotas.

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. La clave pública se comparte con Azure DevOps y se usa para comprobar la conexión SSH inicial. La clave privada se mantiene segura en el sistema.

Establecimiento de la autenticación de clave SSH

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):

Nota:

A partir de Visual Studio 2017, se puede usar SSH para conectarse a repositorios Git de Azure DevOps.

Sugerencia

En Windows, se recomienda el uso de Git Credential Manager o tokens de acceso personal.

Paso 1: creación de las claves SSH

Nota:

Si ya ha creado claves SSH de RSA en el sistema, omita este paso y configure las claves SSH. Para comprobarlo, vaya al directorio principal y examine la carpeta .ssh (%UserProfile%\.ssh\ en Windows o ~/.ssh/ en Linux, macOS y Windows con Git Bash). Si ve dos archivos denominados id_rsa y id_rsa.pub respectivamente, continúe con la configuración de las claves SSH.

Para usar la autenticación basada en claves, primero debe generar pares de claves públicas o privadas para el cliente. ssh-keygen.exe se usa para generar archivos de clave y se pueden especificar los algoritmos DSA, RSA, ECDSA o Ed25519. Si no se especifica ningún algoritmo, se usa RSA.

Nota:

El único tipo de clave SSH admitido por Azure DevOps es RSA.

Para generar archivos de clave mediante el algoritmo RSA, ejecute el siguiente comando desde PowerShell u otro shell como bash en el cliente:

ssh-keygen

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

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

Puede presionar Entrar para aceptar el valor predeterminado o puede especificar una ruta de acceso o un nombre de archivo en el que quiere que se generen las claves. Llegados a este punto, se te pedirá que uses 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 funciona con el archivo de clave para proporcionar una autenticación en dos fases.

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úblicas/privadas en la ubicación especificada. Los archivos .pub son claves públicas y los archivos sin 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

Importante

Nunca comparta el contenido de la clave privada. Si la clave privada está en peligro, los atacantes pueden usarla para engañar a los servidores para que piensen que la conexión proviene de usted. Los archivos de clave privada son equivalentes a una contraseña y deben protegerse de la misma manera.

Paso 2: Adición de la clave pública a Azure DevOps

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

Nota:

Debe repetir esta operación para cada organización a la que tenga acceso y con la que desee utilizar SSH.

  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.

    Captura de pantalla que muestra el elemento de menú de claves públicas de SSH y el avatar de usuario seleccionado en Azure DevOps.

  2. Seleccione + Nueva clave.

    Captura de pantalla que muestra el acceso a la configuración de Security en Azure DevOps.

  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 en blanco o líneas nuevas en el campo Datos de clave, ya que pueden hacer que Azure DevOps use una clave pública no válida. Al pegar la clave, se suele agregar una línea nueva al final. Asegúrese de quitar esta línea nueva en caso de que ocurra.

    Captura de pantalla que muestra la configuración de una clave pública en Azure DevOps.

  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. Tenga en cuenta también que las claves SSH almacenadas en Azure DevOps expiran después de un año. Si la clave expira, puede cargar la misma clave o una nueva para seguir accediendo a Azure DevOps mediante SSH.

  5. En la página de información general se muestra una nota en la parte superior que contiene las huellas digitales del servidor. Tome nota de ellas porque serán necesarias cuando se conecte por primera vez a Azure DevOps a través de SSH.

    Captura de pantalla del acceso a la configuración de seguridad en Azure DevOps Services.

  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 la siguiente salida:

    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 la huella digital dada con las huellas digitales que se ofrecen en la página de configuración mencionada anteriormente. ¡Continúe solo si coinciden!

    Si todo está configurado correctamente, la salida debe tener este aspecto:

    remote: Shell access is not supported.

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

Paso 3: Clonación del repositorio de Git con SSH

Nota:

Para usar SSH con un repositorio clonado previamente a través de HTTPS, consulte Actualizar repositorios remotos a 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.

    Captura de pantalla que muestra la dirección URL clonada SSH de Azure Repos

    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 más información, consulte Presentación de Azure DevOps: cambiar las organizaciones existentes para usar la nueva dirección URL de nombre de dominio.

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

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

    Ahora se le pedirá que introduzca la frase de contraseña de su clave SSH antes de poder continuar, a menos que esté administrada por un agente SSH:

    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 lugar de ello, se le pide que verifique una huella digital, vuelva a leer el Paso 2: Adición de la clave pública a Azure DevOps. Para otros problemas, lea la sección Preguntas y solución de problemas.

Sugerencia

Para sacar el máximo partido de SSH, es habitual usar un agente SSH para administrar la(s) clave(s) SSH. Sin embargo, la configuración de un agente va más allá del ámbito de este artículo.

Preguntas y solución de problemas

R: Hay dos mensajes de aviso diferentes que puede ver:

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.

o

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.

Es posible que haya modificado previamente la configuración de SSH para bajar el nivel de 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

Quite estas líneas ahora y dé los permisos necesarios a rsa-sha2-256 y/o rsa-sha2-512.

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

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

R: Hay varios problemas diferentes que puede experimentar:

  • Uso de SSH-RSA no admitido

    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.

    Es posible que haya modificado previamente la configuración de SSH para bajar el nivel de 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

    Quite estas líneas ahora y dé los permisos necesarios a rsa-sha2-256 y/o rsa-sha2-512.

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

  • No hay ninguna clave de host coincidente

    Esto no debería ocurrir en Azure DevOps Service ni en versiones más recientes de Azure DevOps Server, tal como se viene indicado en el entrada del 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 cambiar a una versión anterior 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

    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 cambiar a una versión anterior 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 cambiar a una versión anterior 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 de intercambio de claves diffie-hellman-group1-sha1 se ha deshabilitado de forma predeterminada en la versión 6.9 de OpenSSH y diffie-hellman-group14-sha1 en la versión 8.2.

Sugerencia

Para las instancias autohospedados de Azure DevOps Server y TFS, use el nombre de host adecuado en la línea Host en lugar de ssh.dev.azure.com vs-ssh.visualstudio.com.

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

R: Puede usar un agente SSH para este fin. Linux, macOS y Windows (a partir de Windows 10 (compilación 1809) o usando Git para Windows con Git Bash) incluyen un agente SSH. El agente SSH se puede usar para 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 Export OpenSSH key (Exportar clave OpenSSH). Guarde el archivo de clave privada y siga los pasos para configurar claves no predeterminadas. 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?

R: Puede comprobar la huella digital de la clave pública cargada con la que se muestra en el perfil mediante el comando ssh-keygen siguiente ejecutado en la clave pública con 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 ~/.ssh/id_rsa.pub

Después, puede comparar la firma MD5 con la del perfil. Esta comprobación es útil si tiene problemas de conexión o 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: Tendrá que actualizar el origin repositorio remoto en Git para cambiar de una dirección URL HTTPS a SSH. Una vez que tenga la dirección URL del clon SSH, ejecute este comando:

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

Los comandos de Git que acceden al repositorio remoto denominado origin ahora usarán SSH.

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

R: 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, distinta de ~/.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 usará 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. Esto 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, si configura varias claves para un cliente SSH y se conecta a un servidor SSH, el cliente puede probar las claves hasta que el servidor acepte una.

Pero esto no funciona con Azure DevOps por motivos técnicos relacionados con el protocolo SSH y cómo se estructuran las direcciones URL de SSH de Git. Azure DevOps aceptará ciegamente la primera clave que proporciona 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 debido al siguiente error:

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

Para Azure DevOps, deberá 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. Simplemente indique a SSH que utilice la clave SSH correcta para el host de Azure DevOps.

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

R: Azure DevOps aceptará ciegamente 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.

Sin embargo, puede modificar la configuración de SSH para diferenciar entre distintas organizaciones y proporcionar claves diferentes para cada una. Para ello, deberá usar alias de host para crear secciones independientes Host en la configuración de SSH. Esto se debe a que todas las direcciones URL de Azure DevOps hospedadas tienen el mismo nombre de host (ssh.dev.azure.com), por lo que SSH no tiene forma de distinguirlas de forma predeterminada.

# 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 convertiría en git@devops_fabrikam:v3/Fabrikam/Project1/fab_repo.

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

R: Cada vez que registre una clave SSH nueva con Azure DevOps Services, recibirá una notificación por correo electrónico que le informará de que se ha agregado una nueva clave SSH a su cuenta.

Ejemplo de notificación SSH

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 una clave SSH que se está registrando y usted no la cargó manualmente en el servicio, es posible que las credenciales estén en peligro.

El siguiente paso sería investigar si la contraseña está en peligro o no. 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 una ubicación u origen 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, tienen directivas criptográficas que requieren algoritmos de firma SSH más seguros que los compatibles con Azure DevOps (a partir de enero de 2021). Hay una solicitud de característica abierta para agregar este servicio de asistencia.

Puede solucionar la incidencia agregando este código a la configuración de SSH (~/.ssh/config):

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

Sugerencia

Para las instancias autohospedados de Azure DevOps Server y TFS, use el nombre de host adecuado en la línea Host en lugar de ssh.dev.azure.com vs-ssh.visualstudio.com.