Compartilhar via

Configurar um aplicativo para confiar em uma identidade gerenciada (versão prévia)

  • Artigo

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

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 federadas podem ser adicionadas 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:

  • 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 do Azure solicita à plataforma de identidade da Microsoft para trocar o token de Identidade Gerenciada por um token de acesso, os valores do emissor e do sujeito 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.

  • issuer é 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 espaço em branco à esquerda ou à direita no valor, a troca de tokens será bloqueada.

    Importante

    Embora o registro do aplicativo e a identidade gerenciada precisem estar no mesmo locatário, a entidade de serviço do registro do aplicativo ainda pode resgatar o token da identidade gerenciada.

  • subject é o GUID da ID de Objeto da Identidade Gerenciada (ID da Entidade de Segurança) atribuído à carga de trabalho do Azure. A plataforma de identidade da Microsoft examina o token externo de entrada e rejeita a troca de um token de acesso se o assunto campo configurado na Credencial de Identidade Federada não corresponder à ID principal da Identidade Gerenciada. O GUID diferencia maiúsculas e minúsculas.

  • Importante

    Você só pode usar Identidades Gerenciadas User-Assigned neste recurso.

  • *audiences listam os públicos-alvo que podem aparecer no token externo (obrigatório). Você deve adicionar um único valor de audiência, que tem um limite de 600 caracteres. O valor deve ser um dos seguintes e deve corresponder ao valor da declaração aud no token de Identidade Gerenciada.

    • Nuvem pública: api://AzureADTokenExchange
    • Fairfax: api://AzureADTokenExchangeUSGov
    • bolo de lua: api://AzureADTokenExchangeChina
    • USNat: api://AzureADTokenExchangeUSNat
    • USSec: api://AzureADTokenExchangeUSSec

    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 de tokens falhe.

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

  • descrição é 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 da propriedade de credencial de identidade federada.

Obter a ID do objeto da identidade gerenciada

  1. Entre no portal do Azure.
  2. Na caixa de pesquisa, insira Identidades gerenciadas. Em Services, selecione Identidades Gerenciadas.
  3. Pesquise e selecione a identidade gerenciada atribuída a usuário que você criou como parte dos pré-requisitos .
  4. No painel Visão geral, copie o valor da ID do objeto (entidade de segurança). Esse valor é usado como o campo subject na configuração de credencial federada.

Captura de tela de uma identidade gerenciada atribuída pelo usuário no portal do Azure. A ID do Objeto é realçada, que será usada como o campo *subject* na configuração de credencial federada.

Configurar uma credencial de identidade federada em um aplicativo existente

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 você está no locatário em que seu aplicativo está registrado.

  2. Navegue até Identidade>Aplicativos>Registros de aplicativo e selecione seu aplicativo na janela principal.

  3. Em Gerenciar, selecione Certificados e Segredos.

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

    Captura de tela do painel de certificados e segredos do Centro de administração da Microsoft Entra com a guia credenciais federadas realçada.

  5. No Cenário de credencial federada, na lista suspensa, selecione Outro emissor e preencha os valores de acordo com a seguinte tabela:

    Campo Descrição Exemplo
    Emissor A URL do emissor OAuth 2.0/OIDC da autoridade de ID do Microsoft Entra. https://login.microsoftonline.com/{tenantID}/v2.0
    Identificador de assunto A GUID Principal ID da Identidade Gerenciada. aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb
    Nome Um nome descritivo exclusivo para a credencial. msi-webapp1
    Descrição (opcional) Uma descrição fornecida pelo usuário da credencial de identidade federada. Confie nas cargas de trabalho UAMI para representar o aplicativo
    Público O valor de público-alvo que deve aparecer no token externo. • nuvem pública: api://AzureADTokenExchange
    • Fairfax: api://AzureADTokenExchangeUSGov
    • Mooncake: api://AzureADTokenExchangeChina
    • USNat: api://AzureADTokenExchangeUSNat
    • USSec: api://AzureADTokenExchangeUSSec

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

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

Os exemplos de código na tabela a seguir mostram fluxos de credencial de cliente "serviço a serviço". Porém, as identidades gerenciadas como uma credencial podem ser usadas em outros fluxos de autenticação, como fluxos em nome de (OBO). Os exemplos são válidos em ambos os casos, quando o locatário do recurso está no mesmo locatário que o registro do aplicativo e a identidade gerenciada e quando está em um locatário diferente.

Azure.Identity

O exemplo a seguir demonstra como se conectar a um contêiner de armazenamento do Azure usando Azure.Identity, mas pode ser adaptado para acessar qualquer recurso protegido pelo Microsoft Entra. Os exemplos são válidos em ambos os casos, quando o locatário do recurso está no mesmo locatário que o registro do aplicativo e a identidade gerenciada e quando está em um locatário diferente.

using Azure.Identity;
using Azure.Storage.Blobs;

internal class Program
{
    // This example demonstrates how to access an Azure blob storage account by utilizing the manage identity credential.
  static void Main(string[] args)
  {
        string storageAccountName = "YOUR_STORAGE_ACCOUNT_NAME";
        string containerName = "CONTAINER_NAME";
        
        // The application must be granted access on the target resource
      string appClientId = "YOUR_APP_CLIENT_ID";

        // The tenant where the target resource is created, in this example, the storage account tenant
        // If the resource tenant different from the app tenant, your app needs to be 
      string resourceTenantId = "YOUR_RESOURCE_TENANT_ID";

        // The managed identity which you configured as a Federated Identity Credential (FIC)
      string miClientId = "YOUR_MANAGED_IDENTITY_CLIENT_ID"; 

        // Audience value must be one of the below values depending on the target cloud.
        // Public cloud: api://AzureADTokenExchange
        //  Fairfax: api://AzureADTokenExchangeUSGov
        //  Mooncake: api://AzureADTokenExchangeChina
        //  USNat: api://AzureADTokenExchangeUSNat
        //  USSec: api://AzureADTokenExchangeUSSec
      string audience = "api://AzureADTokenExchange";

        // 1. Create an assertion with the managed identity access token, so that it can be exchanged an app token
        var miCredential = new ManagedIdentityCredential(managedIdentityClientId);
        ClientAssertionCredential assertion = new(
            tenantId,
            appClientId,
            async (token) =>
            {
                // fetch Managed Identity token for the specified audience
                var tokenRequestContext = new Azure.Core.TokenRequestContext(new[] { $"{audience}/.default" });
                var accessToken = await miCredential.GetTokenAsync(tokenRequestContext).ConfigureAwait(false);
                return accessToken.Token;
            });

        // 2. The assertion can be used to obtain an App token (taken care of by the SDK)
        var containerClient  = new BlobContainerClient(new Uri($"https://{storageAccountName}.blob.core.windows.net/{containerName}"), assertion);

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

Microsoft.Identity.Web

No Microsoft.Identity.Web, um aplicativo Web ou API Web pode substituir o certificado do cliente por uma declaração de cliente assinada para autenticação. Em seu aplicativo, você pode atualizar a seção ClientCredentials em seu appsettings.json para a seguinte configuração:

{
  "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"
      }
   ]
  }
}

MSAL (.NET)

Em MSAL, você pode utilizar a classe ManagedClientApplication para obter um token de identidade gerenciada. Esse token pode ser usado como uma declaração de cliente ao construir um aplicativo cliente confidencial.

Aviso

Para aplicativos .NET, recomendamos usar bibliotecas de nível superior baseadas na MSAL, como Microsoft.Identity.Web ou Azure.Identity.

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

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";

      // 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 client = 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}");
        }
  }
}

Consulte também