Compartir vía

Uso de la autenticación de clave SSH

  • Artículo

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

Puede conectarse a los repositorios de Git mediante SSH en macOS, Linux o Windows para conectarse de forma segura con Azure DevOps.

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 Ed25519.

Nota:

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

Para generar archivos de clave mediante el algoritmo RSA compatible con Azure DevOps (RSA-SHA2-256 o RSA-SHA2-512), ejecute uno de los siguientes comandos desde un PowerShell u otro shell, como bash en el cliente:

ssh-keygen -t rsa-sha2-256

Or

ssh-keygen -t rsa-sha2-512

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

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 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 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 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.

    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 con la huella digital SHA256 que se muestra en la página Claves públicas SSH que se mencionó anteriormente. ¡Continúe solo si 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: 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

    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 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 advertencia diferentes que podría 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.

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 modificó 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

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 de blog.

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

R: Hay varios problemas diferentes que podría experimentar:

  • 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.

    Si modificó 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

    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 de blog.

  • No hay ninguna clave de host coincidente

    Ese problema no debería ocurrir en Azure DevOps Service ni en versiones más recientes de Azure DevOps Server, tal como se indica en la 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. 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 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.

Nota:

A partir de agosto/septiembre de 2024, estamos migrando de MD5 a hash SHA-256. Es posible que tenga que elegir la función correcta durante el período de transición.

ssh-keygen -l -E md5 -f <path_to_your_public_key> -- use this for MD5 fingerprints
ssh-keygen -l -E sha256 -f <path_to_your_public_key> -- use this for SHA-256 fingerprints

A continuación, puede comparar la firma 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 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 remoto denominado origin usan 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, 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.

Pero este enfoque no funciona con Azure DevOps debido a restricciones técnicas relacionadas con el protocolo SSH y la estructura de las direcciones URL de SSH de Git. 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á 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, deberá configurar SSH para usar explícitamente un archivo de claves específico. El procedimiento es el mismo que cuando se usa una clave almacenada en una ubicación no predeterminada. 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 acepta 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.

Este error se debe a que 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 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 registro de clave SSH que no inició, las credenciales podrían estar 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.