Use segredos do cliente com Microsoft. Identity.Web

Um segredo do cliente é um valor de cadeia de caracteres que seu aplicativo usa para provar sua identidade ao solicitar tokens do plataforma de identidade da Microsoft. Microsoft. O Identity.Web dá suporte a segredos do cliente como um dos vários tipos de credencial para aplicativos cliente confidenciais.

Escolher um tipo de credencial

Aplicativos cliente confidenciais precisam de uma credencial para autenticar com o plataforma de identidade da Microsoft. Microsoft. O Identity.Web dá suporte aos seguintes tipos de credencial por meio da seção de configuração ClientCredentials:

Os segredos do cliente são cadeias de caracteres simples registradas com seu aplicativo no Microsoft Entra ID. Embora sejam o tipo de credencial mais fácil de configurar, eles também têm limitações de segurança significativas:

• Eles podem ser expostos acidentalmente no código-fonte, logs ou arquivos de configuração.
• Eles têm uma data de validade e devem ser girados manualmente.
• Eles não fornecem nenhuma prova criptográfica da identidade do chamador além da posse do segredo.

Configurar um segredo do cliente no appsettings.json

Para configurar um segredo do cliente, adicione uma ClientCredentials matriz à AzureAd seção do arquivo appsettings.json :

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

A ClientCredentials matriz dá suporte a várias entradas. Microsoft.Identity.Web tenta cada credencial em ordem até que uma seja bem-sucedida, o que é útil para cenários de rotação de segredos.

Armazenamento de segredos para desenvolvimento

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

.NET segredos do usuário

A abordagem recomendada para armazenar segredos durante o desenvolvimento local é a ferramenta do Gerenciador de Segredos. Os Segredos do Usuário armazenam dados confidenciais fora da árvore do projeto, o que impede confirmações acidentais no controle do código-fonte.

1. Inicializar secretos de usuário para 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 armazenado:

   dotnet user-secrets list
   

Os Segredos do Usuário são carregados automaticamente no Development ambiente quando você usa WebApplication.CreateBuilder() ou Host.CreateDefaultBuilder().

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

Você também pode usar variáveis de ambiente para fornecer o segredo do cliente. As configurações do .NET mapeiam automaticamente variáveis de ambiente que usam o separador __ (dois sublinhados) para a hierarquia de configuração. Defina a variável para seu 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 os valores em appsettings.json, de modo que o valor secreto no arquivo de configuração pode ser vazio ou omitido.

Armazenar segredos para ambientes superiores

Para homologação, QA ou qualquer ambiente compartilhado, use Azure Key Vault como fonte de configuração. Essa abordagem mantém os segredos fora dos arquivos de configuração e das variáveis de ambiente, fornecendo auditoria, políticas de acesso e recursos de rotação automática.

Adicionar Azure Key Vault como uma 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 utilizando um nome que corresponda ao caminho de configuração. Use -- (traço duplo) 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 código a seguir registra Key Vault para que seus segredos estejam disponíveis por meio 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 do cliente no portal do Azure

Siga estas etapas para registrar um segredo do cliente para seu aplicativo no Microsoft Entra ID:

1. Entre no centro de administração do Microsoft Entra.
2. Navegue até Identity>Applications>Registros de aplicativo.
3. Selecione seu aplicativo na lista.
4. No menu à esquerda, selecione Certificados &segredos.
5. Selecione a guia Segredos do cliente .
6. Selecione Novo segredo do cliente.
7. No painel Adicionar um segredo do cliente :
   • Insira uma descrição para o 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 o valor do segredo imediatamente. O valor é mostrado apenas uma vez e não pode ser recuperado depois que você navega para longe da página.

Gerenciar expiração e rotação de segredos

Os segredos do cliente têm um tempo de vida máximo e expiram na data especificada durante a criação. Planeje a rotação de segredo para evitar interrupções de aplicativo.

Monitorar a expiração

• Verifique a coluna Expira na página Certificados e segredos do registro do aplicativo.
• Configure Microsoft Entra recomendações para receber alertas antes que as credenciais expirem.

Estratégia de rotação

Use a ClientCredentials matriz para dar suporte à rotação sem tempo de inatividade.

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

2. Adicione o novo segredo como uma entrada adicional na ClientCredentials matriz. Coloque o novo segredo primeiro para que ele seja tentado antes do antigo:

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

3. Implante a configuração atualizada. Microsoft. Identity.Web tenta a primeira credencial e volta para a segunda se a primeira falhar.

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

Migrar para credenciais de produção

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

Autenticação baseada em certificado

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

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

Para obter etapas detalhadas, consulte Usar certificados com Microsoft. Identity.Web.

Identidade gerenciada (sem certificado)

Para aplicativos hospedados em Azure, as identidades gerenciadas eliminam totalmente a necessidade de gerenciar credenciais. A configuração a seguir usa uma identidade gerenciada atribuída pelo usuário:

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

Para obter etapas detalhadas, consulte Autenticação sem certificação com Microsoft. Identity.Web.

Lista de verificação de migração

• [ ] Gerar ou provisionar a nova credencial (certificado ou identidade gerenciada).
• [ ] Atualize a configuração do aplicativo para usar o novo tipo de credencial.
• [ ] Teste a nova credencial em um ambiente de teste.
• [ ] Implantar em produção.
• [ ] Remova o segredo do cliente antigo do portal Azure.
• [ ] Verifique as funções do aplicativo corretamente sem o segredo antigo.

Evitar erros comuns de segurança

Examine os seguintes antipadrões e suas alternativas recomendadas ao trabalhar com segredos do cliente:

Solucionar erros comuns

Esta seção aborda erros frequentes que você pode encontrar ao configurar segredos do cliente.

Segredo do cliente inválido

Erro: AADSTS7000215: Invalid client secret provided.

Causas possíveis::

• O valor do segredo foi copiado incorretamente. Os valores secretos podem conter caracteres especiais que são truncados durante operações de cópia/colagem.
• O segredo foi criado para um registro de aplicativo diferente do configurado em ClientId.
• O caminho de configuração está incorreto e o valor do segredo não está sendo lido pelo aplicativo.

Resolução:

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

2. Verifique se o ClientId e o TenantId em sua configuração correspondem ao registro do aplicativo em que o segredo foi criado.

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

   // 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.

Resolução:

1. Navegue até o registro do aplicativo no centro de administração do Microsoft Entra.
2. Verifique a data de validade em Certificados &segredos>Segredos do cliente.
3. Crie um novo segredo e atualize a configuração do aplicativo.
4. Exclua o segredo expirado do portal.

Segredo não encontrado na configuração

Sintoma: O aplicativo lança um NullReferenceException ou falha ao autenticar porque o valor do segredo é null.

Causas possíveis::

• Os Segredos do Usuário não são inicializados para o projeto.
• O nome da variável de ambiente não corresponde ao caminho de configuração esperado.
• Key Vault não está configurado como uma fonte de configuração.
• O aplicativo está em execução em um ambiente que não seja de desenvolvimento em que os Segredos do Usuário não são carregados.

Resolução:

1. Verifique se os User Secrets estão inicializados verificando a presença de um UserSecretsId no arquivo .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 em execução fora do ambiente de desenvolvimento, verifique se a fonte de configuração apropriada (variável de ambiente ou Key Vault) está disponível.

Conteúdo relacionado

• Certificados com Microsoft.Identity.Web
• Autenticação sem certificado
• Visão geral do cache de token
• Armazenamento seguro de segredos de aplicação durante o desenvolvimento no ASP.NET Core
• Fornecedor de configuração do Azure Key Vault no ASP.NET Core