Partilhar via

Configurar um aplicativo para confiar em uma identidade gerenciada

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

Pré-requisitos

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 o de Administrador de Aplicativos, de Desenvolvedor de Aplicativos, de Administrador de Aplicativos na Nuvem ou a função de 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 pode ser adicionado a um aplicativo ou identidade gerenciada atribuída pelo usuário.

Quando você configura uma credencial de identidade federada, há várias informações importantes a serem fornecidas:

  • emitente, 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 que a plataforma de identidade da Microsoft troque o token de identidade gerenciado por um token de acesso ao aplicativo Entra, os valores do emissor e do assunto da credencial de identidade federada são verificados em relação às issuer declarações fornecidas subject 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 à carga de trabalho de software externo.

  • emissor é o URL da Autoridade do tenant do Microsoft Entra no formato https://login.microsoftonline.com/{tenant}/v2.0. Tanto a aplicação Microsoft Entra como a identidade gerida devem pertencer ao mesmo inquilino. Se a declaração de issuer tiver espaço em branco à esquerda ou à direita no valor, a troca de token será bloqueada.

  • subject: Este é o GUID sensível a maiúsculas e minúsculas da ID de objeto (principal) da identidade gerida atribuída à carga de trabalho do Azure. A identidade gerida deve estar no mesmo inquilino que o registo da aplicação, mesmo que o recurso de destino esteja em uma nuvem diferente. A plataforma de identidade da Microsoft rejeitará a troca de tokens se o subject na configuração de credenciais de identidade federada não corresponder exatamente ao ID Principal da identidade gerida.

  • audiences especifica o valor que aparece na aud declaração no token de identidade gerenciado (Obrigatório). O valor deve ser um dos seguintes, dependendo da nuvem de destino.

    • Serviço global Microsoft Entra ID: api://AzureADTokenExchange
    • Microsoft Entra ID para o Governo dos EUA: api://AzureADTokenExchangeUSGov
    • Microsoft Entra China operado pela 21Vianet: api://AzureADTokenExchangeChina

    Importante

    O acesso a recursos em outro locatário é suportado. Não há suporte para o acesso a recursos em outra nuvem . Os pedidos de token para outras nuvens falharão.

    Importante

    Se adicionar acidentalmente informações incorretas nodo emissor , assunto ou público, a credencial de identidade federada será criada com sucesso e sem erro. O erro não se torna aparente até que a troca de token falhe.

  • name é o identificador exclusivo da credencial de identidade federada. (Obrigatório) Este campo tem um limite de caracteres de 3 a 120 caracteres e deve ser amigável para URL. Há suporte para caracteres alfanuméricos, traços ou sublinhados, e o primeiro caractere deve ser apenas alfanumérico. É imutável uma vez criado.

  • 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. Este campo tem um limite de 600 caracteres.

Não há suporte para caracteres universais em nenhum valor nas propriedades das credenciais de identidade federada.

Configure uma credencial de identidade federada numa aplicação

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.

  1. Entre no centro de administração do Microsoft Entra. Verifique se está no locatário onde a sua aplicação está registada.

  2. Navegue até Registros do aplicativo Entra ID> e selecione seu aplicativo na janela principal.

  3. Em Gerenciar, selecione Certificados & segredos.

  4. Selecione a guia Credenciais federadas e selecione Adicionar credencial.

    Captura de ecrã do painel de certificados e segredos do centro de administração do Microsoft Entra com o separador de credenciais federadas realçado.

  5. Na lista suspensa Cenário de credenciais federadas , selecione Identidade gerenciada e preencha os valores de acordo com a tabela a seguir:

    Campo Descrição Exemplo
    Emitente O URL do emissor OAuth 2.0 / OIDC da autoridade Microsoft Entra ID que emite o token de identidade gerida. Esse valor é preenchido automaticamente com o emissor atual do locatário do Entra. 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. Pode usar apenas Identidades Geridas Atribuídas pelo Utilizador como credencial. MSI-WebApp1
    Descrição (Opcional) Uma descrição fornecida pelo usuário da credencial de identidade federada. Confiar nas cargas de trabalho UAMI como uma credencial para o meu aplicativo
    Público-alvo O valor da audiência que deve aparecer no token externo. Deve ser configurado para um dos seguintes valores:
    • Serviço Global Entra ID: api://AzureADTokenExchange
    • Entra ID para o Governo dos EUA: api://AzureADTokenExchangeUSGov
    • Entra ID China operado pela 21Vianet: api://AzureADTokenExchangeChina

    Captura de ecrã da janela de credenciais no centro de administração do Microsoft Entra.

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

Os trechos 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 está no mesmo locatário que o aplicativo Entra ou em um locatário diferente.

Bibliotecas de cliente do Azure Identity

Os exemplos de código a seguir demonstram o acesso a um segredo do Cofre da Chave do Azure, 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>");

Microsoft.Identity.Web

Em Microsoft.Identity.Web, pode definir a ClientCredentials seção no seu appsettings.json para usar SignedAssertionFromManagedIdentity e permitir que o seu código utilize a identidade gerida configurada como 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)

No MSAL, você pode usar a classe ManagedClientApplication para adquirir um token de identidade gerenciada. Esse token pode ser usado como uma asserçã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}");
        }
    }
}

Ver também