Compartilhar via

Considerações e restrições importantes para credenciais de identidade federadas

  • Artigo

Este artigo descreve considerações importantes, restrições e limitações para credenciais de identidade federada em aplicativos do Microsoft Entra e identidades atribuídas pelo usuário gerenciadas.

Para obter mais informações sobre os cenários habilitados por credenciais de identidade federadas, confira a visão geral da federação de identidade de carga de trabalho.

Considerações gerais sobre credenciais de identidade federadas

Aplica-se a: aplicativos e identidades gerenciadas atribuídas pelo usuário

Qualquer pessoa com permissões para criar um registro de aplicativo e adicionar um segredo ou certificado pode adicionar uma credencial de identidade federada a um aplicativo. Se a opção Usuários podem registrar aplicativos estiver definida como Não na folha Usuários->Configurações do Usuário no Centro de administração do Microsoft Entra, no entanto, você não poderá criar um registro de aplicativo ou configurar a credencial de identidade federada. Encontre um administrador para configurar a credencial de identidade federada em seu nome, alguém que tenha uma das funções de Administrador do Aplicativo ou Proprietário do Aplicativo.

As credenciais de federação de identidade não consomem a cota de objeto da entidade de serviço do locatário do Microsoft Entra.

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.

Regiões sem suporte (identidades gerenciadas atribuídas pelo usuário)

Aplica-se a: identidades gerenciadas atribuídas pelo usuário

Atualmente, não há suporte para a criação de credenciais de identidade federadas em identidades gerenciadas atribuídas pelo usuário criadas nas seguintes regiões:

  • Leste da Ásia
  • Catar Central
  • Sul da Malásia
  • Norte da Itália
  • Israel Central
  • México Central

O suporte para a criação de credenciais de identidade federadas em identidades atribuídas pelo usuário nessas regiões será gradualmente distribuído. Os recursos nessa região que precisam usar credenciais de identidade federadas podem fazer isso aproveitando uma identidade gerenciada atribuída pelo usuário criada em uma região com suporte.

Emissores e algoritmos de assinatura com suporte

Aplica-se a: aplicativos e identidades gerenciadas atribuídas pelo usuário

Somente emissores que fornecem tokens assinados usando o algoritmo RS256 são compatíveis com a troca de tokens usando a federação de identidade de carga de trabalho. A troca de tokens assinados com outros algoritmos pode funcionar, mas não foi testada.

Os emissores do Microsoft Entra não são suportados

Aplica-se a: aplicativos e identidades gerenciadas atribuídas pelo usuário

Não é possível criar uma federação entre duas identidades do Microsoft Entra do mesmo locatário ou de locatários diferentes. Ao criar uma credencial de identidade federada, não há suporte para configurar o emissor (a URL do provedor de identidade externo) com os seguintes valores:

  • *.login.microsoftonline.com
  • *.login.windows.net
  • *.login.microsoft.com
  • *.sts.windows.net

Embora seja possível criar uma credencial de identidade federada com um emissor do Microsoft Entra, as tentativas de usá-la para autorização falham com o erro AADSTS700222: AAD-issued tokens may not be used for federated identity flows.

Tempo para as alterações de credencial federada serem propagadas

Aplica-se a: aplicativos e identidades gerenciadas atribuídas pelo usuário

Leva tempo para que a credencial de identidade federada seja propagada em toda uma região depois de ser configurada inicialmente. Uma solicitação de token feita vários minutos depois de configurar a credencial de identidade federada pode falhar porque o cache é preenchido no diretório com os dados antigos. Durante essa janela de tempo, uma solicitação de autorização pode falhar com a mensagem de erro: AADSTS70021: No matching federated identity record found for presented assertion.

Para evitar esse problema, aguarde um tempo curto após adicionar a credencial de identidade federada antes de solicitar um token para garantir que a replicação seja concluída em todos os nós do serviço de autorização. Também recomendamos adicionar lógica de repetição para solicitações de token. As novas tentativas deverão ser feitas para cada solicitação, mesmo depois que um token foi obtido com êxito. Eventualmente, depois que os dados forem totalmente replicados, o percentual de falhas diminuirá.

Não há suporte para atualizações simultâneas (identidades gerenciadas atribuídas pelo usuário)

Aplica-se a: identidades gerenciadas atribuídas pelo usuário

A criação de várias credenciais de identidade federadas sob a mesma identidade gerenciada atribuída pelo usuário dispara simultaneamente a lógica de detecção de simultaneidade, o que faz com que as solicitações falhem com o código de status HTTP 409 – conflito.

O Provedor Terraform para Azure (Resource Manager) versão 3.40.0 apresenta uma atualização que cria várias credenciais de identidade federadas na sequência em vez de simultaneamente. As versões anteriores à 3.40.0 podem causar falhas em pipelines quando identidades federadas múltiplas são criadas. Recomendamos que você use o Provedor Terraform para Azure (Resource Manager) v3.40.0 ou posterior, de modo que várias credenciais de identidade federadas sejam criadas sequencialmente.

Quando você usa a automação ou modelos do ARM (Azure Resource Manager) para criar credenciais de identidade federadas na mesma identidade pai, deve criar as credenciais federadas sequencialmente. As credenciais de identidade federada em diferentes identidades gerenciadas podem ser criadas em paralelo sem restrições.

Se as credenciais de identidade federadas forem provisionadas em um loop, você poderá provisioná-las em série definindo "mode": "serial".

