Usar entidades de serviço & identidades gerenciadas no Azure DevOps

Serviços de DevOps do Azure

Adicionar entidades de serviço e identidades gerenciadas do Microsoft Entra às suas organizações dos Serviços de DevOps do Azure concederá acesso aos recursos da sua organização. Para muitas equipes, esse recurso pode ser uma alternativa viável e preferida aos tokens de acesso pessoal (PATs) quando você autentica aplicativos que alimentam fluxos de trabalho de automação em sua empresa.

Sobre entidades de serviço e identidades gerenciadas

Entidades de serviço são objetos de segurança dentro de um aplicativo Microsoft Entra que definem o que um aplicativo pode fazer em um determinado locatário. Eles são configurados no portal do Azure durante o processo de registro do aplicativo e configurados para acessar recursos do Azure, como o Azure DevOps. Ao adicionar entidades de serviço à sua organização e configurar permissões sobre elas, podemos determinar se uma entidade de serviço está autorizada a acessar seus recursos organizacionais e quais.

As identidades gerenciadas são outro recurso do Microsoft Entra que age de forma semelhante às entidades de serviço de um aplicativo. Esses objetos fornecem identidades para recursos do Azure e permitem uma maneira fácil de os serviços que oferecem suporte à autenticação do Microsoft Entra compartilharem credenciais. Eles são uma opção atraente porque o Microsoft Entra ID cuida do gerenciamento e da rotação de credenciais. Embora a configuração de uma identidade gerenciada possa parecer diferente no portal do Azure, o Azure DevOps trata ambos os objetos de segurança da mesma forma que uma nova identidade em uma organização com permissões definidas. Ao longo do restante deste artigo, nos referimos a identidades gerenciadas e entidades de serviço de forma intercambiável como entidade de serviço, a menos que especificado.

Use as etapas a seguir para autenticar essas identidades no Azure DevOps para permitir que elas executem ações em nome de si mesmas.

Configurar identidades gerenciadas e entidades de serviço

Sua implementação pode variar, mas em um alto nível, as etapas a seguir ajudam você a começar a usar entidades de serviço em seu fluxo de trabalho. Considere ver uma das nossas aplicações de exemplo para seguir o processo.

1. Crie uma nova identidade gerenciada ou uma entidade de serviço de aplicativo

Crie uma entidade de serviço de aplicativo ou uma identidade gerenciada no portal do Azure.

Criar uma entidade de serviço de aplicativo

Quando você cria um novo registro de aplicativo, um objeto de aplicativo é criado no Microsoft Entra ID. A entidade de serviço de aplicativo é uma representação desse objeto de aplicativo para um determinado locatário. Quando você registra um aplicativo como um aplicativo multilocatário, há um objeto de entidade de serviço exclusivo que representa o objeto de aplicativo para cada locatário ao qual o aplicativo é adicionado.

Informações adicionais:

• Objetos de aplicação e de principal de serviço no Microsoft Entra ID
• Protegendo entidades de serviço
• Use o portal para criar um aplicativo Microsoft Entra e uma entidade de serviço que possa acessar recursos

Criar uma identidade gerenciada

A criação de identidades gerenciadas no portal do Azure difere significativamente da configuração de aplicativos com entidades de serviço. Antes de iniciar o processo de criação, você deve primeiro considerar qual tipo de identidade gerenciada deseja criar:

• Identidade gerenciada atribuída ao sistema: alguns serviços do Azure permitem habilitar uma identidade gerenciada diretamente em uma instância de serviço. Quando você habilita uma identidade gerenciada atribuída ao sistema, uma identidade é criada na ID do Microsoft Entra. A identidade está vinculada ao ciclo de vida dessa instância de serviço. Quando o recurso é excluído, o Azure exclui automaticamente a identidade para você. Por predefinição, apenas esse recurso do Azure pode utilizar essa identidade para pedir tokens ao Microsoft Entra ID.
• Identidade gerenciada atribuída pelo usuário Você também pode criar uma identidade gerenciada como um recurso autônomo do Azure criando uma identidade gerenciada atribuída pelo usuário e atribuí-la a uma ou mais instâncias de um serviço do Azure. Para identidades gerenciadas atribuídas pelo usuário, a identidade é gerenciada separadamente dos recursos que a usam.

Para obter mais informações, consulte os seguintes artigos e vídeo:

• O que são identidades geridas para recursos do Azure?
• Gerenciar identidades gerenciadas atribuídas pelo usuário
• Configurar identidades gerenciadas para recursos do Azure em uma VM usando o portal do Azure

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

Depois de configurar as entidades de serviço no centro de administração do Microsoft Entra, você deve fazer o mesmo no Azure DevOps adicionando as entidades de serviço à sua organização. Você pode adicioná-los através da página Usuários ou com as APIs ServicePrincipalEntitlements. Como eles não podem entrar interativamente, uma conta de usuário que possa adicionar usuários a uma organização, projeto ou equipe deve adicioná-los. Esses usuários incluem Administradores de Coleção de Projetos (PCA) ou Administradores de Projeto e Administradores de Equipe quando a política "Permitir que administradores de equipe e de projeto convidem novos usuários" estiver habilitada.

Se você for um PCA, também poderá conceder a uma entidade de serviço acesso a projetos específicos e atribuir uma licença. Se você não for um PCA, deverá entrar em contato com o PCA para atualizar quaisquer associações de projeto ou níveis de acesso de licença.

3. Definindo permissões em uma entidade de serviço

Depois que as entidades de serviço forem adicionadas à organização, você poderá tratá-las de forma semelhante às contas de usuário padrão. Você pode atribuir permissões diretamente em uma entidade de serviço, adicioná-la a grupos e equipes de segurança, atribuí-la a qualquer nível de acesso e removê-la da organização. Você também pode usar o Service Principal Graph APIs para executar operações CRUD em entidades de serviço.

A definição dessas permissões pode ser diferente de como você está acostumado a configurar permissões de aplicativo em um aplicativo Microsoft Entra para outros recursos do Azure. O Azure DevOps não depende da configuração "Permissões de aplicativo" disponível para registros de aplicativos por meio do portal do Azure. Essas permissões de aplicativo atribuem permissões a um principal de serviço em todas as organizações vinculadas a um locatário e não têm conhecimento das permissões disponíveis de organização, projeto ou objeto no Azure DevOps. Para oferecer permissões mais granulares às entidades de serviço, contamos com nosso próprio modelo de permissões em vez de Entra ID.

4. Gerir uma entidade de serviço

O gerenciamento de entidades de serviço difere das contas de usuário das seguintes maneiras principais:

• As entidades de serviço não têm e-mails e, como tal, não podem ser convidadas para uma organização por e-mail.
• Atualmente, as regras de grupo para licenciamento não se aplicam a entidades de serviço. Se você quiser atribuir um nível de acesso a uma entidade de serviço, é melhor fazê-lo diretamente.
• Os princípios de serviço podem ser adicionados aos grupos do Microsoft Entra (no portal do Azure). Existe atualmente uma limitação técnica que nos impede de poder exibi-los em uma lista de membros do grupo Microsoft Entra. Essa limitação não é verdadeira para grupos de DevOps do Azure. Dito isto, uma entidade de serviço ainda herda quaisquer permissões de grupo definidas sobre um grupo do Microsoft Entra a que pertencem.
• Os usuários em um grupo do Microsoft Entra não farão parte de uma organização do Azure DevOps imediatamente apenas porque um administrador cria um grupo e adiciona um grupo do Microsoft Entra a ele. Temos um processo chamado "materialização" que acontece quando um usuário de um grupo do Microsoft Entra entra na organização pela primeira vez. Um usuário entrando em uma organização nos permite determinar quais usuários devem receber uma licença. Como o login não é possível para entidades de serviço, um administrador deve adicioná-lo explicitamente a uma organização, conforme descrito anteriormente.
• Não é possível modificar o nome de exibição ou avatar de uma entidade de serviço no Azure DevOps.
• As entidades de serviço obtêm licenças em cada organização à qual são adicionadas, mesmo que de cobrança de várias organizações esteja selecionada.

5. Obtenha um token de ID do Microsoft Entra

(a) Adquira um token de ID do Microsoft Entra programaticamente

A aquisição de um token de acesso para uma identidade gerenciada pode ser feita seguindo a documentação do Microsoft Entra ID. Veja os exemplos de entidades de serviço e identidades gerenciadas.

O token de acesso retornado é um Token Web JSON (JWT) com as funções definidas, que pode ser usado para aceder a recursos da organização, utilizando o token como portador.

(b) Adquira um token de ID do Microsoft Entra com a CLI do Azure

Para operações ad-hoc, pode ser mais fácil adquirir um token único de ID do Microsoft Entra por meio da CLI do Azure. Essa abordagem é preferida para operações que não precisam de um token persistente para serem alternadas regularmente, como chamadas de API ou operações de clone git.

Pré-requisitos

• ID do locatário do Azure e ID da assinatura: verifique se a assinatura está associada ao locatário conectado à organização do Azure DevOps que você está tentando acessar. Se não souber o seu inquilino ou ID de subscrição, pode encontrá-lo no portal do Azure.
• ID do cliente da aplicação do Azure e segredo do cliente
• da CLI do Azure

Estas instruções são fornecidas pelos documentos Databricks e mais detalhes podem ser encontrados em sua página.

1. Inicie sessão na CLI do Azure como principal de serviço usando o comando az devops login.
2. Siga as instruções no ecrã e conclua o início de sessão.

# To authenticate a service principal with a password or cert:
az login --service-principal -u <app-id> -p <password-or-cert> --tenant <tenant>

# To authenticate a managed identity:
az login --identity

3. Defina a assinatura correta para a entidade de serviço conectada digitando o comando:

az account set -s <subscription-id>

4. Gere um token de acesso do Microsoft Entra ID com o ID do recurso az account get-access-token do Azure DevOps: 499b84ac-1321-427f-aa17-267ca6975798.

$accessToken = az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798 --query "accessToken" --output tsv

5. Agora, você pode usar az cli comandos por costume. Vamos tentar chamar uma API de DevOps do Azure passando-a nos cabeçalhos como um token de Bearer:

$apiVersion = "7.1-preview.1"
$uri = "https://dev.azure.com/${yourOrgname}/_apis/projects?api-version=${apiVersion}"
$headers = @{
    Accept = "application/json"
    Authorization = "Bearer $accessToken"
}
Invoke-RestMethod -Uri $uri -Headers $headers -Method Get | Select-Object -ExpandProperty value ` | Select-Object id, name

6. Use o token de ID do Microsoft Entra para autenticar nos recursos do Azure DevOps

No exemplo de vídeo a seguir, passamos da autenticação com uma PAT para o uso de um token de uma entidade de serviço. Começamos usando um segredo do cliente para autenticação e, em seguida, passamos a usar um certificado de cliente.

Outro exemplo demonstra como se conectar ao Azure DevOps usando uma Identidade Gerenciada Atribuída pelo Usuário dentro de uma Função do Azure.

Acompanhe esses exemplos encontrando o código do aplicativo em nossa coleção de aplicativos de exemplo.

Alguns cenários comuns para autenticação com entidades de serviço além de fazer chamadas à API REST do Azure DevOps podem ser encontrados nestes recursos:

• Conecte sua entidade de serviço a um feed do NuGet com Nuget.exe ou dotnet.
• Publique extensões no Visual Studio Marketplace por meio de de linha de comando com sua entidade de serviço.
• Crie conexões de serviço sem segredos no Azure Pipelines apoiadas por entidades de serviço ou identidades gerenciadas.
• clonar repositórios usando uma entidade de serviço com o Git Credential Manager

Qual é a diferença entre as entidades de serviço e os utilizadores?

• Não é possível modificar o nome de exibição ou avatar de uma entidade de serviço no Azure DevOps.
• Uma entidade de serviço conta como uma licença para cada organização à qual é adicionada, mesmo que a cobrança de várias organizações esteja selecionada.
• As entidades de serviço não podem ser proprietárias de organizações ou criar organizações.
• As entidades de serviço não podem criar tokens, como tokens de acesso pessoal (PATs) ou chaves SSH. Eles podem gerar seus próprios tokens de ID do Microsoft Entra e esses tokens podem ser usados para chamar APIs REST do Azure DevOps.
• Não damos suporte ao Azure DevOps OAuth para entidades de serviço.

FAQs

Geral

P: Por que devo usar uma entidade de serviço ou uma identidade gerenciada em vez de um PAT?

R: Muitos dos nossos clientes procuram uma entidade de serviço ou uma identidade gerida para substituir um PAT (token de acesso pessoal) existente. Esses PATs geralmente pertencem a uma conta de serviço (conta de equipe compartilhada) que os está usando para autenticar um aplicativo com recursos do Azure DevOps. Os PATs devem ser laboriosamente rodados de vez em quando (mínimo 180 dias). Os PATs armazenados indevidamente podem cair nas mãos erradas e perdurar durante o seu tempo de vida útil, que muitas vezes é prolongado. Os tokens Microsoft Entra expiram a cada hora, limitando o fator de risco geral quando vazados. Para cenários PAT comuns, partilhamos alguns exemplos sobre como pode explorar a utilização de um token Microsoft Entra em vez.

Não é possível usar uma entidade de serviço para criar um token de acesso pessoal.

P: Quais são os limites de taxa para entidades de serviço e identidades gerenciadas?

R: As entidades de serviço e as identidades geridas têm os mesmos limites de taxa que os utilizadores.

P: O uso desse recurso custará mais?

R: As entidades de serviço e as identidades geridas têm um preço semelhante ao dos utilizadores, com base no nível de acesso. Uma mudança notável diz respeito à forma como tratamos o "faturamento multi-organização" para entidades de serviço. Os usuários são contados como apenas uma licença, não importa em quantas organizações estejam. As entidades de serviço são contadas como uma licença por cada organização em que o usuário está. Esse cenário é semelhante ao padrão "faturamento baseado em atribuição de usuário".

P: Posso adicionar uma identidade gerenciada de um locatário diferente à minha organização?

R: Só pode adicionar uma identidade gerida a partir do mesmo inquilino ao qual a sua organização está ligada. No entanto, temos uma solução alternativa que permite configurar uma identidade gerenciada no "locatário de recurso", onde estão todos os seus recursos. Em seguida, você pode habilitá-lo para ser usado por uma entidade de serviço no "locatário de destino", onde sua organização está conectada. Execute as seguintes etapas como uma solução alternativa:

1. Crie uma identidade gerenciada atribuída pelo usuário no portal do Azure para seu locatário de recurso.
2. Conecte-o a uma máquina virtual e atribua-lhe essa identidade gerenciada.
3. Crie um cofre de chaves e gere um certificado (não pode ser do tipo "PEM"). Quando você gera esse certificado, um segredo com o mesmo nome também é gerado, que usamos mais tarde.
4. Conceda acesso à identidade gerenciada para que ela possa ler a chave privada do cofre de chaves. Crie uma política de acesso no cofre de chaves com as permissões "Get/List" (em "Permissões secretas" e procure a identidade gerenciada em "Selecionar principal".
5. Faça o download do certificado criado no formato "CER", o que garante que ele não contenha a parte privada do seu certificado.
6. Crie um novo registro de aplicativo no locatário de destino.
7. Carregue o certificado baixado para este novo aplicativo na guia "Certificados & segredos".
8. Adicione a entidade de serviço deste aplicativo à organização do Azure DevOps que queremos que ela acesse e lembre-se de configurar a entidade de serviço com as permissões necessárias.
9. Obtenha um token de acesso do Microsoft Entra deste principal de serviço que utiliza o certificado de identidade gerida com este exemplo de código:

public static async Task<string> GetSecret(string keyVaultName, string secretName)
{
	var keyVaultUri = new Uri("https://" + keyVaultName + ".vault.azure.net");
	var client = new SecretClient(keyVaultUri, new ManagedIdentityCredential());
	var keyVaultSecret = await client.GetSecretAsync(secretName);

	var secret = keyVaultSecret.Value;
	return secret.Value;
}

private static async Task<AuthenticationResult> GetAppRegistrationAADAccessToken(string applicationClientID, string appTenantId)
{
	IConfidentialClientApplication app;

	byte[] privateKeyBytes = Convert.FromBase64String(GetSecret(keyVaultName, secretName));
	X509Certificate2 certificateWithPrivateKey = new X509Certificate2(privateKeyBytes, (string)null, X509KeyStorageFlags.MachineKeySet);

	app = ConfidentialClientApplicationBuilder.Create(applicationClientID)
		.WithCertificate(certificateWithPrivateKey)
		.WithAuthority(new Uri(string.Format(CultureInfo.InvariantCulture, "https://login.microsoftonline.com/{0}", appTenantId)))
		.Build();
	app.AddInMemoryTokenCache();

	string AdoAppClientID = "499b84ac-1321-427f-aa17-267ca6975798/.default";
	string[] scopes = new string[] { AdoAppClientID };

	var result = await app.AcquireTokenForClient(scopes).ExecuteAsync();

	return result;
}

Erros potenciais

O repositório Git com nome ou identificador '{repoName}' não existe ou você não tem permissões para a operação que está tentando.

Certifique-se de que a entidade de serviço tenha pelo menos uma licença "Basic" para ter acesso aos repositórios. Uma licença "Stakeholder" não é suficiente.

Falha ao criar entidade de serviço com ID de objeto '{provided objectId}'

Não há nenhuma entidade de serviço com o provided objectId no locatário conectado à sua organização. Um motivo comum é que você está passando a ID do objeto do registro do aplicativo, em vez da ID do objeto da entidade de serviço. Lembre-se, uma entidade de serviço é um objeto que representa o aplicativo para um determinado locatário, não é o aplicativo em si. O service principal object ID pode ser encontrado na página "Aplicativos Empresariais" do seu locatário. Procure o nome do aplicativo e selecione o resultado "Aplicativo Empresarial" que retorna. Esse resultado é a página da entidade de serviço/aplicativo empresarial e você pode usar a ID do objeto encontrada nesta página para criar uma entidade de serviço no Azure DevOps.

Acesso negado: {ID of the caller identity} precisa das seguintes permissões no recurso Usuários para executar esta ação: Adicionar usuários

Este erro pode ser devido a um dos seguintes motivos:

• Você não é o proprietário da organização, administrador de coleção de projetos ou um administrador de projeto ou equipe.
• Você é um administrador de projeto ou equipe, mas a política "Permitir que administradores de equipe e projeto convidem novos usuários" está desabilitada.
• Você é um administrador de projeto ou equipe que pode convidar novos usuários, mas está tentando atribuir uma licença quando convida um novo usuário. Os administradores de projeto ou de equipe não têm permissão para atribuir uma licença a novos usuários. Qualquer novo usuário convidado é adicionado no nível de acesso padrão para novos usuários. Entre em contato com um PCA para alterar o nível de acesso da licença.

A API da Lista de Gráficos de DevOps do Azure retorna uma lista vazia, mesmo sabendo que há entidades de serviço na organização

A API de Lista de Gráficos de DevOps do Azure pode retornar uma lista vazia, mesmo que ainda haja mais páginas de usuários para retornar. Use o continuationToken para iterar através das listas, e você pode eventualmente encontrar uma página onde as entidades de serviço são retornadas. Se um continuationToken for retornado, isso significa que há mais resultados disponíveis por meio da API. Embora tenhamos planos para melhorar essa lógica, neste momento, é possível que os primeiros resultados X retornem vazios.

TF401444: Entre pelo menos uma vez como {tenantId'tenantId\servicePrincipalObjectId'} em um navegador da Web para habilitar o acesso ao serviço.

Se a entidade de serviço não foi convidada para a organização, você pode se deparar com o seguinte erro. Certifique-se de que a entidade de serviço seja adicionada à organização apropriada e tenha todas as permissões necessárias para acessar quaisquer recursos necessários.

Artigos relacionados

• Link para aplicativos de exemplo
• Referência da API de Direitos de Entidades de Serviço
• Referência da API do Service Principal Graph