Compartir a través de

Uso de paquetes desde fuentes autenticadas

  • Artículo

Muchas operaciones de NuGet, como la restauración e instalación, requieren comunicación con uno o varios orígenes de paquetes, que se pueden configurar en archivos nuget.config.

Nota:

Utilice orígenes de paquetes fiables.

En el caso de las fuentes HTTP, NuGet realizará una solicitud no autenticada y, si el servidor responde con una respuesta HTTP 401, NuGet buscará credenciales en el orden siguiente:

  1. Una variable de entorno NuGetPackageSourceCredentials_{name}.
  2. Credenciales en archivos nuget.config.
  3. Use un proveedor de credenciales de NuGet si el origen del paquete proporciona uno.

El origen del paquete determina las credenciales que debe usar. Por lo tanto, a menos que use un proveedor de credenciales, debe comprobar en el origen del paquete las credenciales que hay que usar. Es muy común que los orígenes de paquetes le impidan usar su contraseña (con la que inicia sesión en el sitio web) con NuGet. Normalmente, debe crear un token de acceso personal para usarlo como contraseña de NuGet, pero debe comprobar la documentación del servidor NuGet que está usando. Algunos orígenes de paquetes, como Azure DevOps y GitHub, tienen tokens de acceso con ámbito, por lo que es posible que tenga que asegurarse de que los tokens que cree incluyan el ámbito necesario.

Procedimientos recomendados de seguridad para administrar credenciales

Aunque NuGet busca credenciales en el orden mencionado anteriormente, se recomienda la siguiente secuencia para administrar de forma segura las credenciales al autenticarse con fuentes privadas:

  1. Proveedor de credenciales: se recomienda usar un proveedor de credenciales siempre que sea posible. Este enfoque evita almacenar secretos en texto sin formato y minimiza el riesgo de exponer accidentalmente los secretos a través del control de código fuente. Además, generalmente reduce el número de lugares que necesita actualizar cuando una credencial expira o cambia. Si el proveedor de credenciales admite el inicio de sesión único, puede reducir la frecuencia de inicios de sesión o el número de lugares donde se deben guardar las credenciales. Consulte la sección de proveedores de credenciales para obtener más información.

  2. Credenciales cifradas en nuget.config: si un proveedor de credenciales no está disponible, debe considerar la posibilidad de usar credenciales cifradas. Este enfoque proporciona una capa adicional de seguridad al almacenar las credenciales en un formato cifrado. Para obtener más información, consulte la sección sobre credenciales en archivos nuget.config.

    Nota:

    Tenga en cuenta que las contraseñas cifradas solo se admiten en Windows. Además, solo se pueden descifrar en el mismo equipo y por el mismo usuario que las cifró originalmente.

  3. Uso de macros de variables de entorno en nuget.config: si no es posible usar credenciales cifradas, considere la posibilidad de almacenar las credenciales en el archivo nuget.config con macros de variables de entorno. Este enfoque permite hacer referencia a variables de entorno que contienen las credenciales reales. Mejora la transparencia y ayuda a los usuarios finales a comprender cómo se configuran sus credenciales. Para obtener más información, consulte la sección sobre credenciales en archivos nuget.config.

  4. Usar variables de entorno directamente: como opción de reserva, puede almacenar las credenciales directamente en variables de entorno. Sin embargo, tenga en cuenta que este enfoque puede ofrecer menos visibilidad y control en comparación con el uso de macros de variables de entorno en el archivo nuget.config. Para obtener más información, consulte la sección sobre credenciales en variables de entorno.

  5. Borrar credenciales de texto en NuGet.Config: se recomienda encarecidamente usar una de las opciones mencionadas anteriormente. Si estas opciones no son factibles, puede almacenar las credenciales en el archivo nuget.config. Sin embargo, esta opción solo debe usarse en entornos en los que no haya ninguna otra opción segura disponible. Para obtener más información, consulte la sección sobre credenciales en archivos nuget.config.

    Advertencia

    Almacenar credenciales en texto no cifrado en el archivo nuget.config, especialmente al guardar el archivo en el control de código fuente, es arriesgado, ya que aumenta las posibilidades de pérdidas accidentales de credenciales. Si debe almacenar credenciales en el archivo nuget.config, considere la posibilidad de usar una de las opciones más seguras mencionadas anteriormente.

Al cumplir estos procedimientos recomendados, puede autenticar de forma segura fuentes privadas al tiempo que minimiza el riesgo de exposición a información confidencial.

Credenciales en variables de entorno

NuGet buscará una variable de entorno denominada NuGetPackageSourceCredentials_{name}, donde {name} es el valor de key="name" en el origen del paquete del archivo nuget.config. El valor de la variable de entorno debe ser Username={username};Password={password}y, opcionalmente, puede incluir ;ValidAuthenticationTypes={types}. Si la variable de entorno no coincide con la convención de NuGet o el valor no cumple el patrón esperado de NuGet, NuGet omitirá silenciosamente la variable de entorno y seguirá buscando credenciales para el origen del paquete en otro lugar. No hay registros para indicar que NuGet usa la credencial de la variable de entorno, lo que puede provocar dificultades en la depuración de problemas de autenticación si la variable de entorno contiene un secreto expirado y el nuevo secreto se agrega a un archivo nuget.config, ya que el archivo de configuración tiene menor prioridad.

Sugerencia

El uso de variables de entorno en canalizaciones de CI/CD es una excelente opción para minimizar el riesgo de que los secretos se capturen en los registros.

