Consumindo pacotes de feeds autenticados

  • Artigo

Muitas operações do NuGet, como restaurar e instalar, exigem comunicação com uma ou mais origens de pacotes, que podem ser configuradas nos arquivos nuget.config. Para feeds HTTP, o NuGet fará uma solicitação não autenticada e, se o servidor responder com uma resposta HTTP 401, o NuGet procurará credenciais na seguinte ordem:

  1. Uma variável de ambiente NuGetPackageSourceCredentials_{name}.
  2. Credenciais em arquivos nuget.config.
  3. Use um provedor de credenciais NuGet, se a origem do pacote fornecer um.

As credenciais que você precisa usar são determinadas pela origem do pacote. Portanto, a menos que você esteja usando um provedor de credenciais, verifique com a origem do pacote quais credenciais você deverá usar. É muito comum que as origens de pacotes proíbam você de usar sua senha (com a qual você faz login no site) com o NuGet. Normalmente, você precisa criar um Token de Acesso Pessoal para usar como senha do NuGet, mas confira também a documentação do servidor NuGet que você estiver usando. Algumas fontes de pacote, como o Azure DevOps e o GitHub, têm tokens de acesso com escopo, portanto, talvez seja necessário garantir que todos os tokens criados incluam o escopo necessário.

Melhores práticas de segurança para gerenciar credenciais

Embora o NuGet procure pelas credenciais na ordem descrita acima, recomendamos a seguinte sequência para gerenciar credenciais com segurança, quando você autenticar com feeds privados:

  1. Provedor de credenciais: é altamente recomendável usar um provedor de credenciais sempre que possível. Essa abordagem evita o armazenamento de segredos em texto sem formatação e minimiza o risco de expor segredos acidentalmente por meio do controle do código-fonte. Além disso, ele geralmente reduz o número de locais que você precisa atualizar quando uma credencial expira ou é alterada. Se o provedor de credenciais oferecer suporte ao logon único, ele poderá reduzir a frequência dos logons ou o número de locais onde as credenciais precisam ser salvas. Consulte a seção provedores de credenciais para obter mais informações.

  2. Credenciais criptografadas em nuget.config: se um provedor de credenciais não estiver disponível, considere usar credenciais criptografadas. Essa abordagem fornece uma camada extra de segurança armazenando as credenciais em um formato criptografado. Para obter mais informações, consulte a seção sobre credenciais nos arquivos nuget.config.

    Observação

    Lembre-se de que as senhas criptografadas são compatíveis somente no Windows. Além disso, elas só podem ser descriptografadas na mesma máquina e pelo mesmo usuário que as criptografou originalmente.

  3. Usar macros de variável de ambiente no nuget.config: se não for possível usar credenciais criptografadas, considere armazenar as credenciais no arquivo nuget.config com macros de variáveis de ambiente. Essa abordagem permite que você faça referência a variáveis de ambiente que contêm as credenciais reais. Ela aumenta a transparência e ajuda os usuários finais a entender como suas credenciais são configuradas. Para obter mais informações, consulte a seção sobre credenciais nos arquivos nuget.config.

  4. Usar variáveis de ambiente diretamente: como uma opção alternativa, armazene as credenciais diretamente nas variáveis de ambiente. Porém, esteja ciente de que essa abordagem pode oferecer menor visibilidade e controle comparada ao uso de macros de variáveis de ambiente no arquivo nuget.config. Para obter mais informações, consulte a seção sobre credenciais em variáveis de ambiente.

  5. Credenciais de texto não criptografadas no NuGet.Config: é altamente recomendável usar uma das opções mencionadas anteriormente. Se essas opções não forem viáveis, você poderá armazenar as credenciais no arquivo nuget.config. No entanto, essa opção só deve ser usada em ambientes onde nenhuma outra opção segura esteja disponível. Para obter mais informações, consulte a seção sobre credenciais nos arquivos nuget.config.

    Aviso

    Armazenar credenciais em texto não criptografado no arquivo nuget.config, principalmente ao salvar o arquivo no controle do código-fonte, é arriscado, pois aumenta as chances de vazamentos acidentais de credenciais. Se você precisar armazenar credenciais no arquivo nuget.config, considere uma das opções mais seguras mencionadas acima.

Ao aderir a essas práticas recomendadas, você pode autenticar feeds privados com segurança e, ao mesmo tempo, minimizar o risco de exposição de informações confidenciais.

Credenciais em variáveis de ambiente

O NuGet procurará uma variável de ambiente chamada NuGetPackageSourceCredentials_{name}, na qual {name} é o valor de key="name" na origem do pacote do seu arquivo nuget.config. O valor da variável de ambiente deve ser Username={username};Password={password}, e pode opcionalmente incluir ;ValidAuthenticationTypes={types}. Se a variável de ambiente não corresponder à convenção do NuGet, ou o valor não atender ao padrão esperado do NuGet, ele ignorará silenciosamente a variável de ambiente e continuará procurando credenciais para a origem do pacote em outro lugar. Não há logs para sinalizar que o NuGet usa a credencial da variável de ambiente, o que pode causar dificuldades na depuração de problemas de autenticação, caso a variável de ambiente contenha um segredo expirado e o novo segredo for adicionado a um arquivo nuget.config, já que o arquivo de configuração tem precedência menor.

