Usa os segredos do cliente com a Microsoft. Identity.Web

Um segredo de cliente é uma cadeia de caracteres que a sua aplicação utiliza para provar a sua identidade ao solicitar tokens à plataforma de identidade da Microsoft. Microsoft. O Identity.Web suporta segredos de cliente como um dos vários tipos de credenciais para aplicações cliente confidenciais.

Escolha um tipo de credencial

Aplicações cliente confidenciais precisam de uma credencial para se autenticarem com a plataforma de identidades da Microsoft. Microsoft. O Identity.Web suporta os seguintes tipos de credenciais através da secção de configuração ClientCredentials:

Os segredos do cliente são simples cadeias de caracteres registadas na sua aplicação no Microsoft Entra ID. Embora sejam o tipo de credencial mais fácil de configurar, também apresentam limitações significativas de segurança:

• Podem ser expostos acidentalmente em código-fonte, registos ou ficheiros de configuração.
• Têm uma data de validade e devem ser substituídas manualmente.
• Não fornecem qualquer prova criptográfica da identidade do interlocutor para além da posse do segredo.

Configurar um segredo de cliente em appsettings.json

Para configurar um cliente secreto, adicione um ClientCredentials array à AzureAd secção do seu appsettings.json ficheiro:

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

O ClientCredentials array suporta múltiplas entradas. Microsoft. O Identity.Web testa cada credencial por ordem até que uma tenha sucesso, o que é útil para cenários de rotação secreta.

Armazenar segredos para o desenvolvimento

Esta secção descreve como manter valores secretos fora do seu código-fonte durante o desenvolvimento local.

Segredos de utilizador .NET

A abordagem recomendada para armazenar segredos durante o desenvolvimento local é a ferramenta Secret Manager. User Secrets armazena dados sensíveis fora da árvore do seu projeto, o que impede commits acidentais no controle de versão.

1. Inicialize os Segredos do Utilizador para o seu projeto:

   dotnet user-secrets init
   

2. Defina o valor do segredo do cliente:

   dotnet user-secrets set "AzureAd:ClientCredentials:0:ClientSecret" "your-secret-value"
   

3. Verifique se o segredo foi guardado:

   dotnet user-secrets list
   

Segredos de Utilizador são automaticamente carregados no ambiente Development quando utiliza WebApplication.CreateBuilder() ou Host.CreateDefaultBuilder().

O seu appsettings.json deve conter a estrutura sem o valor secreto real:

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

Variáveis de ambiente

Também pode usar variáveis de ambiente para fornecer o segredo do cliente. A configuração do .NET mapeia automaticamente as variáveis de ambiente que usam o separador __ (dois sublinhados) para a hierarquia de configuração. Defina a variável para a sua shell:

$env:AzureAd__ClientCredentials__0__ClientSecret = "your-secret-value"

export AzureAd__ClientCredentials__0__ClientSecret="your-secret-value"

As variáveis de ambiente têm precedência sobre valores em appsettings.json, pelo que o valor secreto no seu ficheiro de configuração pode estar vazio ou omitido.

Guardar segredos para ambientes superiores

Para staging, QA ou qualquer ambiente partilhado, use o Azure Key Vault como fonte de configuração. Esta abordagem mantém segredos fora dos ficheiros de configuração e das variáveis do ambiente, ao mesmo tempo que fornece auditoria, políticas de acesso e capacidades de rotação automática.

Adicionar Azure Key Vault como fonte de configuração

1. Instale o pacote NuGet necessário:

   dotnet add package Azure.Extensions.AspNetCore.Configuration.Secrets
   

2. Armazene o segredo do cliente no Azure Key Vault com um nome que corresponda ao caminho de configuração. Use -- (duplo traço) como separador:

   az keyvault secret set \
     --vault-name "your-keyvault-name" \
     --name "AzureAd--ClientCredentials--0--ClientSecret" \
     --value "your-secret-value"
   

3. Adicione-Key Vault como fonte de configuração em Program.cs. O seguinte código regista o Key Vault para que os seus segredos estejam disponíveis através da API de configuração padrão:

   var builder = WebApplication.CreateBuilder(args);
   
   builder.Configuration.AddAzureKeyVault(
       new Uri("https://your-keyvault-name.vault.azure.net/"),
       new DefaultAzureCredential());
   

O nome do segredo do Key Vault AzureAd--ClientCredentials--0--ClientSecret é mapeado automaticamente para o caminho de configuração AzureAd:ClientCredentials:0:ClientSecret.

Criar um segredo de cliente no portal do Azure

Siga estes passos para registar um segredo de cliente para a sua aplicação no Microsoft Entra ID:

1. Inicia sessão no centro de administração Microsoft Entra.
2. Navegue até Identidade>Aplicações>Registros de Aplicações.
3. Selecione seu aplicativo na lista.
4. No menu à esquerda, selecione Certificados & Segredos.
5. Selecione o separador Segredos do Cliente .
6. Selecione Novo segredo do cliente.
7. No painel Adicionar um segredo de cliente :
   • Introduza uma Descrição do segredo (por exemplo, "Segredo de desenvolvimento").
   • Selecione uma duração de expiração . As opções disponíveis incluem 180 dias, 365 dias, 730 dias ou uma data personalizada.
   • Selecione Adicionar.
8. Copie imediatamente o valor secreto. O valor só é mostrado uma vez e não pode ser recuperado depois de sair da página.

Gerir a expiração e rotação secretas

