Configure a autenticação sem certificado com Microsoft. Identity.Web

Este artigo mostra como configurar a autenticação sem certificado para que seu aplicativo se autentique com Microsoft Entra ID sem gerenciar certificados ou segredos do cliente. Seu aplicativo usa uma Credencial de Identidade Federada (FIC) respaldada por uma Identidade Gerenciada do Azure para obter tokens, o que elimina a rotação de credenciais, reduz a propagação de segredos e simplifica implantações do Azure.

Microsoft. O Identity.Web dá suporte à autenticação sem certificado por meio do tipo de origem de credencial SignedAssertionFromManagedIdentity, disponível na versão 2.12.0 e posterior.

Entender a autenticação sem certificado

Esta seção explica como funciona a autenticação sem certificado e quando usá-la.

Tradicionalmente, os aplicativos cliente confidenciais comprovam sua identidade para Microsoft Entra ID apresentando um segredo do cliente ou um certificado. Ambas as abordagens exigem que você gerencie o ciclo de vida da credencial, girando segredos antes que eles expirem, renovando certificados e armazenando-os com segurança.

As Credenciais de Identidade Federadas (FIC) alteram esse modelo. Com o FIC, você configura uma relação de confiança entre o registro do aplicativo e uma Identidade Gerenciada. Quando seu aplicativo precisa se autenticar:

1. Microsoft.Identity.Web solicita um token do ponto de extremidade de Identidade Gerenciada no host da Azure.
2. A biblioteca usa o token de Identidade Gerenciada como uma declaração assinada para autenticar com Microsoft Entra ID.
3. Microsoft Entra ID valida a declaração assinada em relação à configuração de credencial federada no registro do aplicativo.
4. Microsoft Entra ID emite um token de acesso para o recurso solicitado.

O resultado é uma implantação totalmente livre de credenciais em que não existem segredos ou certificados em suas variáveis de configuração, código ou ambiente.

Escolha a abordagem de autenticação correta

A tabela a seguir ajuda você a decidir quando a autenticação sem certificado é a escolha certa.

Pré-requisitos

Verifique se você tem os seguintes recursos e ferramentas antes de começar:

• Uma assinatura Azure. Se você não tiver uma, crie uma conta gratuita.
• Um registro de Aplicativo no Microsoft Entra ID com as permissões de API necessárias para seu cenário.
• Uma Identidade Gerenciada em Azure—atribuída pelo sistema no seu recurso de computação ou uma Identidade Gerenciada atribuída pelo usuário.
• Microsoft. Identity.Web versão 2.12.0 ou posterior instalada em seu projeto.
• Um recurso de computação Azure que dá suporte à Identidade Gerenciada, como Serviço de Aplicativo do Azure, AKS (Serviço de Kubernetes do Azure), Aplicativos de Contêiner do Azure ou Máquinas Virtuais do Azure.

Etapa 1: Criar ou identificar uma Identidade Gerenciada

Você pode usar uma Identidade Gerenciada atribuída pelo sistema ou atribuída pelo usuário. Se você ainda não criou um, siga as instruções para seu cenário.

Opção A: Usar uma Identidade Gerenciada atribuída pelo sistema

As Identidades Gerenciadas atribuídas pelo sistema estão vinculadas ao ciclo de vida de um recurso de Azure. Quando você habilita uma identidade atribuída pelo sistema em um recurso como um Serviço de Aplicativo, Azure cria uma identidade automaticamente.

1. No Azure portal, navegue até o recurso de computação (por exemplo, seu Serviço de Aplicativo).
2. Selecione Identidade no menu de navegação esquerdo.
3. Na guia Sistema atribuído, defina o Status para Ativado.
4. Selecione Salvar e confirme a ação.
5. Depois que a identidade for criada, copie a ID do Objeto (principal). Você precisa desse valor ao configurar a credencial federada.

Opção B: criar uma Identidade Gerenciada atribuída pelo usuário

Identidades Gerenciadas atribuídas pelo usuário são recursos Azure autônomos que você pode atribuir a um ou mais recursos de computação.

1. Azure portal, pesquise por Managed Identities e selecione-o.
2. Selecione Criar.
3. Escolha sua assinatura, grupo de recursos, região e insira um nome para a identidade.
4. Selecione Examinar + criar, depois Criar.
5. Após a conclusão da implantação, abra o novo recurso de Identidade Gerenciada.
6. Copie a ID do cliente da página Visão geral . Você precisa desse valor para a configuração do aplicativo.

Etapa 2: Configurar uma credencial de Identidade Federada no portal do Azure

Uma Credencial de Identidade Federada estabelece uma relação de confiança entre o registro do aplicativo e a Identidade Gerenciada. Siga estas etapas para criar uma:

1. No portal Azure, vá para Microsoft Entra ID>Registros de aplicativos.

2. Selecione o registro de aplicativo que seu aplicativo usa.

3. No menu de navegação à esquerda, selecione Certificados &segredos.

4. Selecione a guia Credenciais federadas.

5. Selecione Adicionar credencial.

6. No cenário de credencial federada, selecione Chaves gerenciadas pelo cliente ou Outro emissor (as opções disponíveis dependem da versão do portal).

7. Configure os seguintes campos:

   Campo	Valor
   Emissor	https://login.microsoftonline.com/{tenant-id}/v2.0 — Substitua {tenant-id} pelo ID do inquilino Microsoft Entra.
   Identificador de Assunto	A ID do objeto (principal) da Identidade Gerenciada. Para sistemas atribuídos, encontre isso na página de Identidade do recurso. Para a identidade atribuída ao usuário, localize-a na página de Visão geral da Identidade Gerenciada sob Principal ID.
   Nome	Um nome descritivo, por exemplo fic-managed-identity-prod.
   Público	api://AzureADTokenExchange (o valor padrão).

8. Selecione Adicionar.

Configurar uma credencial de Identidade Federada com CLI do Azure

Como alternativa, crie a credencial federada com o CLI do Azure. O comando a seguir cria uma credencial no registro do aplicativo:

az ad app federated-credential create \
    --id <app-object-id> \
    --parameters '{
        "name": "fic-managed-identity-prod",
        "issuer": "https://login.microsoftonline.com/<tenant-id>/v2.0",
        "subject": "<managed-identity-principal-id>",
        "audiences": ["api://AzureADTokenExchange"],
        "description": "FIC for production managed identity"
    }'

URLs do emissor por serviço do Azure

A URL do emissor na credencial federada depende do serviço Azure que hospeda seu aplicativo:

Formato do identificador de assunto

O formato do identificador de assunto depende do tipo de Identidade Gerenciada:

Identidade Gerenciada atribuída pelo sistema – use a ID do objeto (identificador principal) da página Identidade do recurso. Este é um valor GUID, por exemplo a1b2c3d4-e5f6-7890-abcd-ef1234567890.

Identidade Gerenciada atribuída pelo usuário — use o ID Principal (também chamado de ID do Objeto) na página Visão Geral do recurso de Identidade Gerenciada. Esse também é um valor GUID.

Etapa 3: Configurar seu aplicativo

Atualizar appsettings.json

Adicione a ClientCredentials seção à sua AzureAd configuração. Defina SourceType como SignedAssertionFromManagedIdentity:

Para identidade gerenciada atribuída pelo usuário

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "YOUR_TENANT_ID",
    "ClientId": "YOUR_CLIENT_ID",
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity",
        "ManagedIdentityClientId": "USER_ASSIGNED_MSI_CLIENT_ID"
      }
    ]
  }
}

Substitua os seguintes espaços reservados:

Para a Identidade Gerenciada atribuída pelo sistema

Quando você usa uma Identidade Gerenciada atribuída pelo sistema, omita a ManagedIdentityClientId propriedade. Microsoft. O Identity.Web usa automaticamente a identidade atribuída pelo sistema do host:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "YOUR_TENANT_ID",
    "ClientId": "YOUR_CLIENT_ID",
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity"
      }
    ]
  }
}

Registrar serviços no Program.cs

Nenhuma alteração de código especial é necessária na configuração de inicialização. Os métodos padrão de registro do Microsoft.Identity.Web leem a seção ClientCredentials automaticamente.

O exemplo a seguir registra a autenticação de um aplicativo Web que autentica usuários e chama APIs subsequentes.

// For a web app that signs in users and calls downstream APIs
builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApp(builder.Configuration.GetSection("AzureAd"))
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddInMemoryTokenCaches();

O exemplo a seguir registra a autenticação de uma API Web que chama APIs downstream:

// For a web API that calls downstream APIs
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(builder.Configuration.GetSection("AzureAd"))
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddInMemoryTokenCaches();

