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

Azure DevOps Services

Adicione princípios de serviço e identidades gerenciadas do Microsoft Entra como identidades de aplicativo em suas organizações do Azure DevOps Services para conceder a elas acesso aos recursos de sua organização. Para muitas equipes, esse recurso pode ser uma alternativa viável e preferencial aos PATs (tokens de acesso pessoal) quando você autentica aplicativos que alimentam fluxos de trabalho de automação em sua empresa.

Sobre entidades de serviço e identidades gerenciadas

As entidades de serviço são objetos de segurança em um aplicativo do 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 deles.

As identidades gerenciadas são outro recurso do Microsoft Entra que atua 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 para que os serviços que dão suporte à autenticação do Microsoft Entra compartilhem 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 para uma identidade gerenciada possa parecer diferente no portal do Azure, o Azure DevOps trata os dois 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, nos referimos a identidades gerenciadas e entidades de serviço intercambiáveis 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. Para acompanhar, considere dar uma olhada em um de nossos aplicativos de exemplo.

1. Criar 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.

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

Quando você cria um novo registro de aplicativo, um objeto de aplicativo é criado na ID do Microsoft Entra. 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.

Mais informações:

• Objetos de entidade de serviço e aplicativo no Microsoft Entra ID
• Proteção de entidades de serviço
• Use o portal para criar um aplicativo do Microsoft Entra e uma entidade de serviço que possa acessar 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 pelo 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 pelo sistema, uma identidade é criada no Microsoft Entra ID. A identidade é 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 design, somente o recurso do Azure pode usar essa identidade para solicitar tokens do 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 atribuindo-a 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ídeos:

• O que são identidades gerenciadas para recursos do Azure?
• Gerenciar identidades gerenciadas e 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 por meio da página Usuários ou com as APIs ServicePrincipalEntitlements. Como eles não podem entrar interativamente, uma conta de usuário que pode adicionar usuários a uma organização, projeto ou equipe deve adicioná-los. Esses usuários incluem PCA (Administradores de Coleção de Projetos ) ou Administradores de Projeto e Administradores de Equipe quando a política "Permitir que administradores de equipe e de projeto convidem novos usuários" está 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, entre em contato com o PCA para atualizar quaisquer associações de projeto ou níveis de acesso de licença.

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

Depois que suas 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 de segurança e equipes, 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.

Definir essas permissões pode ser diferente de como você é usado para configurar permissões de aplicativo em um aplicativo do Microsoft Entra para outros recursos do Azure. O Azure DevOps não depende da configuração de "permissões de aplicativo" disponível para registros de aplicativo por meio do portal do Azure. Essas permissões de aplicativo aplicam 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 de organização, projeto ou objeto disponíveis 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 emails e, como tal, não podem ser convidadas para uma organização por email.
• Atualmente, as regras de grupo para licenciamento não se aplicam às entidades de serviço. Se você quiser atribuir um nível de acesso a uma entidade de serviço, é melhor fazer isso diretamente.
• As entidades de serviço podem ser adicionadas aos grupos do Microsoft Entra (no portal do Azure). Atualmente, existe uma limitação técnica que nos impede de exibi-los em uma lista de membros do grupo Microsoft Entra. Essa limitação não é verdadeira para grupos do Azure DevOps. Dito isso, uma entidade de serviço ainda herda todas as permissões de grupo definidas sobre um grupo do Microsoft Entra ao qual pertence.
• Os usuários de 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 na organização pela primeira vez. Um usuário que entra em uma organização nos permite determinar quais usuários devem receber uma licença. Como a entrada não é possível para entidades de serviço, um administrador deve adicioná-la explicitamente a uma organização, conforme descrito anteriormente.
• Você não pode 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 cobrança de várias organizações seja selecionada.

5. Obter um token de ID do Microsoft Entra

(a) Adquirir 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 da ID do Microsoft Entra. Veja os exemplos de princípios de serviço e de identidades gerenciadas .

O token de acesso retornado é um JWT (token Web JSON) com as funções definidas, que podem ser usadas para acessar recursos da organização usando o token como Bearer.

(b) Adquirir 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 de ID do Microsoft Entra único por meio da CLI do Azure. Essa abordagem é preferencial para operações que não precisam de um token persistente para serem giradas regularmente, como chamadas à API ou operações de clone git.

Pré-requisitos

• id de locatário do Azure e id de assinatura: verifique se a assinatura está associada ao locatário conectado à organização do Azure DevOps que você está tentando acessar. Se você não souber sua ID de locatário ou assinatura, poderá encontrá-la no portal do Azure.
• ID do cliente do aplicativo Azure e segredo do cliente
• CLI do Azure

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

1. Entre na CLI do Azure como principal de serviço usando o comando az devops login.
2. Siga as instruções na tela e conclua a entrada.