Dica

O uso de variáveis de ambiente em pipelines de CI/CD é uma excelente opção para minimizar o risco de segredos serem capturados nos logs.

Por exemplo, considere o seguinte arquivo nuget.config:

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

Nesse caso, o nome de origem é Contoso e o NuGet procurará o nome NuGetPackageSourceCredentials_Contoso da variável de ambiente. Algumas plataformas diferenciam maiúsculas de minúsculas, portanto, tome cuidado ao usar os caracteres maiúsculos e minúsculos corretos para o nome do ambiente e o nome da origem, conforme definido no arquivo nuget.config.

Se o nome de usuário for nugetUser e a senha for secret123, o valor da variável de ambiente deverá ser definido como Username=nugetUser;Password=secret123. Se o NuGet usar somente essa credencial para a autenticação HTTP Básica, mas não outros esquemas de autenticação, defina o valor da variável de ambiente como Username=nugetUser;Password=secret123;ValidAuthenticationTypes=Basic. Para obter mais informações sobre os tipos de autenticação válidos, consulte os documentos sobre credenciais de pacote nos arquivos do nuget.config.

Observação

As variáveis de ambiente têm restrições sobre caracteres permitidos e diferentes sistemas operacionais podem ter restrições diferentes. Por exemplo, espaços não são permitidos. Portanto, você usa esse recurso de variável de ambiente para especificar as credenciais NuGet nas origens de pacotes que usam caracteres inválidos para as variáveis de ambiente da sua plataforma. Nesses casos, renomeie a origem do pacote no arquivo nuget.config.

Credenciais em arquivos nuget.config

Os arquivos nuget.config podem conter credenciais da origem do pacote. Consulte a seção do documento de referência do arquivo nuget.config sobre credenciais de origem do pacote para obter mais informações, incluindo sintaxe. No entanto, é mais fácil usar dotnet nuget update source na linha de comando para definir as credenciais.

Aviso

Tome cuidado ao definir credenciais nos arquivos nuget.config, principalmente ao salvar a credencial como texto sem criptografia. Se a credencial for gravada em um arquivo nuget.config que estiver no controle do código-fonte, haverá um risco maior de vazar acidentalmente o segredo.

Como o NuGet acumula configurações de vários arquivos, é recomendável salvar as credenciais no arquivo nuget.config do usuário. Também recomendamos salvar as origens do pacote na solução no arquivo nuget.config da solução (repositório de código-fonte), incluindo um elemento <clear />, para confiabilidade da compilação.

O nome de usuário e a senha de texto sem formatação em um arquivo nuget.config podem usar uma variável de ambiente adicionando % ao início e ao fim do nome da variável de ambiente que você deseja usar. Para obter mais informações, consulte os documentos de referência nuget.config sobre o uso de variáveis de ambiente.

Fornecedores de credenciais

O NuGet tem um modelo de extensibilidade, permitindo que os plug-ins forneçam credenciais ao NuGet. O caminho no qual os provedores de credenciais devem ser instalados, para que o NuGet seja descoberto, é diferente para o .NET Framework (NuGet.exe, MSBuild e Visual Studio) e o SDK do .NET (em runtime do .NET 5+).

O NuGet tem um conceito de execução no modo interativo ou no modo não interativo. Quando no modo não interativo, os provedores de credenciais são solicitados a não bloquear o NuGet. Enquanto estiver no modo interativo, o provedor de credenciais pode solicitar que você faça logon. Ferramentas diferentes têm padrões diferentes, portanto, o modo interativo pode precisar ser aceito ou desativado, dependendo da sua situação.

Ferramenta Padrão Ativar/desativar
dotnet CLI não interativo Argumento --interactive. Por exemplo, dotnet restore --interactive.
MSBuild não interativo Propriedade NuGetInteractive do MSBuild. Por exemplo, msbuild -t:restore -p:NuGetInteractive=true.
NuGet.exe Interativo Argumento -NonInteractive. Por exemplo, nuget.exe restore -NonInteractive.
Visual Studio Interativo Não é possível executar no modo não interativo.

O NuGet.exe oferece suporte a provedores de credenciais V1 e V2, enquanto o MSBuild e o SDK do .NET oferecem suporte somente aos plug-ins multiplataforma (V2).

No Visual Studio, o NuGet tem uma interface do Provedor de Credenciais do Visual Studio, que os provedores de credenciais podem usar para fornecer uma experiência de logon gráfico ou para chamar as APIs do Visual Studio, se necessário. O NuGet no Visual Studio usará como alternativa os provedores de credenciais de linha de comando se não encontrar um provedor de credenciais do Visual Studio que administre a origem.

O Visual Studio 2017 versão 15.9 e superior inclui um provedor de credenciais para o Azure Artifacts, que funciona no Visual Studio, no MSBuild e no NuGet.exe. No entanto, o provedor de credenciais para o SDK do .NET não está incluído pelo Visual Studio, portanto , deve ser instalado separadamente para que funcione com a CLI do dotnet.

Lista de provedores de credenciais

Há uma solicitação de recurso para tornar os provedores de credenciais instaláveis por meio de ferramentas do .NET, e isso provavelmente facilitará a descoberta de outros provedores de credenciais. Até que isso seja implementado, aqui está uma lista de provedores de credenciais que conhecemos: