Chaves de API com escopo

Para tornar o NuGet um ambiente mais seguro para distribuição de pacotes, você pode assumir o controle das chaves de API adicionando escopos.

A capacidade de fornecer escopo para suas chaves de API oferece um melhor controle sobre suas APIs. É possível:

• Crie várias chaves de API com escopo que podem ser usadas para pacotes diferentes com intervalos de tempo de expiração variáveis.
• Obtenha chaves de API com segurança.
• Edite as chaves de API existentes para alterar a aplicabilidade do pacote.
• Atualize ou exclua as chaves de API existentes sem dificultar as operações usando outras chaves.

Por que damos suporte a chaves de API com escopo?

Damos suporte a escopos para chaves de API para permitir que você tenha permissões mais refinadas. Anteriormente, o NuGet oferecia uma única chave de API para uma conta e essa abordagem tinha várias desvantagens:

• Uma chave de API para controlar todos os pacotes. Com uma única chave de API usada para gerenciar todos os pacotes, é difícil compartilhar com segurança a chave quando vários desenvolvedores estão envolvidos com pacotes diferentes e quando compartilham uma conta de editor.
• Todas as permissões ou nenhuma. Qualquer pessoa com acesso à chave de API tem todas as permissões (publicar, enviar push e cancelar a lista) nos pacotes. Isso geralmente não é desejável em ambiente com várias equipes.
• Ponto único de falha. Uma única chave de API também significa um único ponto de falha. Se a chave estiver comprometida, todos os pacotes associados à conta poderão ser comprometidos. Renovar a chave API é a única maneira de tampar o vazamento e evitar interrupção no fluxo de trabalho CI/CD. Além disso, pode haver casos em que você deseja revogar o acesso à chave de API para um indivíduo (por exemplo, quando um funcionário deixa a organização). Não há uma maneira limpa de lidar com isso hoje.

Com chaves de API com escopo, tentamos resolver esses problemas, garantindo que nenhum dos fluxos de trabalho existentes seja interrompido.

Adquirir uma chave de API

1. Entre em sua conta nuget.org ou crie uma conta se você ainda não tiver uma.

2. Selecione o nome de usuário no canto superior direito e selecione Chaves de API.

3. Selecione Criar e forneça um nome para sua chave.

4. Em Selecionar Escopos, selecione Push.

5. Sob Selecionar Pacotes>Padrão Glob, insira *.

6. Selecione Criar.

7. Selecione Copiar para copiar a nova chave.

   

Importante

• Sempre mantenha sua chave de API em segredo. A chave de API é como uma senha que permite que qualquer pessoa gerencie pacotes em seu nome. Exclua ou regenere sua chave de API se ela for revelada acidentalmente.
• Salve sua chave em um local seguro, pois não é possível copiar a chave novamente mais tarde. Se você retornar à página de chave da API, será necessário regenerar a chave para copiá-la. Você também pode remover a chave de API se não quiser mais enviar pacotes por push.

A limitação de escopo permite criar chaves de API separadas, cada uma com uma finalidade específica. Cada chave tem um prazo de validade, e você pode limitar o escopo da chave para pacotes específicos ou padrões globais. Você também define o escopo de cada chave para operações específicas: fazer push de novos pacotes e versões de pacotes, fazer push apenas de novas versões de pacotes ou remover da lista.

Por meio do escopo, você pode criar chaves de API para diferentes pessoas que gerenciam pacotes para sua organização para que tenham apenas as permissões necessárias.

Criar chaves de API com escopo específico

Você pode criar várias chaves de API com base em seus requisitos. Uma chave de API pode se aplicar a um ou mais pacotes, ter escopos variados que concedem privilégios específicos e ter uma data de validade associada a ela.

No exemplo a seguir, você tem uma chave de API nomeada Contoso service CI que pode ser usada para enviar pacotes por push para pacotes específicos Contoso.Service e é válida por 365 dias. Esse é um cenário típico em que diferentes equipes na mesma organização trabalham em pacotes diferentes e os membros da equipe recebem a chave que lhes concede privilégios apenas para o pacote em que estão trabalhando. A expiração serve como um mecanismo para evitar chaves obsoletas ou esquecidas.

Usar padrões glob

Se você estiver trabalhando em vários pacotes e tiver uma grande lista de pacotes para gerenciar, poderá optar por usar padrões de globbing para selecionar vários pacotes juntos. Por exemplo, se você quiser conceder escopos específicos a uma chave para todos os pacotes cuja ID começa com Fabrikam.Service, você poderá fazer isso especificando fabrikam.service.* na caixa de texto padrão Glob.

Usar padrões glob para determinar permissões de chave de API também se aplica a novos pacotes que correspondem ao padrão glob. Por exemplo, se você tentar fazer o push de um novo pacote chamado Fabrikam.Service.Framework, poderá fazer isso com a chave criada anteriormente, já que o pacote corresponde ao padrão glob fabrikam.service.*.

Obter chaves de API com segurança

Para segurança, uma chave recém-criada nunca é mostrada na tela e só está disponível usando o botão Copiar . Da mesma forma, a chave não é acessível depois que a página é atualizada.

Editar chaves de API existentes

Talvez você também queira atualizar as permissões de chave e os escopos sem alterar a chave em si. Se você tiver uma chave com escopos específicos para um único pacote, poderá optar por aplicar os mesmos escopos em um ou muitos outros pacotes.

Atualizar ou excluir chaves de API existentes

O proprietário da conta pode optar por atualizar a chave, caso em que a permissão (em pacotes), o escopo e a expiração permanecem iguais, mas uma nova chave é emitida tornando a chave antiga inutilizável. Isso é útil no gerenciamento de chaves obsoletas ou em que há qualquer potencial para um vazamento de chave de API.

Você também poderá optar por excluir essas chaves se elas não forem mais necessárias. Excluir uma chave remove a chave e a torna inutilizável.

FAQs

O que acontece com minha antiga chave de API (herdada)?

Sua chave de API antiga (herdada) continua funcionando e pode funcionar enquanto você quiser que ela funcione. No entanto, essas chaves serão desativadas se não tiverem sido usadas por mais de 365 dias para enviar um pacote por push. Para obter mais detalhes, consulte a postagem no blog Alterações nas chaves de API que expiram. Você não pode mais atualizar essa chave. Você precisa excluir a chave herdada e criar uma nova chave de escopo.

Observação

Essa chave tem todas as permissões em todos os pacotes e nunca expira. Você deve considerar a exclusão dessa chave e a criação de novas chaves com permissões com escopo e expiração definitiva.

Quantas chaves de API posso criar?

Não há limite para o número de chaves de API que você pode criar. No entanto, aconselhamos você a mantê-lo em uma contagem gerenciável para que você não acabe tendo muitas chaves obsoletas sem conhecimento de onde e quem as está usando.

Posso excluir minha chave de API herdada ou descontinuar o uso agora?

Sim. Você pode -- e provavelmente deve -- excluir sua chave de API herdada.

Posso recuperar minha chave de API que excluo por engano?

Não. Depois de excluído, você só pode criar novas chaves. Não há nenhuma recuperação possível para chaves excluídas acidentalmente.

A chave de API antiga continua funcionando após a atualização da chave de API?

Não. Depois de atualizar uma chave, uma nova chave será gerada com o mesmo escopo, permissão e expiração que a antiga. A chave antiga deixa de existir.

Posso conceder mais permissões a uma chave de API existente?

Você não pode modificar o escopo, mas pode editar a lista de pacotes à qual ela é aplicável.

Como saber se alguma das minhas chaves expirou ou se está expirando?

Se qualquer chave expirar, informaremos você por meio de uma mensagem de aviso na parte superior da página. Também enviamos um email de aviso ao titular da conta dez dias antes da expiração da chave para que você possa agir com antecedência.