O exemplo a seguir registra a autenticação de um aplicativo daemon sem interação do usuário:

// For a daemon application (no user interaction)
builder.Services.AddAuthentication()
    .AddMicrosoftIdentityWebApi(builder.Configuration.GetSection("AzureAd"));

builder.Services.AddTokenAcquisition()
    .AddInMemoryTokenCaches();

Microsoft. Identity.Web detecta o tipo de origem SignedAssertionFromManagedIdentity e manipula a troca de tokens de forma transparente.

Comparar identidade gerenciada atribuída pelo sistema e atribuída pelo usuário

Escolha o tipo de Identidade Gerenciada que melhor se adapte à sua arquitetura. As seções a seguir descrevem as compensações.

Identidade Gerenciada atribuída pelo sistema

Uma identidade atribuída pelo sistema é criada e excluída automaticamente com o recurso de Azure ao qual pertence.

Vantagens:

• Nenhum recurso separado precisa ser gerenciado—o ciclo de vida da identidade corresponde ao recurso de computação.
• Configuração mais simples para implantações de recurso único.
• Não é necessário ManagedIdentityClientId na configuração.

Considerações:

• Você não pode compartilhar a identidade em vários recursos.
• Se você excluir e recriar o recurso, a identidade será alterada. Você deve atualizar a Credencial de Identidade Federada.

Melhor para: Implantações de instância única em que um recurso de computação é mapeado para um registro de aplicativo.

Identidade gerenciada atribuída ao usuário

Uma identidade atribuída pelo usuário é um recurso Azure autônomo com seu próprio ciclo de vida.

Vantagens:

• Compartilhe uma única identidade em vários recursos de computação (por exemplo, várias instâncias do Serviço de Aplicativo em regiões diferentes).
• A identidade persiste independentemente do ciclo de vida do recurso de computação.
• Pré-criar e pré-configurar antes de implantar o recurso de computação.

Considerações:

• Um recurso de Azure adicional a ser gerenciado.
• Você deve especificar a configuração ManagedIdentityClientId.

Melhor para: Implantações de várias instâncias ou várias regiões, padrões de implantação azul-verde e cenários em que os recursos de computação são recriados com frequência.

Implantar em serviços de computação do Azure

Depois de configurar seu aplicativo, implante-o em um serviço de computação Azure que dê suporte à Identidade Gerenciada.

Serviço de Aplicativo do Azure

1. Habilite a Identidade Gerenciada em seu Serviço de Aplicativo (consulte a Etapa 1).

2. Implante seu aplicativo no Serviço de Aplicativo usando seu método preferencial (Visual Studio, CLI do Azure GitHub Actions).

3. Verifique se a AzureAd seção na configuração implantada corresponde às configurações na Etapa 3.

4. Se você usar uma Identidade Gerenciada atribuída pelo usuário, atribua-a ao Serviço de Aplicativo:

   az webapp identity assign \
     --resource-group <resource-group> \
     --name <app-service-name> \
     --identities <managed-identity-resource-id>
   

5. Reinicie o Serviço de Aplicativo para pegar a atribuição de identidade.

Serviço de Kubernetes do Azure (AKS)

Para o AKS, use a identidade da carga de trabalho para associar uma conta de serviço do Kubernetes à Identidade Gerenciada. Conclua as seguintes etapas:

1. Habilite o recurso de identidade de carga de trabalho no cluster do AKS:

   az aks update \
     --resource-group <resource-group> \
     --name <aks-cluster-name> \
     --enable-oidc-issuer \
     --enable-workload-identity
   

2. Crie uma conta de serviço do Kubernetes anotada com a ID do cliente de Identidade Gerenciada:

   apiVersion: v1
   kind: ServiceAccount
   metadata:
     name: my-app-sa
     namespace: default
     annotations:
       azure.workload.identity/client-id: "<USER_ASSIGNED_MSI_CLIENT_ID>"
   

3. Crie uma credencial federada vinculando o emissor do OIDC do AKS à Managed Identity.

4. Configure o pod para usar a conta de serviço:

   apiVersion: v1
   kind: Pod
   metadata:
     name: my-app
     namespace: default
     labels:
       azure.workload.identity/use: "true"
   spec:
     serviceAccountName: my-app-sa
     containers:
       - name: my-app
         image: <your-container-image>
   

5. Desdobre o pod. O webhook de identidade de carga de trabalho injeta as variáveis de ambiente necessárias para o ponto de extremidade do token de Identidade Gerenciada.

Aplicativos de Contêiner do Azure

1. Crie ou atualize seu Aplicativo de Contêiner com uma Identidade Gerenciada:

   az containerapp identity assign \
     --resource-group <resource-group> \
     --name <container-app-name> \
     --user-assigned <managed-identity-resource-id>
   

2. Implante sua imagem de contêiner com a configuração apropriada AzureAd .

3. O endpoint do token de Identidade Gerenciada está disponível automaticamente dentro do contêiner.

Migrar de certificados para autenticação sem certificado

Se o aplicativo atualmente usa a autenticação baseada em certificado, você pode migrar para a autenticação sem certificado com alterações mínimas de configuração.

Concluir as etapas de migração

1. Criar uma Identidade Gerenciada para seu recurso de computação Azure (consulte Step 1).

2. Adicione uma Credencial de Identidade Federada ao registro do aplicativo (consulte a Etapa 2).

3. Atualize sua configuração para adicionar a SignedAssertionFromManagedIdentity credencial. Você pode manter a credencial de certificado existente como um fallback durante a migração:

   {
     "AzureAd": {
       "Instance": "https://login.microsoftonline.com/",
       "TenantId": "YOUR_TENANT_ID",
       "ClientId": "YOUR_CLIENT_ID",
       "ClientCredentials": [
         {
           "SourceType": "SignedAssertionFromManagedIdentity",
           "ManagedIdentityClientId": "USER_ASSIGNED_MSI_CLIENT_ID"
         },
         {
           "SourceType": "KeyVault",
           "KeyVaultUrl": "https://your-keyvault.vault.azure.net",
           "KeyVaultCertificateName": "your-cert-name"
         }
       ]
     }
   }
   

   Microsoft.Identity.Web tenta fontes de credencial em ordem. Ao executar no Azure, a primeira credencial (SignedAssertionFromManagedIdentity) é bem-sucedida. Se falhar (por exemplo, durante o desenvolvimento local), a biblioteca retornará ao certificado.

4. Implante e valide em um ambiente de preparo antes de aplicar à produção.

5. Remova a credencial de certificado da configuração depois de confirmar que a autenticação sem certificado funciona em produção.

6. Exclua o certificado de Azure Key Vault e o registro do aplicativo quando ele não for mais necessário.

Comparar antes e depois da configuração

Os exemplos a seguir mostram a alteração de configuração de autenticação baseada em certificado para autenticação sem certificado.

Antes (baseado em certificado):

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://your-keyvault.vault.azure.net",
        "KeyVaultCertificateName": "your-cert-name"
      }
    ]
  }
}

Depois (sem certificado):

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity",
        "ManagedIdentityClientId": "USER_ASSIGNED_MSI_CLIENT_ID"
      }
    ]
  }
}

Solucionar erros comuns

Use as diretrizes a seguir para diagnosticar e resolver problemas com a autenticação sem certificado.

AADSTS70021: Nenhum registro de identidade federado correspondente encontrado

Causa: O identificador de assunto na Credencial de Identidade Federada não corresponde à ID do objeto (principal) da Identidade Gerenciada.

Resolução:

1. No portal Azure, navegue até o recurso de Identidade Gerenciada e copie a ID Principal (também chamada de ID de Objeto) da página Overview.
2. Navegue até o registro do aplicativo: >Certificados e segredos>credenciais federadas.
3. Verifique se o campo Identificador de Sujeito corresponde exatamente à ID Principal.
4. Se os valores não corresponderem, exclua a credencial e recrie-a com o identificador de assunto correto.

AADSTS700024: A asserção do cliente não está dentro do intervalo de tempo válido

Causa: O token de Identidade Gerenciada usado como a asserção assinada expirou ou o relógio do sistema está distorcido.

Resolução:

• Verifique se o relógio do sistema em seu recurso de Azure é preciso.
• Reinicie o aplicativo para forçar uma nova solicitação de token de Identidade Gerenciada.
• Se você executar em um contêiner, verifique se o relógio do contêiner está sincronizado com o host.

ManagedIdentityException: ponto de extremidade de Identidade Gerenciada não disponível

