Configurar um aplicativo para confiar em uma identidade gerenciada

2025-07-14

Este artigo descreve como configurar um aplicativo do Microsoft Entra para confiar em uma identidade gerenciada. Em seguida, você pode trocar o token de identidade gerenciada por um token de acesso que possa acessar recursos protegidos do Microsoft Entra sem precisar usar ou gerenciar segredos do aplicativo.

Pré-requisitos

Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
Essa conta do Azure deve ter permissões para atualizar as credenciais do aplicativo. Qualquer uma das seguintes funções do Microsoft Entra inclui as permissões necessárias:
Uma compreensão dos conceitos em identidades gerenciadas para recursos do Azure.
Uma identidade gerenciada atribuída pelo usuário atribuída ao recurso de computação do Azure (por exemplo, uma máquina virtual ou o Serviço de Aplicativo do Azure) que hospeda sua carga de trabalho.
Um registro de aplicação no Microsoft Entra ID. Esse registro de aplicativo precisa pertencer ao mesmo locatário que a identidade gerenciada
- Se você precisar acessar recursos em outro locatário, o registro do aplicativo deverá ser um aplicativo multilocatário e provisionado no outro locatário. Saiba mais sobre como adicionar um aplicativo multilocatário em outros locatários.
O registro do aplicativo precisa ter acesso concedido aos recursos protegidos do Microsoft Entra (por exemplo, Azure, Microsoft Graph, Microsoft 365 etc.). Esse acesso pode ser concedido por meio de permissões de API ou permissões delegadas.

Considerações e restrições importantes

Para criar, atualizar ou excluir uma credencial de identidade federada, a conta que executa a ação deve ter a função administrador de aplicativos , do Desenvolvedor de Aplicativos, de Administrador de Aplicativos na Nuvem ou Proprietário do Aplicativo. A permissão microsoft.directory/applications/credentials/update é necessária para atualizar uma credencial de identidade federada.

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:

emissor, assunto são as principais informações necessárias para configurar a relação de confiança. Quando a carga de trabalho do Azure solicita à plataforma de identidade da Microsoft trocar o token de identidade gerenciada por um token de acesso do aplicativo Entra, os valores de emissor e assunto da credencial de identidade federada são verificados em relação às declarações issuer e subject fornecidas no token de Identidade Gerenciada. 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.
emissor é a URL da URL de Autoridade do locatário do Microsoft Entra no formulário https://login.microsoftonline.com/{tenant}/v2.0. O aplicativo Microsoft Entra e a identidade gerenciada devem pertencer ao mesmo locatário. Se a declaração issuer tiver um espaço em branco à esquerda ou à direita no valor, a troca de tokens será bloqueada.
subject: este é o GUID sensível a maiúsculas e minúsculas da ID de Objeto (Identidade Principal) da identidade gerenciada atribuída à workload do Azure. A identidade gerenciada deve estar no mesmo locatário que o registro do aplicativo, mesmo que o recurso de destino esteja em uma nuvem diferente. A plataforma de identidade da Microsoft rejeitará a troca de tokens se subject na configuração de credencial da identidade federada não corresponder exatamente à ID da entidade de segurança da identidade gerenciada.
audiências especificam o valor que aparece na aud declaração no token de identidade gerenciada (Obrigatório). O valor deve ser um dos seguintes, dependendo da nuvem de destino.
- Serviço global de identidade do Microsoft Entra: api://AzureADTokenExchange
- Microsoft Entra ID para o Governo dos EUA: api://AzureADTokenExchangeUSGov
- Microsoft Entra China operado pela 21Vianet: api://AzureADTokenExchangeChina
Importante

Há suporte para acessar recursos em outro locatário . Não há suporte para acessar recursos em outra nuvem . As solicitações de token para outras nuvens falharão.

Importante

Se você adicionar acidentalmente as informações incorretas na configuração issuer, subject ou audience, 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.
o nome é o identificador exclusivo da credencial de identidade federada. (Necessário) 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, e o primeiro caractere precisa ser apenas alfanumérico. Após criado, ele será imutável.
descrição é a descrição fornecida pelo usuário da credencial de identidade federada (opcional). A descrição não é validada ou verificada pelo Microsoft Entra ID. Esse campo tem um limite de 600 caracteres.

Não há suporte para caracteres curinga nos valores da propriedade de credencial de identidade federada.

Configurar uma credencial de identidade federada em um aplicativo