Você também pode provisionar várias novas credenciais de identidade federadas sequencialmente usando a propriedade dependsOn. O exemplo de modelo do ARM (Azure Resource Manager) a seguir cria três novas credenciais de identidade federadas sequencialmente em uma identidade gerenciada atribuída pelo usuário usando a propriedade dependsOn:

{ 
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#", 
    "contentVersion": "1.0.0.0", 
    "parameters": { 
        "userAssignedIdentities_parent_uami_name": { 
            "defaultValue": "parent_uami", 
            "type": "String" 
        } 
    }, 
    "variables": {}, 
    "resources": [ 
        { 
            "type": "Microsoft.ManagedIdentity/userAssignedIdentities", 
            "apiVersion": "2022-01-31-preview", 
            "name": "[parameters('userAssignedIdentities_parent_uami_name')]", 
            "location": "eastus" 
        }, 
        { 
            "type": "Microsoft.ManagedIdentity/userAssignedIdentities/federatedIdentityCredentials", 
            "apiVersion": "2022-01-31-preview", 
            "name": "[concat(parameters('userAssignedIdentities_parent_uami_name'), '/fic01')]", 
            "dependsOn": [ 
                "[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('userAssignedIdentities_parent_uami_name'))]" 
            ], 
            "properties": { 
                "issuer": "https://kubernetes-oauth.azure.com", 
                "subject": "fic01", 
                "audiences": [ 
                    "api://AzureADTokenExchange" 
                ] 
            } 
        }, 
        { 
            "type": "Microsoft.ManagedIdentity/userAssignedIdentities/federatedIdentityCredentials", 
            "apiVersion": "2022-01-31-preview", 
            "name": "[concat(parameters('userAssignedIdentities_parent_uami_name'), '/fic02')]", 
            "dependsOn": [ 
                "[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('userAssignedIdentities_parent_uami_name'))]", 
                "[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities/federatedIdentityCredentials', parameters('userAssignedIdentities_parent_uami_name'), 'fic01')]" 
            ], 
            "properties": { 
                "issuer": "https://kubernetes-oauth.azure.com", 
                "subject": "fic02", 
                "audiences": [ 
                    "api://AzureADTokenExchange" 
                ] 
            } 
        }, 
        { 
            "type": "Microsoft.ManagedIdentity/userAssignedIdentities/federatedIdentityCredentials", 
            "apiVersion": "2022-01-31-preview", 
            "name": "[concat(parameters('userAssignedIdentities_parent_uami_name'), '/fic03')]", 
            "dependsOn": [ 
                "[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('userAssignedIdentities_parent_uami_name'))]", 
                "[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities/federatedIdentityCredentials', parameters('userAssignedIdentities_parent_uami_name'), 'fic02')]" 
            ], 
            "properties": { 
                "issuer": "https://kubernetes-oauth.azure.com", 
                "subject": "fic03", 
                "audiences": [ 
                    "api://AzureADTokenExchange" 
                ] 
            } 
        } 
    ] 
}

Azure Policy

Aplica-se a: aplicativos e identidades gerenciadas atribuídas pelo usuário

É possível usar uma política do Azure de negação como no seguinte exemplo de modelo do ARM:

{ 
"policyRule": { 
            "if": { 
                "field": "type", 
                "equals": "Microsoft.ManagedIdentity/userAssignedIdentities/federatedIdentityCredentials" 
            }, 
            "then": { 
                "effect": "deny" 
            } 
        } 
}

Limitações

Aplica-se a: identidades gerenciadas atribuídas pelo usuário

A tabela a seguir descreve os limites de solicitações para as APIS REST de identidades gerenciadas atribuídas pelo usuário. Se você exceder um limite de limitação, receberá um erro HTTP 429.

Operação Solicitações por segundo por locatário do Microsoft Entra Solicitações por segundo por assinatura Solicitações por segundo por recurso
Solicitações CREATE ou UPDATE 10 2 0,25
Solicitações GET 30 10 0,5
Solicitações de Listar por grupo de recursos ou Listar por assinatura 15 5 0,25
Solicitações DELETE 10 2 0,25

Errors

Aplica-se a: aplicativos e identidades gerenciadas atribuídas pelo usuário

Os códigos de erro a seguir podem ser retornados ao criar, atualizar, obter, listar ou excluir credenciais de identidade federadas.

Código HTTP Mensagem de erro Comentários
405 O formato da solicitação era inesperado: suporte para credenciais de identidade federadas não habilitado. As credenciais de identidade federadas não estão habilitadas nessa região. Consulte "Regiões com suporte atualmente".
400 As credenciais de identidade federadas precisam ter exatamente um público-alvo. Atualmente, as credenciais de identidade federadas dão suporte a apenas um público, "api://AzureADTokenExchange".
400 A credencial de identidade federada do corpo HTTP tem propriedades vazias Todas as propriedades de credencial de identidade federada são obrigatórias.
400 O nome da credencial de identidade federada "{ficName}" é inválido. Alfanumérico, traço, sublinhado, não mais do que 3-120 símbolos. O primeiro símbolo é alfanumérico.
404 A identidade atribuída pelo usuário pai não existe. Verifique o nome da identidade atribuída pelo usuário no caminho do recurso de credenciais de identidade federadas.
400 A combinação de emissor e assunto já existe para essa Identidade Gerenciada. Essa é uma restrição. Liste todas as credenciais de identidade federadas associadas à identidade atribuída pelo usuário para localizar a credencial de identidade federada existente.
409 Conflito A solicitação de gravação simultânea para recursos de credencial de identidade federada sob a mesma identidade atribuída pelo usuário foi negada.