Compartilhar via


Configurar uma identidade gerenciada atribuída pelo usuário para confiar em um provedor de identidade externo

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.

Para saber mais sobre regiões com suporte, tempo para propagar atualizações de credenciais federadas, emissores com suporte e muito mais, leia Considerações e restrições importantes para credenciais de identidade federada.

Pré-requisitos

Configurar uma credencial de identidade federada em uma identidade gerenciada atribuída pelo usuário

No centro de administração do Microsoft Entra, 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:

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

  2. Adicione um Nome para a credencial federada.

  3. Os campos Emissor, Audiências e Identificador de assunto são preenchidos automaticamente com base nos valores inseridos.

  4. 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.

    Captura de tela que demonstra como copiar a ID de identidade gerenciada e a ID da assinatura do portal do Azure.

  • AZURE_TENANT_ID a ID do diretório (locatário). Saiba como encontrar sua ID de locatário do Microsoft Entra.

Exemplos de tipos de entidades

Exemplo de branch

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:

  • A URL do emissor do cluster é a URL do emissor do OIDC para o cluster gerenciado ou a URL do Emissor do OIDC para um cluster auto-gerenciado.
  • 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 centro de administração do Microsoft Entra, 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 centro de administração do Microsoft Entra, 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.

Pré-requisitos

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

Execute o comando az identity federated-credential show para mostrar uma credencial de identidade federada (por ID):

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

Pré-requisitos

Configurar o Azure PowerShell localmente

Para usar o Azure PowerShell localmente para este artigo em vez de usar Cloud Shell:

  1. Instale a versão mais recente do Azure PowerShell se ainda não o fez.

  2. Entre no Azure.

    Connect-AzAccount
    
  3. Instale a versão mais recente do PowerShellGet.

    Install-Module -Name PowerShellGet -AllowPrerelease
    

    Talvez seja necessário Exit da sessão atual do PowerShell depois de executar esse comando para a próxima etapa.

  4. 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.

