Usar entidades de serviço e identidades geridas no Azure DevOps

Serviços de DevOps do Azure

Nota

O Azure Ative Directory (Azure AD) agora é o Microsoft Entra ID. Para obter mais informações, consulte Novo nome para o Azure AD.

Adicione entidades de serviço do Microsoft Entra e identidades gerenciadas como identidades de aplicativo em suas organizações de Serviços de DevOps do Azure, que lhes concedem 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

Principais 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 inquilino. 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.

Managed identities são outro recurso do Microsoft Entra que funciona de forma semelhante aos princípios de serviço de uma aplicação. 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 de aplicativo em uma organização com permissões definidas. Ao longo do restante deste artigo, referimo-nos a identidades geridas e entidades de serviço de forma intercambiável como entidade de serviço, a menos que especificado o contrário.

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 geridas e principais de serviço

A sua implementação pode variar, mas, de forma geral, os passos seguintes ajudam-no a começar a utilizar princípios de serviço no seu fluxo de trabalho. Para acompanhar, considere ver uma das nossas aplicações de exemplo .

1. Crie uma nova identidade gerida ou um principal de serviço de aplicação

Crie uma entidade de serviço de aplicação ou uma identidade gerida no portal do Azure.

Opção 1: Criar um principal de serviço de aplicação

Quando você cria um novo registro de aplicativo, um objeto de aplicativo é criado no Microsoft Entra ID. O principal de serviço da aplicação é uma representação deste objeto de aplicação 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.

Para obter mais informações, consulte os seguintes artigos:

• Objetos de aplicação e de entidade de serviço no Microsoft Entra ID
• Proteja suas entidades de serviço
• Use o portal para criar uma aplicação Microsoft Entra e um principal de serviço que possa aceder a recursos

Opção 2: 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:

• Saber mais sobre as identidades geridas para recursos do Azure
• Gerenciar identidades gerenciadas atribuídas pelo usuário
• Configurar identidades gerenciadas para recursos do Azure em uma máquina virtual 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 de Utilizadores 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.

Gorjeta

Para adicionar um principal do serviço à organização, insira o nome de apresentação do aplicativo ou da identidade gerenciada. Se optar por adicionar uma entidade de serviço programaticamente por meio do ServicePrincipalEntitlements API, certifique-se de passar a ID de objeto da entidade de serviço e não a ID de objeto da aplicação.

Se for um PCA, também pode conceder a um principal 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.

Nota

Você só pode adicionar uma identidade gerida ou um principal de serviço para o tenant ao qual a sua organização está conectada. As entidades de serviço podem ser tornadas multilocatárias para aceder a vários locatários simultaneamente. As identidades gerenciadas só podem pertencer a um único locatário. Para acessar uma identidade gerenciada em um locatário diferente, consulte a solução alternativa nas Perguntas frequentes.

3. Definir permissões em um principal 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 a um principal de serviço, adicioná-lo a grupos e equipas de segurança, atribuí-lo a qualquer nível de acesso e removê-lo 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 IDs do Microsoft Entra.

4. Gerenciar 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. Tendo dito isso, um principal de serviço ainda herda quaisquer permissões de grupo definidas sobre um grupo Microsoft Entra ao qual pertence.
• Os usuários em um grupo do Microsoft Entra não fazem 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 a cobrança de várias organizações esteja selecionada.

5. Obtenha um token de ID do Microsoft Entra

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.

Para operações ad-hoc, pode ser mais fácil adquirir um token único do Microsoft Entra ID 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.

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 um PAT para a utilização de um token de um principal 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 documentos:

• Conecte o seu principal de serviço a um feed do NuGet com Nuget.exe ou dotnet.
• Publique extensões no Visual Studio Marketplace via linha de comando com a 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.
• Usar o Git Credential Manager para clonar repositórios com um principal de serviço

Como as entidades de serviço diferem dos usuários

• 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 em que se inscreve, mesmo com faturação de várias organizações .
• As entidades de serviço não podem ser proprietárias de organizações nem 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 para chamar APIs REST do Azure DevOps.
• Os principais de serviço não suportam Azure DevOps OAuth.

Perguntas frequentes

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 girados periodicamente (mínimo a cada 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 utilizador 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?

Só pode adicionar uma identidade gerida a partir do mesmo locatário 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. Baixe o certificado criado no CER formato, 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:

Nota

Faça sempre a rotação regular dos seus certificados.

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 principal de serviço com ID de objeto '{provided objectId}'

Não existe nenhum principal 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, um principal de serviço é um objeto que representa a aplicação para um determinado inquilino, não é a aplicação 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, poderás deparar-te 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

• Explore aplicativos de exemplo
• Revise a referência da API de Princípios de Serviço e Direitos
• Revise a referência da API do Service Principal Graph