Nesta seção, você configurará uma credencial de identidade federada em um aplicativo existente para confiar em uma identidade gerenciada. Use as guias a seguir para escolher como configurar uma credencial de identidade federada em um aplicativo existente.

Entre no Centro de administração do Microsoft Entra. Verifique se você está no locatário em que seu aplicativo está registrado.
Navegue atéregistros do aplicativo> e selecione seu aplicativo na janela principal.
Em Gerenciar, selecione Certificados &segredos.
Selecione a guia Credenciais Federadas e selecione Adicionar credencial.

No Cenário de credencial federada, na lista suspensa, selecione Identidade Gerenciada e preencha os valores de acordo com a tabela a seguir:

Campo	Descrição	Exemplo
Emissor	A URL do emissor OAuth 2.0/OIDC da autoridade do Microsoft Entra ID que emite o token de identidade gerenciada. Esse valor é preenchido automaticamente com o emissor do locatário do Entra atual.	`https://login.microsoftonline.com/{tenantID}/v2.0`
Selecionar identidade gerenciada	Clique neste link para selecionar a identidade gerenciada que atuará como a credencial de identidade federada. Você só pode usar User-Assigned Identidades Gerenciadas como uma credencial.	msi-webapp1
Descrição (opcional)	Uma descrição fornecida pelo usuário da credencial de identidade federada.	Confiar no UAMI dos workloads como uma credencial para meu aplicativo
Público	O valor de público-alvo que deve aparecer no token externo.	Deve ser definido como um dos seguintes valores: • Serviço Global do Entra ID: api://AzureADTokenExchange • Entra ID para Governo dos EUA: api://AzureADTokenExchangeUSGov • Entra ID China operado pela 21Vianet: api://AzureADTokenExchangeChina

Captura de tela da janela de credencial no Centro de administração do Microsoft Entra.

Abra um terminal no IDE preferido e execute o comando a seguir para criar uma credencial de identidade federada em seu aplicativo.

az ad app federated-credential create --id 00001111-aaaa-2222-bbbb-3333cccc4444 --parameters credential.json

O id parâmetro especifica a ID do aplicativo (ID do objeto). O parameters parâmetro especifica a configuração de credencial de identidade federada, no formato JSON.

Este é um exemplo para o conteúdo de credential.json. Substitua o GUID subject pelo ID do objeto (principal) da identidade gerenciada e o {tenantID} pelo ID do locatário do seu aplicativo. O valor de audiência deve ser definido como um dos seguintes valores:
• Serviço Global do Entra ID: api://AzureADTokenExchange
• Entra ID para Governo dos EUA: api://AzureADTokenExchangeUSGov
• Entra ID China operado pela 21Vianet: api://AzureADTokenExchangeChina

{
    "name": "msi-webapp1",
    "issuer": "https://login.microsoftonline.com/{tenantID}/v2.0",
    "subject": "00001111-aaaa-2222-bbbb-3333cccc4444",
    "description": "Trust the workload's UAMI to impersonate the App",
    "audiences": [
        "api://AzureADTokenExchange"
    ]
}

Abra um terminal do PowerShell no IDE preferido e execute o comando a seguir para criar uma credencial de identidade federada em seu aplicativo. Substitua o GUID Subject pelo ID do objeto (principal) da identidade gerenciada e o {tenantID} pelo ID do locatário do seu aplicativo.

O valor de audiência deve ser definido como um dos seguintes valores:
• Serviço Global do Entra ID: api://AzureADTokenExchange
• Entra ID para Governo dos EUA: api://AzureADTokenExchangeUSGov
• Entra ID China operado pela 21Vianet: api://AzureADTokenExchangeChina

New-AzADAppFederatedCredential -ApplicationObjectId $appObjectId -Audience api://AzureADTokenExchange -Issuer 'https://login.microsoftonline.com/{tenantID}/v2.0' -Name 'MyMsiFic' -Subject 'aaaabbbb-0000-cccc-1111-dddd2222eeee'

Abra um terminal no IDE preferido e execute o comando a seguir para criar uma credencial de identidade federada em seu aplicativo. Defina o valor de subject como a ID do objeto (entidade de segurança) da identidade gerenciada e {tenantID} pela ID de locatário do aplicativo.

az rest --method POST --uri 'https://graph.microsoft.com/applications/{app_registration_id}/federatedIdentityCredentials' --body '{"name":"MyMsiFicTest","issuer":"https://login.microsoftonline.com/{tenantID}/v2.0","subject":"{Managed_Identity_Principal_ID}","description":"Trust the workloads UAMI to impersonate the App","audiences":["api://AzureADTokenExchange"]}'

Este exemplo mostra como usar o Bicep para criar um FIC para fazer seu aplicativo confiar na identidade gerenciada atribuída. Substitua os espaços reservados pelos valores apropriados.

extension 'br:mcr.microsoft.com/bicep/extensions/microsoftgraph/v1.0:0.1.8-preview'

param myWorkloadManagedIdentity string = '[MANAGED-IDENTITY-NAME]'
param applicationDisplayName string = '[APPLICATION-DISPLAYNAME]'
param applicationName string = '[APPLICATION-UNIQUE-NAME]'

resource myManagedIdentity 'Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31' existing = {
  name: myWorkloadManagedIdentity
}

resource myApp 'Microsoft.Graph/applications@v1.0' = {
  displayName: applicationDisplayName
  uniqueName: applicationName

  resource myMsiFic 'federatedIdentityCredentials@v1.0' = {
    name: '${myApp.uniqueName}/msiAsFic'
    description: 'Trust the workloads UAMI to impersonate the App'
    audiences: [
       'api://AzureADTokenExchange'
    ]
    issuer: '${environment().authentication.loginEndpoint}${tenant().tenantId}/v2.0'
    subject: myManagedIdentity.properties.principalId
  }
}

Atualizar o código do aplicativo para solicitar um token de acesso

Os snippets de código a seguir demonstram como adquirir um token de identidade gerenciado e usá-lo como uma credencial para seu aplicativo Entra. Os exemplos são válidos em ambos os casos em que o recurso de destino no mesmo locatário do aplicativo Entra ou em um locatário diferente.

bibliotecas de clientes do Azure Identity

Os exemplos de código a seguir demonstram o acesso a um segredo do Azure Key Vault, mas podem ser adaptados para acessar qualquer recurso protegido pelo Microsoft Entra.

using Azure.Core;
using Azure.Identity;
using Azure.Security.KeyVault.Secrets;

// Audience value must be one of the below values depending on the target cloud:
// - Entra ID Global cloud: api://AzureADTokenExchange
// - Entra ID US Government: api://AzureADTokenExchangeUSGov
// - Entra ID China operated by 21Vianet: api://AzureADTokenExchangeChina
string miAudience = "api://AzureADTokenExchange";

// Create an assertion with the managed identity access token, so that it can be
// exchanged for an app token. Client ID is passed here. Alternatively, either
// object ID or resource ID can be passed.
ManagedIdentityCredential miCredential = new(
    ManagedIdentityId.FromUserAssignedClientId("<YOUR_MI_CLIENT_ID>"));
TokenRequestContext tokenRequestContext = new([$"{miAudience}/.default"]);
ClientAssertionCredential clientAssertionCredential = new(
    "<YOUR_RESOURCE_TENANT_ID>",
    "<YOUR_APP_CLIENT_ID>",
    async _ =>
        (await miCredential
            .GetTokenAsync(tokenRequestContext)
            .ConfigureAwait(false)).Token
);

// Create a new SecretClient using the assertion
SecretClient client = new(
    new Uri("https://testfickv.vault.azure.net/"), 
    clientAssertionCredential);

// Retrieve the secret
KeyVaultSecret secret = client.GetSecret("<SECRET_NAME>");

package main

import (
  "context"
  "log"

  "github.com/Azure/azure-sdk-for-go/sdk/azcore/policy"
  "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
  "github.com/Azure/azure-sdk-for-go/sdk/security/keyvault/azsecrets"
)

func main() {
  // Audience value must be one of the below values depending on the target cloud:
  // - Entra ID Global cloud: api://AzureADTokenExchange
  // - Entra ID US Government: api://AzureADTokenExchangeUSGov
  // - Entra ID China operated by 21Vianet: api://AzureADTokenExchangeChina
  azScopes := []string{"api://AzureADTokenExchange/.default"}

  // Client ID is passed here. Alternatively, either object ID or resource ID can be passed.
  mic, err := azidentity.NewManagedIdentityCredential(
    &azidentity.ManagedIdentityCredentialOptions{
      ID: azidentity.ClientID("<YOUR_MI_CLIENT_ID>"),
    },
  )
  if err != nil {
    log.Fatal("error constructing managed identity credential: ", err)
  }

  getAssertion := func(ctx context.Context) (string, error) {
    tk, err := mic.GetToken(ctx, policy.TokenRequestOptions{Scopes: azScopes})
    return tk.Token, err
  }
  cred, err := azidentity.NewClientAssertionCredential("<YOUR_TENANT_ID>", "<YOUR_APP_CLIENT_ID>", getAssertion, nil)
  if err != nil {
    log.Fatal("error constructing client assertion credential: ", err)
  }

  client := azsecrets.NewClient("https://testfickv.vault.azure.net", cred, nil)
	resp, err := client.GetSecret(context.TODO(), "<SECRET_NAME>", "", nil)
	if err != nil {
		// TODO: handle error
	}
}

import com.azure.core.credential.TokenRequestContext;
import com.azure.core.credential.*;
import com.azure.identity.*;
import com.azure.security.keyvault.secrets.SecretClient;
import com.azure.security.keyvault.secrets.SecretClientBuilder;
import com.azure.security.keyvault.secrets.models.KeyVaultSecret;

import reactor.core.publisher.Mono;

public class KeyVaultFIC {
  // Audience value must be one of the below values depending on the target cloud:
  // - Entra ID Global cloud: api://AzureADTokenExchange
  // - Entra ID US Government: api://AzureADTokenExchangeUSGov
  // - Entra ID China operated by 21Vianet: api://AzureADTokenExchangeChina
  private static final String MI_AUDIENCE = "api://AzureADTokenExchange";

  public static void main(String[] args) throws Exception {
    ClientAssertionCredential clientAssertionCredential = new ClientAssertionCredentialBuilder()
        .tenantId("<YOUR_TENANT_ID>")
        .clientId("<YOUR_APP_CLIENT_ID>")
        .clientAssertion(() -> getTokenUsingManagedIdentity(MI_AUDIENCE).block())
        .build();

    SecretClient secretClient = new SecretClientBuilder()
        .vaultUrl("https://testfickv.vault.azure.net")
        .credential(clientAssertionCredential)
        .buildClient();

    KeyVaultSecret secret = secretClient.getSecret("<SECRET_NAME>");
  }

  private static Mono<String> getTokenUsingManagedIdentity(String audience) {
    // Client ID is passed here. Alternatively, either object ID or resource ID can be passed.
    ManagedIdentityCredential managedIdentityCredential = new ManagedIdentityCredentialBuilder()
        .clientId("<YOUR_MI_CLIENT_ID>")
        .build();
    TokenRequestContext requestContext = new TokenRequestContext()
        .addScopes(audience + "/.default");

    return managedIdentityCredential
        .getToken(requestContext)
        .map(accessToken -> accessToken.getToken());
  }
}

import { ManagedIdentityCredential, ClientAssertionCredential, TokenCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";

// Audience value must be one of the below values depending on the target cloud:
// - Entra ID Global cloud: api://AzureADTokenExchange
// - Entra ID US Government: api://AzureADTokenExchangeUSGov
// - Entra ID China operated by 21Vianet: api://AzureADTokenExchangeChina
const MI_AUDIENCE: string = "api://AzureADTokenExchange";

async function getAccessToken(credential: TokenCredential, audience: string[]): Promise<string> {
    const accessToken = await credential.getToken(audience);
    const token = accessToken?.token;
    if (!token)
        throw new Error(`Failed to obtain valid access token, received ${token}`);
    return token;
}

const main = async () => {
    // Client ID is passed here. Alternatively, either object ID or resource ID can be passed.
    const managedIdentityCredential = new ManagedIdentityCredential(
    {
        clientId: "<YOUR_MI_CLIENT_ID>"
    });
    const clientAssertionCredential = new ClientAssertionCredential(
        "<YOUR_TENANT_ID>",
        "<YOUR_APP_CLIENT_ID>",
        () => getAccessToken(managedIdentityCredential, [`${MI_AUDIENCE}/.default`]));
    const client = new SecretClient("https://testfickv.vault.azure.net", clientAssertionCredential);

    try {
        const secret = await client.getSecret("<SECRET_NAME>");
        console.log("Found the secret from Key Vault");
    } catch (error) {
        console.error("Failed to retrieve secret:", error);
        throw error;
    }
};

main();

from azure.identity import ManagedIdentityCredential, ClientAssertionCredential
from azure.keyvault.secrets import SecretClient

# Audience value must be one of the below values depending on the target cloud:
# - Entra ID Global cloud: api://AzureADTokenExchange
# - Entra ID US Government: api://AzureADTokenExchangeUSGov
# - Entra ID China operated by 21Vianet: api://AzureADTokenExchangeChina
MI_AUDIENCE = "api://AzureADTokenExchange"

def get_managed_identity_token(credential, audience):
    return credential.get_token(audience).token

# Client ID is passed here. Alternatively, either object ID or resource ID can be passed.
managed_identity_credential = ManagedIdentityCredential(client_id="<YOUR_MI_CLIENT_ID>")

client_assertion_credential = ClientAssertionCredential(
    "<YOUR_RESOURCE_TENANT_ID>",
    "<YOUR_APP_CLIENT_ID>",
    lambda: get_managed_identity_token(managed_identity_credential, f"{MI_AUDIENCE}/.default"))

client = SecretClient(
    vault_url="https://testfickv.vault.azure.net",
    credential=client_assertion_credential)
retrieved_secret = client.get_secret("<SECRET_NAME>")

Microsoft.Identity.Web

No Microsoft.Identity.Web, você pode definir a ClientCredentials seção em seu appsettings.json para usar SignedAssertionFromManagedIdentity e habilitar seu código a empregar a identidade gerenciada configurada como uma credencial:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "ClientId": "YOUR_APPLICATION_ID",
    "TenantId": "YOUR_TENANT_ID",
    
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity",
        "ManagedIdentityClientId": "YOUR_USER_ASSIGNED_MANAGED_IDENTITY_CLIENT_ID",
        "TokenExchangeUrl": "api://AzureADTokenExchange/.default"
      }
    ]
  }
}

MSAL (.NET)

Na MSAL, você pode usar a classe ManagedClientApplication para adquirir um token de Identidade Gerenciada. Esse token pode ser usado como uma declaração de cliente ao construir um aplicativo cliente confidencial.

using Microsoft.Identity.Client;
using Microsoft.Identity.Client.AppConfig;
using Azure.Storage.Blobs;
using Azure.Core;
using Azure.Storage.Blobs.Models;

internal class Program
{
  static async Task Main(string[] args)
  {
      string storageAccountName = "YOUR_STORAGE_ACCOUNT_NAME";
      string containerName = "CONTAINER_NAME";

      string appClientId = "YOUR_APP_CLIENT_ID";
      string resourceTenantId = "YOUR_RESOURCE_TENANT_ID";
      Uri authorityUri = new($"https://login.microsoftonline.com/{resourceTenantId}");
      string miClientId = "YOUR_MI_CLIENT_ID";
      string audience = "api://AzureADTokenExchange/.default";

      // Get mi token to use as assertion
      var miAssertionProvider = async (AssertionRequestOptions _) =>
      {
            var miApplication = ManagedIdentityApplicationBuilder
                .Create(ManagedIdentityId.WithUserAssignedClientId(miClientId))
                .Build();

            var miResult = await miApplication.AcquireTokenForManagedIdentity(audience)
                .ExecuteAsync()
                .ConfigureAwait(false);
            return miResult.AccessToken;
      };

      // Create a confidential client application with the assertion.
      IConfidentialClientApplication app = ConfidentialClientApplicationBuilder.Create(appClientId)
        .WithAuthority(authorityUri, false)
        .WithClientAssertion(miAssertionProvider)
        .WithCacheOptions(CacheOptions.EnableSharedCacheOptions)
        .Build();

        // Get the federated app token for the storage account
        string[] scopes = [$"https://{storageAccountName}.blob.core.windows.net/.default"];
        AuthenticationResult result = await app.AcquireTokenForClient(scopes).ExecuteAsync().ConfigureAwait(false);

        TokenCredential tokenCredential = new AccessTokenCredential(result.AccessToken);
        var containerClient = new BlobContainerClient(
            new Uri($"https://{storageAccountName}.blob.core.windows.net/{containerName}"),
            tokenCredential);

        await foreach (BlobItem blob in containerClient.GetBlobsAsync())
        {
            // TODO: perform operations with the blobs
            BlobClient blobClient = containerClient.GetBlobClient(blob.Name);
            Console.WriteLine($"Blob name: {blobClient.Name}, URI: {blobClient.Uri}");
        }
    }
}

Confira também

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