# 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 ao Microsoft Entra ID com a az account get-access-token ID do recurso 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 de costume. Vamos tentar chamar uma API do Azure DevOps passando-a nos cabeçalhos como um token 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 um 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 do cliente.

Outro exemplo demonstra como se conectar ao Azure DevOps usando uma Identidade Gerenciada Atribuída pelo Usuário em 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 sua entidade de serviço a um feed NuGet com Nuget.exe ou dotnet.
• Publique extensões no Visual Studio Marketplace por meio da linha de comando com sua entidade de serviço.
• Crie conexões de serviço sem segredo no Azure Pipelines baseadas em entidades de serviço ou identidades gerenciadas.
• Clonar repositórios usando uma entidade de serviço com o Gerenciador de Credenciais do Git

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

• Você não pode 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 se associa, mesmo com cobrança de várias organizações.
• As entidades de serviço não podem ser proprietárias da organização 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 para chamar APIs REST do Azure DevOps.
• As entidades de serviço não dão suporte a OAuth do Azure DevOps.

Perguntas Frequentes

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

R: Muitos de nossos clientes procuram uma entidade de serviço ou identidade gerenciada para substituir um PAT existente (token de acesso pessoal). Esses PATs geralmente pertencem a uma conta de serviço (conta de equipe compartilhada) que as está usando para autenticar um aplicativo com recursos do Azure DevOps. Os PATs devem ser girados laboriosamente de vez em quando (no mínimo 180 dias). Os PATs armazenados incorretamente podem cair em mãos erradas e durar o tempo de sua vida útil, que costuma ser maior. Os tokens do Microsoft Entra expiram a cada hora, limitando o fator de risco geral quando vazado. Para cenários comuns de PAT, compartilhamos alguns exemplos de como você pode explorar o uso de um token Microsoft Entra.

Você não pode usar uma entidade de serviço para criar um token de acesso pessoal.

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

R: as entidades de serviço e as identidades gerenciadas têm os mesmos limites de taxa dos usuários.

P: Usar esse recurso custará mais?

R: Entidades de serviço e identidades gerenciadas têm um preço semelhante ao dos usuários, com base no nível de acesso. Uma alteração notável diz respeito à forma como tratamos a "cobrança de várias organizações" para entidades de serviço. Os usuários são contados como apenas uma licença, independentemente de 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 "faturamento baseado em atribuição de usuário" padrão.

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

R: Você só pode adicionar uma identidade gerenciada do mesmo locatário ao qual sua organização está conectada. No entanto, temos uma solução alternativa que permite configurar uma identidade gerenciada no "locatário do 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 em portal do Azure para seu locatário de recurso.
2. Conecte-o a uma máquina virtual e atribua essa identidade gerenciada a ela.
3. Criar um cofre de chaves e gerar 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 posteriormente.
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 "Obter/Listar" (em "Permissões secretas" e pesquise a identidade gerenciada em "Selecionar entidade de segurança".
5. Baixe o certificado criado no formato "CER", o que garante que ele não contenha a parte privada do 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 e segredos".
8. Adicione a entidade de serviço desse aplicativo à organização do Azure DevOps que queremos que ele 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 faz uso do certificado de identidade gerenciada 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;
}

Possíveis erros

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

Verifique se o principal de serviço possui pelo menos uma licença "Básica" para acessar repositórios. Uma licença "Stakeholder" não é suficiente.

Falha ao criar a entidade de serviço com a ID do 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 de sua entidade de serviço. Lembre-se de que 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 locatário. Pesquise o nome do aplicativo e selecione no resultado "Aplicativo Empresarial" que retorna. Esse resultado é a página da entidade de serviço/aplicativo empresarial e você pode usar a ID de 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

Esse erro pode ser devido a um dos seguintes motivos:

• Você não é o proprietário da organização, do administrador da coleção de projetos ou de um projeto ou administrador de equipe.
• Você é um administrador de projeto ou equipe, mas a política "Permitir que administradores de equipe e de projeto convidem novos usuários" está desativada.
• Você é um administrador de projeto ou equipe que pode convidar novos usuários, mas está tentando atribuir uma licença ao convidar um novo usuário. Os administradores do projeto ou da 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 à licença.

A API Azure DevOps Graph List retorna uma lista vazia, mesmo sabendo que há entidades de serviço na organização

A API de Lista de Graph do Azure DevOps pode retornar uma lista vazia, mesmo que ainda haja mais páginas de usuários a serem retornadas. Use o continuationToken para iterar por meio das listas e, eventualmente, você pode encontrar uma página em que 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 tiver sido convidada para a organização, você poderá encontrar o seguinte erro. Verifique se a entidade de serviço foi adicionada à organização apropriada e tem todas as permissões necessárias para acessar os recursos necessários.

Artigos relacionados

• Descubra aplicativos de exemplo
• Examinar a referência da API de Direitos das Entidades de Serviço
• Revisar a referência da API Graph da Entidade de Serviço