Por ejemplo, imagine que usa el siguiente archivo nuget.config:

<configuration>
  <packageSources>
    <clear />
    <add key="Contoso" value="https://nuget.contoso.com/v3/index.json" />
  </packageSources>
</configuration>

En este caso, el nombre de origen es Contoso y NuGet buscará el nombre de la variable de entorno NuGetPackageSourceCredentials_Contoso. Algunas plataformas distinguen mayúsculas de minúsculas, así que procure utilizar los caracteres correctos en mayúsculas y minúsculas para el nombre del entorno y el nombre de origen, tal como se define en el archivo nuget.config.

Si el nombre de usuario es nugetUser y la contraseña es secret123, el valor de la variable de entorno debe establecerse en Username=nugetUser;Password=secret123. Si NuGet solo debe usar esta credencial para la autenticación HTTP básica, pero no para otros esquemas de autenticación, puede establecer el valor de la variable de entorno en Username=nugetUser;Password=secret123;ValidAuthenticationTypes=Basic. Para obtener más información sobre los tipos de autenticación válidos, consulte la documentación sobre credenciales de paquete en archivos nuget.config.

Nota:

Las variables de entorno tienen restricciones en los caracteres permitidos y los distintos sistemas operativos pueden tener restricciones diferentes. Por ejemplo, no se permiten los espacios. Por lo tanto, utilice esta característica de variable de entorno para especificar las credenciales de NuGet para los orígenes de paquetes que usan caracteres que no son válidos para las variables de entorno de la plataforma. En tales casos, debe cambiar el nombre del origen del paquete en el archivo nuget.config.

Credenciales en archivos nuget.config

Los archivos nuget.config pueden contener credenciales de origen del paquete. Consulte la sección de documentación de referencia del archivo nuget.config sobre las credenciales de origen del paquete para obtener más información, incluida la sintaxis. Sin embargo, es más fácil usar dotnet nuget update source en la línea de comandos para establecer las credenciales.

Advertencia

Tenga cuidado al establecer credenciales en archivos nuget.config, especialmente al guardar la credencial como texto sin formato. Si la credencial se escribe en un archivo nuget.config que se encuentra en el control de código fuente, existe un mayor riesgo de perder accidentalmente el secreto.

A medida que NuGet acumula la configuración de varios archivos, se recomienda guardar las credenciales en el archivo de usuario nuget.config. También se recomienda guardar orígenes de paquetes en el archivo nuget.config de la solución (repositorio de código fuente), incluido un elemento <clear />, para la confiabilidad de la compilación.

El nombre de usuario y la contraseña de texto sin formato de un archivo nuget.config pueden usar una variable de entorno agregando % al principio y al final del nombre de la variable de entorno que desea usar. Para más información, consulte los documentos de referencia de nuget.config sobre el uso de variables de entorno.

Proveedores de credenciales

NuGet tiene un modelo de extensibilidad, lo que permite a los complementos proporcionar credenciales de NuGet. La ruta de acceso en la que se deben instalar los proveedores de credenciales, para que NuGet los detecte, es diferente para .NET Framework (NuGet.exe, MSBuild y Visual Studio) y el SDK de .NET (que se ejecuta en el entorno de ejecución de .NET 5+).

NuGet tiene un concepto de ejecución en modo interactivo o modo no interactivo. Cuando está en modo no interactivo, se pide a los proveedores de credenciales que no bloqueen NuGet. Cuando está en modo interactivo, es posible que el proveedor de credenciales le pida que inicie sesión. Las distintas herramientas tienen valores predeterminados diferentes, por lo que es posible que sea necesario habilitar o no el modo interactivo, en función de su escenario.

Herramienta Valor predeterminado Control de alternancia
dotnet CLI no interactivo Argumento --interactive. Por ejemplo, dotnet restore --interactive.
MSBuild no interactivo Propiedad de MSBuild NuGetInteractive. Por ejemplo, msbuild -t:restore -p:NuGetInteractive=true.
NuGet.exe interactiva Argumento -NonInteractive. Por ejemplo, nuget.exe restore -NonInteractive.
Visual Studio interactivo No es posible ejecutarlo en modo no interactivo.

NuGet.exe admite proveedores de credenciales V1 y V2, mientras que MSBuild y el SDK de .NET solo admiten los complementos multiplataforma (V2).

En Visual Studio, NuGet tiene una interfaz del proveedor de credenciales de Visual Studio que los proveedores de credenciales pueden usar para proporcionar una experiencia gráfica de inicio de sesión o llamar a las API de Visual Studio si es necesario. NuGet en Visual Studio volverá a los proveedores de credenciales de la línea de comandos si no encuentra un proveedor de credenciales de Visual Studio que controle el origen.

Visual Studio 2017, versión 15.9 y versiones posteriores, incluye un proveedor de credenciales para Azure Artifacts, que funciona en Visual Studio, MSBuild y NuGet.exe. Sin embargo, Visual Studio no incluye el proveedor de credenciales para el SDK de .NET, por lo que debe instalarse por separado para trabajar con la CLI dotnet.

Lista de proveedores de credenciales

Hay una solicitud de característica para que los proveedores de credenciales se puedan instalar a través de las herramientas de .NET y esto probablemente hará que sea más fácil detectar otros proveedores de credenciales. Hasta que esto se implemente, a continuación se muestra una lista de los proveedores de credenciales que conocemos: