Conectar-se com segurança aos recursos do Azure ou clonar repositórios privados

Ao acessar recursos como repositórios ou recursos do Azure durante o processo de personalização, autentique-se com segurança. Para evitar o armazenamento de valores secretos em arquivos de personalização e controle do código-fonte, faça referência aos segredos do Azure Key Vault em seus arquivos de personalização. Use as entidades de serviço para autenticar no Azure para ter acesso seguro a recursos. Este artigo explica como gerenciar e acessar recursos com segurança durante a personalização da caixa de desenvolvimento.

Pré-requisitos

• Um centro de desenvolvimento e um projeto configurados para o Dev Box. Se você não tiver um, consulte Configurar o Microsoft Dev Box.
• Permissão para criar uma caixa de desenvolvimento em pelo menos um projeto. Para configurar e acessar, consulte Criar uma caixa de desenvolvimento.
• Permissões necessárias para configurar personalizações, acesso ao Key Vault e catálogos. Consulte Permissões para personalizações.
• Um Azure Key Vault que contém os segredos que você deseja usar.
• (Exemplos de entidade de serviço) CLI do Azure instalada e conectada e permissão para criar entidades de serviço. Confira Instalar a CLI do Azure.

Considerações de segurança

A integração do Azure Key Vault ajuda você a evitar o armazenamento de valores secretos em arquivos de personalização e controle do código-fonte. No entanto, o Computador de Desenvolvimento resolve espaços reservados secretos no momento da personalização. Dependendo de como uma tarefa é executada e do que ela grava na saída, os valores secretos resolvidos podem aparecer na saída ou nos logs da tarefa.

Para reduzir a chance de exposição:

• Prefira abordagens de troca de tokens ou baseadas em identidade (por exemplo, troca de token do Azure DevOps) em vez de PATs (tokens de acesso pessoal) de longa duração, quando possível.
• Não imprima segredos para a saída. Evite modos detalhados ou de depuração que possam expor credenciais, URLs ou cabeçalhos.
• Evite inserir segredos diretamente em linhas de comando ou URLs. Se um segredo aparecer nos logs, revogue ou gire-o e atualize o cofre de chaves.

Usar segredos do cofre de chaves em arquivos de personalização

Use segredos do Azure Key Vault em suas personalizações YAML para clonar repositórios privados ou executar tarefas que exigem um token de acesso. Por exemplo, em um arquivo de personalização, use um PAT (token de acesso pessoal) armazenado no Azure Key Vault para acessar um repositório privado.

As personalizações de equipe e de usuário dão suporte à obtenção de segredos de um cofre de chaves.

• As personalizações de equipe usam arquivos de definição de imagem que definem a imagem base para a caixa de desenvolvimento com o image parâmetro e listam as tarefas executadas quando uma caixa de desenvolvimento é criada.
• As personalizações de usuário listam as tarefas executadas quando uma caixa de desenvolvimento é criada.

Para usar um segredo, como um PAT, em seus arquivos de personalização, armazene-o como um segredo do cofre de chaves. Os exemplos a seguir mostram como referenciar um segredo do cofre de chaves em ambos os tipos de personalizações.

Configurar o acesso ao cofre de chaves para personalizações

Seu centro de desenvolvimento precisa ter acesso ao cofre de chaves. Para configurar segredos do cofre de chaves para uso em sua equipe ou personalizações de usuário, verifique se a identidade gerenciada do projeto do Centro de Desenvolvimento tem a função de Usuário de Segredos do Key Vault em seu cofre de chaves.

Se as políticas da sua organização exigirem que você mantenha seu Key Vault privado da Internet, você poderá criar uma regra de firewall para desabilitar ou limitar o acesso público. Você precisa permitir que serviços confiáveis da Microsoft ignorem o firewall porque o Centro de Desenvolvimento não dá suporte a marcas de serviço. Atualmente, não há suporte para cofres de chaves com pontos de extremidade privados ou integração de link privado para esse cenário.

A captura de tela a seguir mostra a opção de permitir que serviços confiáveis da Microsoft ignorem o firewall nas configurações do Azure Key Vault.

Para saber mais sobre como permitir que serviços confiáveis da Microsoft ignorem o firewall, consulte Definir as configurações de rede do Azure Key Vault.

Configuração adicional para personalizações de usuário

Para configurar segredos armazenados no Cofre de Segredos para personalizações do usuário, também:

1. Certifique-se de que a identidade gerenciada do projeto do Centro de Desenvolvimento tenha as funções Leitor do Key Vault e Usuário de Segredos do Key Vault no seu cofre de chaves.
2. Conceda a função de Usuário de Segredos do Key Vault para o segredo a cada usuário ou grupo que precise dele durante a personalização do ambiente de desenvolvimento, incluindo a identidade gerenciada do Dev Center, contas de administrador e quaisquer outros usuários ou grupos necessários.

Exemplo de personalizações de equipe

Essa sintaxe usa um segredo do cofre de chaves (PAT) em um arquivo de definição de imagem. O KEY_VAULT_SECRET_URI é o identificador secreto (URI) para o segredo no seu cofre de chaves.

$schema: "<SCHEMA_VERSION>"
name: "<IMAGE_DEFINITION_NAME>"
image: "<BASE_IMAGE>"
description: "<DESCRIPTION>"

tasks:
  - name: <TASK_NAME>
    description: <TASK_DESCRIPTION>
    parameters:
      repositoryUrl: <REPOSITORY_URL>
      directory: <DIRECTORY_PATH>
      pat: "{{<KEY_VAULT_SECRET_URI>}}"

Este exemplo usa a git-clone tarefa:

$schema: "1.0"
name: "example-image-definition"
image: microsoftvisualstudio_visualstudioplustools_vs-2022-ent-general-win11-m365-gen2
description: "Clones a public example Git repository"

tasks:
  - name: git-clone
    description: Clone this repository into C:\workspaces
    parameters:
      repositoryUrl: https://github.com/example-org/example-repo.git
      directory: C:\workspaces
      pat: "{{https://contoso-vault.vault.azure.net/secrets/github-pat}}"

Ou você pode referenciar o segredo em linha com uma tarefa interna, conforme mostrado no exemplo a seguir:

$schema: "1.0" 
name: "example-image-definition"
image: microsoftvisualstudio_visualstudioplustools_vs-2022-ent-general-win11-m365-gen2
description: "Clones a public example Git repository"

tasks:  
- name: git-clone
    description: Clone this repository into C:\Workspaces 
    parameters: 
    command: MyCommand –MyParam "{{KEY_VAULT_SECRET_URI}}"

Exemplo de personalizações de usuário

As personalizações de usuário permitem que você obtenha um token do Azure DevOps para clonar repositórios privados sem especificar explicitamente um PAT do cofre de chaves.

Este exemplo mostra a abreviação do ADO ({{ado://...}}). O serviço troca seu token do Azure por um token do Azure DevOps em runtime, portanto, você não precisa armazenar um PAT no Key Vault.

$schema: "1.0"
tasks:
  - name: git-clone
    description: Clone this repository into C:\workspaces
    parameters:
      repositoryUrl: https://dev.azure.com/example-org/MyProject/_git/example-repo
      directory: C:\workspaces
      pat: '{{ado://example-org}}'

A extensão Computador de Desenvolvimento do Visual Studio Code e a CLI do Computador de Desenvolvimento não oferecem suporte ao carregamento seguro de segredos no fluxo de trabalho de teste interno para personalizações.

Autenticar para recursos do Azure usando entidades de serviço

Usando entidades de serviço, você pode autenticar nos recursos do Azure sem usar as credenciais do usuário. Crie um principal do serviço, atribua as funções necessárias e use-o para autenticar em uma tarefa de personalização. Hidrate sua senha do Key Vault no momento da personalização usando o recurso de segredos existente.

1. Crie um Principal de Serviço no Microsoft Entra ID e atribua as permissões necessárias para os recursos que você deseja usar.

   A saída é um objeto JSON que contém o appId, displayName, senha e tenant do principal de serviço, que são usados para autenticação e autorização em cenários de Automação do Azure.

   Exemplo: saída da CLI ao criar um principal de serviço. Armazene a senha devolvida no Key Vault e conceda a função de Usuário de Segredos do Key Vault à identidade do projeto Centro de Desenvolvimento para que a personalização possa hidratar o segredo em tempo de execução.

   $ az ad sp create-for-rbac -n DevBoxCustomizationsTest
   
   {
     "appId": "...",
     "displayName": "DevBoxCustomizationsTest",
     "password": "...",
     "tenant": "..."
   }
   

2. Armazene a senha retornada na etapa anterior em um segredo do Key Vault, desta forma: https://mykeyvault.vault.azure.net/secrets/password

3. No Key Vault, conceda a função de Usuário de Segredos do Key Vault à identidade do projeto.

Agora você pode autenticar em tarefas de personalização hidratando a senha da entidade de serviço a partir do Key Vault no momento da personalização.

Exemplo: baixar um arquivo do Armazenamento do Azure

O exemplo a seguir mostra como baixar um arquivo de uma conta de armazenamento. O snippet yaml define uma personalização do Dev Box que executa duas tarefas principais:

1. Instala a CLI do Azure usando o gerenciador de pacotes winget.

2. Executa um script do PowerShell que:

• Autentica no Azure usando uma entidade de serviço, com a senha recuperada do Azure Key Vault.
• Baixa um blob (arquivo) de uma conta de Armazenamento do Azure usando a sessão autenticada.

Exemplo: personalização que hidrata uma senha de entidade de serviço do Key Vault e a usa para autenticar e baixar um blob do Armazenamento do Azure. Armazene a senha do principal de serviço no Key Vault e verifique se a identidade do projeto tem a função de Usuário de Segredos do Key Vault.

$schema: "1.0"
name: "devbox-customization"
tasks:
  - name: ~/winget
    parameters:
      package: Microsoft.AzureCLI
  - name: ~/powershell
    parameters:
      command: |
        az login --service-principal `
          --username <appId> `
          --password {{https://mykeyvault.vault.azure.net/secrets/password}} `
          --tenant <tenantId>
        az storage blob download `
          --account-name <storage_account_name> `
          --container-name <container_name> `
          --name <blob_name> `
          --file <local_file_path> `
          --auth-mode login

Essa configuração permite automatizar o uso seguro de recursos do Azure durante o provisionamento do Dev Box sem expor credenciais no script.

Exemplo: Fazer o download de um artefato do Azure DevOps

Baixar artefatos de build do Azure DevOps (ADO) usando uma entidade de serviço para autenticação. Adicione a ID do Aplicativo (appId) da entidade de serviço como um usuário em sua organização do Azure DevOps e atribua a entidade de segurança ao grupo Leitores. Esta etapa fornece as permissões necessárias para usar artefatos de build.

Depois de configurar estas etapas, use as credenciais da entidade de serviço em tarefas de personalização para autenticar e baixar artefatos com segurança do Azure DevOps.

Adicionar um principal de serviço a uma organização do Azure DevOps

Para adicionar um service principal à sua organização do Azure DevOps:

1. Entre em sua organização do Azure DevOps e abra as configurações da Organização.

2. No menu, selecione Usuários.

3. Na página Usuários , selecione Adicionar usuários.

4. Na caixa de diálogo Adicionar novos usuários , insira as seguintes informações:

   

   • Usuários: insira a ID do Aplicativo (appId) do principal de serviço como o e-mail do usuário.
   • Nível de Acesso: Selecione Básico.
   • Adicionar ao projeto: Selecione o projeto no qual você deseja adicionar o principal de serviço.
   • Grupos do Azure DevOps: Atribuir a entidade de serviço ao grupo Leitores.

5. Conclua o processo para conceder as permissões necessárias.

Para obter detalhes sobre como adicionar usuários a organizações de DevOps, consulte Adicionar usuários da organização e gerenciar o acesso.

Conteúdo relacionado

• Saiba como definir e recuperar um segredo do Azure Key Vault usando o portal do Azure.
• Saiba como adicionar e gerenciar catálogos no Microsoft Dev Box.
• Saiba como usar entidades de serviço e identidades gerenciadas no Azure DevOps.