New-AzFederatedIdentityCredentials -ResourceGroupName azure-rg-test -IdentityName uai-pwsh01 `
    -Name fic-pwsh01 -Issuer "https://kubernetes-oauth.azure.com" -Subject "system:serviceaccount:ns:svcaccount"

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:

Get-AzFederatedIdentityCredentials -ResourceGroupName azure-rg-test -IdentityName uai-pwsh01

Obter uma credencial de identidade federada em uma identidade gerenciada atribuída pelo usuário

Execute o comando Get-AzFederatedIdentityCredentials para mostrar uma credencial de identidade federada (por nome):

Get-AzFederatedIdentityCredentials -ResourceGroupName azure-rg-test -IdentityName uai-pwsh01 -Name fic-pwsh01

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.

Remove-AzFederatedIdentityCredentials -ResourceGroupName azure-rg-test -IdentityName uai-pwsh01 -Name fic-pwsh01

Pré-requisitos

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.

{

    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "variables": {},
    "parameters": {
        "location": {
            "type": "string",
            "defaultValue": "westcentralus",
            "metadata": {
                "description": "Location for identities resources. FIC should be enabled in this region."
            }
        },
        "userAssignedIdentityName": {
            "type": "string",
            "defaultValue": "FIC_UA",
            "metadata": {
                "description": "Name of the User Assigned identity (parent identity)"
            }
        },
        "federatedIdentityCredential": {
            "type": "string",
            "defaultValue": "testCredential",
            "metadata": {
                "description": "Name of the Federated Identity Credential"
            }
        },
        "federatedIdentityCredentialIssuer": {
            "type": "string",
            "defaultValue": "https://aks.azure.com/issuerGUID",
            "metadata": {
                "description": "Federated Identity Credential token issuer"
            }
        },
        "federatedIdentityCredentialSubject": {
            "type": "string",
            "defaultValue": "system:serviceaccount:ns:svcaccount",
            "metadata": {
                "description": "Federated Identity Credential token subject"
            }
        },
        "federatedIdentityCredentialAudience": {
            "type": "string",
            "defaultValue": " api://AzureADTokenExchange",
            "metadata": {
                "description": "Federated Identity Credential audience. Single value is only supported."
            }
        }
    },
    "resources": [
        {
            "type": "Microsoft.ManagedIdentity/userAssignedIdentities",
            "apiVersion": "2018-11-30",
            "name": "[parameters('userAssignedIdentityName')]",
            "location": "[parameters('location')]",
            "tags": {
                "firstTag": "ficTest"
            },
            "resources": [
                {
                    "type": "Microsoft.ManagedIdentity/userAssignedIdentities/federatedIdentityCredentials",
                    "apiVersion": "2022-01-31-PREVIEW",
                    "name": "[concat(parameters('userAssignedIdentityName'), '/', parameters('federatedIdentityCredential'))]",
                    "dependsOn": [
                      "[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('userAssignedIdentityName'))]"
                    ],
                    "properties": {
                        "issuer": "[parameters('federatedIdentityCredentialIssuer')]",
                        "subject": "[parameters('federatedIdentityCredentialSubject')]",
                        "audiences": [
                            "[parameters('federatedIdentityCredentialAudience')]"
                        ]
                    }
                }
            ]
        }
    ]
}

Pré-requisitos

Obter um token de acesso de portador

  1. Se estiver em execução localmente, entre no Azure pela CLI do Azure.

    az login
    
  2. Obter um token de acesso usando az account get-access-token.

    az account get-access-token
    

Configurar uma credencial de identidade federada em uma identidade gerenciada atribuída pelo usuário

Crie ou atualize uma credencial de identidade federada na identidade gerenciada atribuída pelo usuário especificada.

curl 'https://management.azure.com/subscriptions/<SUBSCRIPTION ID>/resourceGroups/<RESOURCE GROUP>/provider
s/Microsoft.ManagedIdentity/userAssignedIdentities/<USER ASSIGNED IDENTITY NAME>/federatedIdenti
tyCredentials/<FEDERATED IDENTITY CREDENTIAL NAME>?api-version=2022-01-31-preview' -X PUT -d '{"properties": "{ "properties": { "issuer": "<ISSUER>", "subject": "<SUBJECT>", "audiences": [ "api://AzureADTokenExchange" ] }}"}' -H "Content-Type: application/json" -H "Authorization: Bearer <ACCESS TOKEN>"
PUT https://management.azure.com/subscriptions/<SUBSCRIPTION ID>/resourceGroups/<RESOURCE GROUP>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<USER ASSIGNED IDENTITY NAME>/federatedIdentityCredentials/<FEDERATED IDENTITY CREDENTIAL NAME>?api-version=2022-01-31-preview

{
 "properties": {
 "issuer": "https://oidc.prod-aks.azure.com/IssuerGUID",
 "subject": "system:serviceaccount:ns:svcaccount",
 "audiences": [
 "api://AzureADTokenExchange"
 ]
 }
}

Cabeçalhos de solicitação

Cabeçalho da solicitação Descrição
Content-Type Obrigatórios. Defina como application/json.
Autorização Obrigatórios. Defina como um Bearer token de acesso válido.

Corpo da solicitação

Nome Descrição
properties.audiences Obrigatórios. A lista de públicos que podem aparecer no token emitido.
properties.issuer Obrigatórios. A URL do emissor a ser confiável.
properties.subject Obrigatórios. O identificador da identidade externa.

Listar credenciais de identidade federada em uma identidade gerenciada atribuída pelo usuário

Liste todas as credenciais de identidade federada na identidade gerenciada atribuída pelo usuário especificada.

curl 'https://management.azure.com/subscriptions/<SUBSCRIPTION ID>/resourceGroups/<RESOURCE GROUP>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<USER ASSIGNED IDENTITY NAME>/<RESOURCE NAME>/federatedIdentityCredentials?api-version=2022-01-31-preview' -H "Content-Type: application/json" -X GET -H "Authorization: Bearer <ACCESS TOKEN>"
GET
https://management.azure.com/subscriptions/<SUBSCRIPTION ID>/resourceGroups/<RESOURCE GROUP>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<USER ASSIGNED IDENTITY NAME>/<RESOURCE NAME>/federatedIdentityCredentials?api-version=2022-01-31-preview

Cabeçalhos de solicitação

Cabeçalho da solicitação Descrição
Content-Type Obrigatórios. Defina como application/json.
Autorização Obrigatórios. Defina como um Bearer token de acesso válido.

Obter uma credencial de identidade federada em uma identidade gerenciada atribuída pelo usuário

Obtenha uma credencial de identidade federada na identidade gerenciada atribuída pelo usuário especificada.

curl 'https://management.azure.com/subscriptions/<SUBSCRIPTION ID>/resourceGroups/<RESOURCE GROUP>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<USER ASSIGNED IDENTITY NAME>/<RESOURCE NAME>/federatedIdentityCredentials/<FEDERATED IDENTITY CREDENTIAL RESOURCENAME>?api-version=2022-01-31-preview' -X GET -H "Content-Type: application/json" -H "Authorization: Bearer <ACCESS TOKEN>"
GET
https://management.azure.com/subscriptions/<SUBSCRIPTION ID>/resourceGroups/<RESOURCE GROUP>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<USER ASSIGNED IDENTITY NAME>/<RESOURCE NAME>/federatedIdentityCredentials/<FEDERATED IDENTITY CREDENTIAL RESOURCENAME>?api-version=2022-01-31-preview

Cabeçalhos de solicitação

Cabeçalho da solicitação Descrição
Content-Type Obrigatórios. Defina como application/json.
Autorização Obrigatórios. Defina como um Bearer token de acesso válido.

Excluir uma credencial de identidade federada de uma identidade gerenciada atribuída pelo usuário

Exclua uma credencial de identidade federada na identidade gerenciada atribuída pelo usuário especificada.

curl 'https://management.azure.com/subscriptions/<SUBSCRIPTION ID>/resourceGroups/<RESOURCE GROUP>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<USER ASSIGNED IDENTITY NAME>/<RESOURCE NAME>/federatedIdentityCredentials/<FEDERATED IDENTITY CREDENTIAL RESOURCENAME>?api-version=2022-01-31-preview' -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer <ACCESS TOKEN>"
DELETE
https://management.azure.com/subscriptions/<SUBSCRIPTION ID>/resourceGroups/<RESOURCE GROUP>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<USER ASSIGNED IDENTITY NAME>/<RESOURCE NAME>/federatedIdentityCredentials/<FEDERATED IDENTITY CREDENTIAL RESOURCENAME>?api-version=2022-01-31-preview

Cabeçalhos de solicitação

Cabeçalho da solicitação Descrição
Content-Type Obrigatórios. Defina como application/json.
Autorização Obrigatórios. Defina como um Bearer token de acesso válido.

Próximas etapas

  • Para obter informações sobre o formato necessário de JWTs criado por provedores de identidade externos, leia sobre o formato de declaração.