Conecte-se com segurança aos recursos do Azure ou clone repositórios privados

Quando você acessa recursos como repositórios ou recursos do Azure durante o processo de personalização, precisa autenticar com segurança. Você pode fazer referência aos segredos do Cofre da Chave do Azure em seus arquivos de personalização para evitar a exposição de informações confidenciais e pode usar entidades de serviço para autenticar no Azure para acesso seguro a recursos. Este artigo explica como gerenciar e acessar recursos com segurança durante a personalização da caixa de desenvolvimento.

Usar segredos do Key Vault em arquivos de personalização

Use segredos do Cofre de Chaves do Azure em suas personalizações do 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 token de acesso pessoal (PAT) armazenado no Cofre de Chaves do Azure para acessar um repositório privado.

As personalizações de equipe e de usuário suportam a busca de segredos em um cofre de chaves. As personalizações de equipe, que usam arquivos de definição de imagem, 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 do usuário listam as tarefas que são 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 fazer referência a um segredo do cofre de chaves em ambos os tipos de personalizações.

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

Para configurar segredos do Key Vault para uso em personalizações de equipe ou usuário, verifique se a identidade gerida do projeto do Centro de Desenvolvimento tem a função Key Vault Secrets User no seu Key Vault.

Se o cofre de chaves for privado, permita que serviços confiáveis da Microsoft ignorem o firewall porque o Centro de Desenvolvimento ainda não oferece suporte a tags de serviço.

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

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

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

Para configurar segredos do cofre de chaves para personalizações do usuário, também:

Verifique se a identidade gerenciada do projeto do Centro de Desenvolvimento tem as funções Key Vault Reader e Key Vault Secrets User no cofre de chaves.
Conceda a função Usuário de Segredos do Cofre de Chaves para o segredo a cada usuário ou grupo que precisar dele durante a personalização da caixa de desenvolvimento, incluindo a identidade gerenciada do Centro de Desenvolvimento, contas de administrador e quaisquer outros usuários ou grupos necessários.

Exemplo de personalizações de equipe

Essa sintaxe usa um segredo do Key Vault (PAT) num ficheiro de definição de imagem. A URI KEY_VAULT_SECRET_URI é do segredo no 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 fazer referência ao 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 do usuário

As personalizações de usuário permitem obter um token de DevOps do Azure para clonar repositórios privados sem especificar explicitamente uma PAT do cofre de chaves. O serviço troca automaticamente seu token do Azure por um token do Azure DevOps em tempo de execução.

Este exemplo mostra a abreviatura do ADO ({{ado://...}}). O serviço troca seu token do Azure por um token do Azure DevOps em tempo de execução, portanto, você não precisa armazenar uma PAT no Cofre da Chave.

$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 Dev Box Visual Studio Code e a CLI Dev Box não oferecem suporte a segredos de hidratação no fluxo de trabalho de teste de loop interno para personalizações.

Autenticar para aceder a recursos do Azure com entidades de serviço

As entidades de serviço permitem que você se autentique com segurança nos recursos do Azure sem expor as credenciais do usuário. Crie um principal de serviço, atribua os papéis necessários e use-o para autenticar numa tarefa de personalização. Hidrate sua senha do Cofre de Chaves no momento da personalização usando o recurso de segredos existente.

Crie uma entidade de serviço no Azure Ative Directory (Azure AD) e atribua-lhe as funções necessárias para os recursos que pretende utilizar.

A saída é um objeto JSON que contém o appId, displayName, palavra-passe e inquilino da entidade de serviço, que são utilizados para autenticação e autorização em cenários de Automação do Azure.

Exemplo: saída CLI quando cria um principal de serviço. Armazene a senha retornada no Cofre de Chaves e conceda a função Usuário de Segredos do Cofre de Chaves à identidade do projeto do 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": "..."
}
```
Armazene a senha retornada acima em um segredo do Cofre de Chaves, assim: https://mykeyvault.vault.azure.net/secrets/password
No Cofre da Chave, conceda a função Usuário dos Segredos do Cofre da Chave à identidade do projeto.

Agora você pode autenticar-se em tarefas de personalização, recuperando a senha da entidade de serviço do Cofre de Chaves durante a 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 da Caixa de Desenvolvimento que executa duas tarefas principais:

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

Executa um script do PowerShell que:

Inicia sessão no Azure usando uma entidade de serviço, com a palavra-passe obtida de forma segura do Cofre de Chaves do Azure.
Baixa um blob (arquivo) de uma conta de Armazenamento do Azure usando a sessão autenticada.

Exemplo: personalização que hidrata uma senha da entidade de serviço do Cofre da Chave 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 Key Vault Secrets User.

$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 dos recursos do Azure durante o provisionamento da Caixa de Desenvolvimento sem expor credenciais no script.

Exemplo: Fazer o download de um artefato do Azure DevOps

Baixe artefatos de compilação do Azure DevOps (ADO) usando uma entidade de serviço para autenticação. Adicione o ID da Aplicação (appId) do principal do serviço como um utilizador na sua organização do Azure DevOps e atribua o principal ao grupo Leitores. Esta etapa fornece as permissões necessárias para usar artefatos de compilação.

Depois de configurar os passos, use as credenciais do principal de serviço em tarefas de personalização para autenticar e baixar artefatos com segurança do Azure DevOps.

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

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

Entre na sua organização do Azure DevOps e abra as configurações da organização.
No menu, selecione Usuários.
Na página Usuários , selecione Adicionar usuários.
Na caixa de diálogo Adicionar novos usuários , insira as seguintes informações:
- Utilizadores: insira o ID da aplicação (appId) da entidade de serviço como o e-mail do utilizador.
- Nível de Acesso: Selecione Básico.
- Adicionar ao projeto: selecione o projeto ao qual deseja adicionar o principal de serviço.
- Grupos de DevOps do Azure: atribua a entidade de serviço ao grupo Leitores .
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.

Saiba como Definir e recuperar um segredo do Cofre da Chave do Azure usando o portal do Azure.
Saiba como Adicionar e configurar um catálogo do GitHub ou Azure Repos.
Saiba como Usar entidades de serviço ou identidades gerenciadas no Azure DevOps.

Feedback

Esta página foi útil?

Last updated on 2025-10-04