Cause: O aplicativo não pode acessar o IMDS (Serviço de Metadados de Instância) Azure ou o ponto de extremidade do token de Identidade Gerenciada.

Resolução:

• Confirme se o aplicativo está em execução em um recurso de computação Azure que dá suporte à Identidade Gerenciada.
• Verifique se a Identidade Gerenciada está habilitada e atribuída ao recurso de computação.
• Para o AKS, verifique se o webhook de identidade de carga de trabalho está em execução e se o pod tem a anotação de conta de serviço correta.
• Para o desenvolvimento local, esse erro é esperado. Use uma fonte de credencial de fallback (consulte as etapas de migração).

AADSTS700016: aplicativo não encontrado no diretório

Causa: A ClientId configuração não corresponde a um registro de aplicativo válido no locatário especificado.

Resolução:

• Verifique se a ClientId corresponde ao ID do aplicativo (cliente) do registro do seu aplicativo.
• Verifique se o TenantId tenant corresponde ao local onde o aplicativo está registrado.

Habilitar o log de depuração

Causa: A incompatibilidade de configuração ou ordem de origem da credencial pode fazer com que a biblioteca ignore a credencial FIC.

Resolução:

1. Habilitar o registro de log no Microsoft.Identity.Web para ver as etapas detalhadas da aquisição de tokens. O código a seguir configura o logging no nível de debug para as bibliotecas de identidade.

   builder.Services.AddLogging(logging =>
   {
       logging.AddConsole();
       logging.SetMinimumLevel(LogLevel.Debug);
       logging.AddFilter("Microsoft.Identity", LogLevel.Debug);
   });
   

2. Examine os logs para obter mensagens sobre qual fonte de credencial a biblioteca tentou e quaisquer erros retornados.

Identidade Gerenciada atribuída pelo usuário não reconhecida

Causa: Quando várias Identidades Gerenciadas atribuídas pelo usuário são atribuídas a um recurso de computação, a biblioteca pode usar a errada se ManagedIdentityClientId não for especificada.

Resolução:

• Sempre especifique a ManagedIdentityClientId propriedade quando você usa uma Identidade Gerenciada atribuída pelo usuário.
• Verifique se a ID do cliente corresponde à identidade para a qual você configurou a Credencial de Identidade Federada.

Examinar os benefícios de segurança

A autenticação sem certificado com FIC fornece vantagens significativas de segurança em relação às abordagens tradicionais baseadas em credencial:

Nenhum segredo a ser vazado

Como não existem arquivos de certificado, senhas PFX ou segredos do cliente em seus artefatos de configuração ou implantação, não há nada para um invasor extrair. Mesmo que um invasor obtenha acesso de leitura aos seus arquivos de configuração, ele não poderá personificar seu aplicativo de fora do Azure.

Nenhuma rotação de credencial

Os tokens de Identidade Gerenciada são de curta duração e atualizados automaticamente pela plataforma Azure. Você não precisa implementar agendamentos de rotação, monitorar datas de validade ou coordenar atualizações de credenciais entre implantações.

Superfície de ataque reduzida

O ponto de extremidade do token de Identidade Gerenciada só pode ser acessado do recurso de Azure específico ao qual a identidade é atribuída. Um invasor não pode usar a credencial de um host, rede ou ambiente de nuvem diferente.

Simplificação de conformidade

Sem credenciais de longa duração, você elimina várias categorias de preocupações de conformidade:

• Nenhum segredo armazenado no controle do código-fonte, variáveis de ambiente ou arquivos de configuração.
• Nenhum material de chave para auditoria, rotação ou revogação.
• Nenhuma infraestrutura de certificado (Autoridade Certificadora, processos de renovação) precisa ser mantida.

Defesa em profundidade

Combine a autenticação sem certificado com outros recursos de segurança Azure para proteção em camadas:

• Azure RBAC: controle quais identidades podem acessar quais recursos.
• Acesso Condicional: aplicar políticas com base no risco de identidade, local e estado do dispositivo.
• Pontos de extremidade privados: restringir o acesso à rede a recursos do Azure.
• Microsoft Defender para Nuvem: monitore padrões de autenticação suspeitos.

Conteúdo relacionado

• Visão geral das credenciais
• Certificados
• Segredos do cliente
• Documentação do Azure Identidades Gerenciadas
• Documentação de Credenciais de Identidade Federadas
• Repositório GitHub do Microsoft.Identity.Web