Os segredos do cliente têm uma vida máxima e expiram na data especificada durante a criação. Planeie uma rotação secreta para evitar falhas de candidatura.

Expiração do monitor

• Verifique a coluna Expiração na página Certificados e Segredos do registo da sua aplicação.
• Configure Microsoft Entra recomendações para receber alertas antes de expirarem as credenciais.

Estratégia de rotação

Use o ClientCredentials array para suportar rotação sem tempo de inatividade:

1. Crie um novo segredo de cliente no portal do Azure.

2. Adicione o novo segredo como uma entrada adicional no ClientCredentials array. Coloca primeiro o novo segredo para que seja experimentado antes do antigo:

   {
     "AzureAd": {
       "ClientCredentials": [
         {
           "SourceType": "ClientSecret",
           "ClientSecret": "[NEW_SECRET_REFERENCE]"
         },
         {
           "SourceType": "ClientSecret",
           "ClientSecret": "[OLD_SECRET_REFERENCE]"
         }
       ]
     }
   }
   

3. Implemente a configuração atualizada. Microsoft.Identity.Web tenta a primeira credencial e recorre à segunda se a primeira falhar.

4. Depois de confirmar que o novo segredo funciona, remova o segredo antigo tanto da configuração como do portal Azure.

Migrar para credenciais de produção

Antes de implementar para produção, migre dos segredos do cliente para um tipo de credencial mais seguro:

Autenticação baseada em certificado

Os certificados fornecem prova criptográfica de identidade e são o tipo de credencial recomendado para produção. A seguinte configuração recupera um certificado do Key Vault:

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

Para passos detalhados, consulte Use certificados com Microsoft. Identidade.Web.

Identidade gerida (sem certificado)

Para aplicações alojadas no Azure, as identidades geridas eliminam completamente a necessidade de gerir credenciais. A seguinte configuração utiliza uma identidade gerida atribuída pelo utilizador:

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

Para passos detalhados, consulte Autenticação sem certificado com Microsoft. Identidade.Web.

Lista de verificação da migração

• [ ] Gerar ou provisionar a nova credencial (certificado ou identidade gerida).
• [ ] Atualize a configuração da sua aplicação para usar o novo tipo de credencial.
• [ ] Testar as novas credenciais num ambiente de teste.
• [ ] Implementar em produção.
• [ ] Remover o antigo segredo do cliente do portal Azure.
• [ ] Verifica se a aplicação funciona corretamente sem o segredo antigo.

Evite erros comuns de segurança

Reveja os seguintes anti-padrões e as suas alternativas recomendadas ao trabalhar com segredos de clientes:

Solucionar erros comuns

Esta secção aborda erros frequentes que pode encontrar ao configurar os segredos do cliente.

Segredo inválido do cliente

Erro:AADSTS7000215: Invalid client secret provided.

Causas possíveis:

• O valor secreto foi copiado incorretamente. Os valores secretos podem conter caracteres especiais que são truncados durante operações de copiar/colar.
• O segredo foi criado para o registo de uma aplicação diferente daquele configurado em ClientId.
• O caminho de configuração está incorreto e o valor secreto não está a ser lido pela aplicação.

Resolution:

1. Crie um novo segredo do cliente no portal do Azure e copie cuidadosamente o valor completo.

2. Verifica se ClientId e TenantId na tua configuração correspondem ao registo da aplicação onde a chave secreta foi criada.

3. Adicione um ponto de interrupção ou instrução log para verificar se a configuração está corretamente carregada:

   // For debugging only — remove before committing
   var config = builder.Configuration.GetSection("AzureAd:ClientCredentials:0:ClientSecret").Value;
   Console.WriteLine($"Secret loaded: {!string.IsNullOrEmpty(config)}");
   

Segredo de cliente expirado

Erro:AADSTS7000222: The provided client secret keys for app '{app-id}' are expired.

Resolution:

1. Navegue até ao registo da aplicação no centro de administração Microsoft Entra.
2. Verifique a data de validade em Certificados &>Segredos de Clientes.
3. Crie um novo segredo e atualize a configuração da sua aplicação.
4. Apaga o segredo expirado do portal.

Segredo não encontrado na configuração

Sintoma: A aplicação lança um NullReferenceException ou falha em autenticar porque o valor secreto é null.

Causas possíveis:

• Os User Secrets não são inicializados para o projeto.
• O nome da variável de ambiente não corresponde ao caminho de configuração esperado.
• O Key Vault não está configurado como fonte de configuração.
• A aplicação está a correr num ambiente que não é de Desenvolvimento, onde os Segredos de Utilizador não são carregados.

Resolution:

1. Verifique se os Segredos de Utilizador estão inicializados verificando a existência de um UserSecretsId no seu ficheiro .csproj.
2. Verifique se o segredo está definido executando dotnet user-secrets list.
3. Verifique se o caminho de configuração corresponde exatamente: AzureAd:ClientCredentials:0:ClientSecret.
4. Se estiver a correr fora do ambiente de Desenvolvimento, certifique-se de que a fonte de configuração apropriada (variável de ambiente ou Key Vault) está disponível.

Conteúdo relacionado

• Certificados com Microsoft. Identidade.Web
• Autenticação sem certificado
• Visão geral da cache de tokens
• Armazenamento seguro de segredos de aplicações em desenvolvimento em ASP.NET Core
• Provedor de configuração do Azure Key Vault no ASP.NET Core