Configurar uma identidade gerenciada atribuída pelo usuário para confiar em um provedor de identidade externo
Artigo
Este artigo descreve como gerenciar uma credencial de identidade federada em uma identidade gerenciada atribuída pelo usuário no Microsoft Entra ID. A credencial de identidade federada cria uma relação de confiança entre uma identidade gerenciada atribuída pelo usuário e um IdP (provedor de identidade externo). Não há suporte para configurar uma credencial de identidade federada em uma identidade gerenciada atribuída pelo sistema.
Após configurar a identidade gerenciada atribuída pelo usuário para confiar em um IdP externo, configure a carga de trabalho de software externo para trocar um token do IdP externo por um token de acesso da plataforma de identidade da Microsoft. A carga de trabalho externa usa o token de acesso para acessar os recursos protegidos do Microsoft Entra sem precisar gerenciar segredos (em cenários com suporte). Para saber mais sobre o fluxo de trabalho de troca de token, leia sobre Federação de identidade de carga de trabalho.
Neste artigo, você saberá como criar, listar e excluir credenciais de identidade federada em uma identidade gerenciada atribuída pelo usuário.
Considerações e restrições importantes
Um máximo de 20 credenciais de identidade federada podem ser adicionadas a um aplicativo ou identidade gerenciada atribuída pelo usuário.
Ao configurar uma credencial de identidade federada, várias informações importantes deverão ser fornecidas:
O issuer e o subject são as principais informações necessárias para configurar a relação de confiança. A combinação de issuer e subject deve ser exclusiva no aplicativo. Quando a carga de trabalho de software externo solicita à plataforma de identidade da Microsoft para trocar o token externo por um token de acesso, os valores de issuer e subject da credencial de identidade federada são verificados com base nas declarações issuersubject fornecidas no token externo. Se essa verificação de validação for aprovada, a plataforma de identidade da Microsoft emitirá um token de acesso para a carga de trabalho de software externo.
O issuer é a URL do provedor de identidade externa e deve corresponder à declaração issuer do token externo que está sendo trocado. Obrigatórios. Se a declaração issuer tiver um espaço em branco à esquerda ou à direita no valor, a troca de tokens será bloqueada. Este campo tem um limite de 600 caracteres.
O subject é o identificador da carga de trabalho de software externo e deve corresponder à declaração sub (subject) do token externo que está sendo trocado. O subject não tem formato fixo, pois cada IdP usa seu próprio, às vezes um GUID, às vezes um identificador delimitado por dois-pontos, às vezes cadeias de caracteres arbitrárias. Este campo tem um limite de 600 caracteres.
Importante
Os valores da configuração assunto devem corresponder exatamente à definição na configuração do fluxo de trabalho do GitHub. Caso contrário, a plataforma de identidade da Microsoft examinará o token externo de entrada e rejeitará o intercâmbio de um token de acesso. Você não receberá um erro, a troca falhará sem erros.
Importante
Se você adicionar acidentalmente as informações incorretas de carga de trabalho externa na configuração subject, a credencial de identidade federada será criada com êxito sem erros. O erro não se torna aparente até que a troca do token falhe.
audiences lista os públicos que podem aparecer no token externo. Obrigatórios. Será necessário adicionar um único valor de audiência com um limite de 600 caracteres. O valor recomendado é "api://AzureADTokenExchange". Ele informa o que a plataforma de identidade da Microsoft deve aceitar na declaração aud no token de entrada.
name é o identificador exclusivo da credencial de identidade federada. Obrigatórios. Esse campo tem um limite de caracteres de 3 a 120 caracteres e deve ser compatível com URL. Há suporte para caracteres alfanuméricos, traços ou sublinhados, o primeiro caractere deverá ser apenas alfanumérico. Após criado será imutável.
description é a descrição fornecida pelo usuário da credencial de identidade federada. Opcional. A descrição não é validada ou verificada pela ID do Microsoft Entra. Esse campo tem um limite de 600 caracteres.
Não há suporte para caracteres curinga em valores de propriedade de credencial de identidade federada.
Obtenha as informações para o IdP e carga de trabalho do software externo, que você precisará nas etapas a seguir.
Para criar uma identidade gerenciada atribuída pelo usuário e configurar uma credencial de identidade federada, a conta deverá ter a atribuição de função Colaborador ou Proprietário.
Encontre o nome da identidade gerenciada atribuída pelo usuário, que você precisa nas etapas a seguir.
Configurar uma credencial de identidade federada em uma identidade gerenciada atribuída pelo usuário
No portal do Microsoft Azure, navegue até a identidade gerenciada atribuída pelo usuário que você criou. Na guia Configurações, na barra de navegação esquerda, selecione Credenciais federadas e, a seguir, Adicionar credencial.
Na caixa suspensa Cenário de credenciais federadas, selecione o cenário.
GitHub Actions implantando recursos do Azure
Para adicionar uma identidade federada para as ações do GitHub, siga estas etapas:
Para Tipo de entidade, selecione Ambiente, Ramificação, Solicitação de pull ou Marca e especifique o valor. Os valores precisam corresponder exatamente à configuração do fluxo de trabalho do GitHub. Para obter mais informações, leia os exemplos.
Adicione um Nome para a credencial federada.
Os campos Emissor, Audiências e Identificador de assunto são preenchidos automaticamente com base nos valores inseridos.
Selecione Adicionar para configurar a credencial federada.
Use os seguintes valores de sua identidade gerenciada Microsoft Entra para o fluxo de trabalho do GitHub:
AZURE_CLIENT_ID a identidade gerenciada ID do cliente
AZURE_SUBSCRIPTION_ID A ID da assinatura.
A captura de tela a seguir demonstra como copiar a ID de identidade gerenciada e a ID da assinatura.
Para um fluxo de trabalho disparado por um evento de solicitação de push ou de pull na ramificação principal:
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
Especifique um Tipo de entidade igual a Branch e um nome do branch do GitHub igual a "principal".
Exemplo de ambiente
Para os trabalhos vinculados a um ambiente chamado "produção":
on:
push:
branches:
- main
jobs:
deployment:
runs-on: ubuntu-latest
environment: production
steps:
- name: deploy
# ...deployment-specific steps
Especifique um Tipo de entidade igual a Ambiente e um Nome do ambiente do GitHub igual a "produção".
Exemplo de marca
Por exemplo, para um fluxo de trabalho disparado por um push para a marca chamada "v2":
on:
push:
# Sequence of patterns matched against refs/heads
branches:
- main
- 'mona/octocat'
- 'releases/**'
# Sequence of patterns matched against refs/tags
tags:
- v2
- v1.*
Especifique um Tipo de entidade igual a Marca e um Nome da marca do GitHub igual a "v2".
Exemplo de solicitação de pull
Para um fluxo de trabalho disparado por um evento de solicitação de pull, especifique um Tipo de entidade da Solicitação de pull
Kubernetes acessando os recursos do Azure
Preencha os campos URL do emissor do cluster, Namespace, Nome da conta de serviço, e Nome:
Nome da conta de serviço é o nome da conta de serviço do Kubernetes, que fornece uma identidade para processos executados em um Pod.
Namespace é o namespace da conta de serviço.
Name é o nome da credencial federada, que não pode ser alterado posteriormente.
Selecione Adicionar para configurar a credencial federada.
Outros
Selecione o cenário Outro emissor no menu suspenso.
Especifique os seguintes campos (usando uma carga de trabalho de software em execução no Google Cloud como exemplo):
Name é o nome da credencial federada, que não pode ser alterado posteriormente.
Identificador de assunto: deve corresponder à declaração sub no token emitido pelo provedor de identidade externo. Neste exemplo, usando o Google Cloud, o assunto é a ID Exclusiva da conta de serviço que você planeja usar.
Emissor: deve corresponder à declaração iss no token emitido pelo provedor de identidade externo. Uma URL que está em conformidade com a especificação de descoberta OIDC. O Microsoft Entra ID usa essa URL do emissor para buscar as chaves necessárias para validar o token. No caso do Google Cloud, o issuer é "https://accounts.google.com".
Selecione Adicionar para configurar a credencial federada.
Listar credenciais de identidade federada em uma identidade gerenciada atribuída pelo usuário
No portal do Microsoft Azure, navegue até a identidade gerenciada atribuída pelo usuário que você criou. Na guia Configurações, na barra de navegação esquerda, selecione Credenciais federadas.
As credenciais de identidade federada configuradas nessa identidade gerenciada atribuída pelo usuário são listadas.
Excluir uma credencial de identidade federada de uma identidade gerenciada atribuída pelo usuário
No portal do Microsoft Azure, navegue até a identidade gerenciada atribuída pelo usuário que você criou. Na guia Configurações, na barra de navegação esquerda, selecione Credenciais federadas.
As credenciais de identidade federada configuradas nessa identidade gerenciada atribuída pelo usuário são listadas.
Para excluir uma credencial de identidade federada específica, selecione o ícone Excluir dessa credencial.
Obtenha as informações para o IdP e carga de trabalho do software externo, que você precisará nas etapas a seguir.
Para criar uma identidade gerenciada atribuída pelo usuário e configurar uma credencial de identidade federada, a conta deverá ter a atribuição de função Colaborador ou Proprietário.
Se preferir executar os comandos de referência da CLI localmente, instale a CLI do Azure. Para execuções no Windows ou no macOS, considere executar a CLI do Azure em um contêiner do Docker. Para obter mais informações, confira Como executar a CLI do Azure em um contêiner do Docker.
Se estiver usando uma instalação local, entre com a CLI do Azure usando o comando az login. Para concluir o processo de autenticação, siga as etapas exibidas no terminal. Para ver outras opções de entrada, confira Conectar-se com a CLI do Azure.
Quando solicitado, instale a extensão da CLI do Azure no primeiro uso. Para obter mais informações sobre extensões, confira Usar extensões com a CLI do Azure.
Execute az version para localizar a versão e as bibliotecas dependentes que estão instaladas. Para fazer a atualização para a versão mais recente, execute az upgrade.
Configurar uma credencial de identidade federada em uma identidade gerenciada atribuída pelo usuário
Execute o comando az identity federated-credential create para criar uma nova credencial de identidade federada na sua identidade gerenciada atribuída pelo usuário (especificada pelo nome). Especifique o nome, emissor, assunto e outros parâmetros.
az login
# set variables
location="centralus"
subscription="{subscription-id}"
rg="fic-test-rg"
# user assigned identity name
uaId="fic-test-ua"
# federated identity credential name
ficId="fic-test-fic-name"
# create prerequisites if required.
# otherwise make sure that existing resources names are set in variables above
az account set --subscription $subscription
az group create --location $location --name $rg
az identity create --name $uaId --resource-group $rg --location $location --subscription $subscription
# Create/update a federated identity credential
az identity federated-credential create --name $ficId --identity-name $uaId --resource-group $rg --issuer 'https://aks.azure.com/issuerGUID' --subject 'system:serviceaccount:ns:svcaccount' --audiences 'api://AzureADTokenExchange'
Listar credenciais de identidade federada em uma identidade gerenciada atribuída pelo usuário
Execute o comando az identity federated-credential list para ler todas as credenciais de identidade federada configuradas em uma identidade gerenciada atribuída pelo usuário:
az login
# Set variables
rg="fic-test-rg"
# User assigned identity name
uaId="fic-test-ua"
# Read all federated identity credentials assigned to the user-assigned managed identity
az identity federated-credential list --identity-name $uaId --resource-group $rg
Obter uma credencial de identidade federada em uma identidade gerenciada atribuída pelo usuário
az login
# Set variables
rg="fic-test-rg"
# User assigned identity name
uaId="fic-test-ua"
# Federated identity credential name
ficId="fic-test-fic-name"
# Show the federated identity credential
az identity federated-credential show --name $ficId --identity-name $uaId --resource-group $rg
Excluir uma credencial de identidade federada de uma identidade gerenciada atribuída pelo usuário
Execute o comando az identity federated-credential delete para excluir uma credencial de identidade federada em uma identidade atribuída a um usuário existente.
az login
# Set variables
# in Linux shell remove $ from set variable statement
$rg="fic-test-rg"
# User assigned identity name
$uaId="fic-test-ua"
# Federated identity credential name
$ficId="fic-test-fic-name"
az identity federated-credential delete --name $ficId --identity-name $uaId --resource-group $rg
Obtenha as informações para o IdP e carga de trabalho do software externo, que você precisará nas etapas a seguir.
Para criar uma identidade gerenciada atribuída pelo usuário e configurar uma credencial de identidade federada, a conta deverá ter a atribuição de função Colaborador ou Proprietário.
Para executar os scripts de exemplo, você tem duas opções:
Use o Azure Cloud Shell, que você pode abrir usando o botão Experimentar no canto superior direito dos blocos de código.
Executar os scripts localmente com o Azure PowerShell, conforme descrito na próxima seção.
Talvez seja necessário Exit da sessão atual do PowerShell depois de executar esse comando para a próxima etapa.
Instale o módulo Az.ManagedServiceIdentity para executar as operações de identidade gerenciada atribuídas pelo usuário neste artigo.
Install-Module -Name Az.ManagedServiceIdentity
Configurar uma credencial de identidade federada em uma identidade gerenciada atribuída pelo usuário
Execute o comando New-AzFederatedIdentityCredentials para criar uma nova credencial de identidade federada na sua identidade gerenciada atribuída pelo usuário (especificada pelo nome). Especifique o nome, emissor, assunto e outros parâmetros.
Listar credenciais de identidade federada em uma identidade gerenciada atribuída pelo usuário
Execute o comando Get-AzFederatedIdentityCredentials para ler todas as credenciais de identidade federada configuradas em uma identidade gerenciada atribuída pelo usuário:
Excluir uma credencial de identidade federada de uma identidade gerenciada atribuída pelo usuário
Execute o comando Remove-AzFederatedIdentityCredentials para excluir uma credencial de identidade federada sob uma identidade de usuário atribuída existente.
Obtenha as informações para o IdP e carga de trabalho do software externo, que você precisará nas etapas a seguir.
Para criar uma identidade gerenciada atribuída pelo usuário e configurar uma credencial de identidade federada, a conta deverá ter a atribuição de função Colaborador ou Proprietário.
Encontre o nome da identidade gerenciada atribuída pelo usuário, que você precisa nas etapas a seguir.
Criação e edição de modelo
Os modelos do Resource Manager ajudam você a implantar recursos novos ou modificados definidos por um grupo de recursos do Azure. Há várias opções disponíveis para a edição e a implantação do modelo, tanto locais quanto baseadas em portal. Você pode:
Configurar uma credencial de identidade federada em uma identidade gerenciada atribuída pelo usuário
É possível criar ou atualizar a credencial de identidade federada e a identidade atribuída ao usuário pai por meio do modelo abaixo. Você pode implantar os modelos do ARM usando o portal do Azure.
Todos os parâmetros do modelo são obrigatórios.
Há um limite de 3 a 120 caracteres para um comprimento do nome da credencial de identidade federada. Deverá ser alfanumérico, traço, sublinhado. O primeiro símbolo é apenas alfanumérico.
Você precisa adicionar exatamente um público a uma credencial de identidade federada. O público é verificado durante a troca de tokens. Use "api://AzureADTokenExchange" como o valor padrão.
As operações de Lista, Obter e Excluir não estão disponíveis com modelo. Consulte a CLI do Azure para essas operações. Por padrão, todas as credenciais de identidade federadas filhas são criadas em paralelo, o que dispara a lógica de detecção de simultaneidade e faz com que a implantação falhe com um código de status HTTP de conflito 409. Para criá-las sequencialmente, especifique uma cadeia de dependências usando a propriedade dependsOn.
Verifique se algum tipo de automação cria credenciais de identidade federadas na mesma identidade pai sequencialmente. As credenciais de identidade federada em diferentes identidades gerenciadas podem ser criadas em paralelo sem restrições.
Obtenha as informações para o IdP e carga de trabalho do software externo, que você precisará nas etapas a seguir.
Para criar uma identidade gerenciada atribuída pelo usuário e configurar uma credencial de identidade federada, a conta deverá ter a atribuição de função Colaborador ou Proprietário.
Você pode executar todos os comandos deste artigo na nuvem ou localmente:
Saiba como criar, gerenciar e conceder permissões para identidades de carga de trabalho, que permitem que seus fluxos de trabalho de implantação se autentiquem com segurança ao Azure.
Demonstrar os recursos do Microsoft Entra ID para modernizar as soluções de identidade, implementar soluções híbridas e implementar a governança de identidade.