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.

Importante

Os segredos do cliente só devem ser usados em ambientes de desenvolvimento e testes. Para cargas de trabalho de produção, utilize certificados ou credenciais sem certificado , como identidades geridas ou credenciais de identidade federadas. Os segredos dos clientes são mais fáceis de comprometer do que credenciais baseadas em certificados e não podem ser atribuídos a operações específicas.

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:

Tipo de credencial Ambiente recomendado Nível de segurança
Segredo do cliente Desenvolvimento, testes Baixo
Certidão Encenação, produção Alto
Identidade gerenciada Produção alojada no Azure Máximo
Identidade federada CI/CD, Kubernetes Alto

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.

Advertência

Nunca guardes valores secretos reais no controlo de código fonte. O YOUR_SECRET_VALUE marcador de posição no exemplo anterior deve ser substituído por uma referência a um armazenamento seguro, conforme descrito nas secções seguintes.

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"

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.

Sugestão

Mesmo ao usar o Key Vault para armazenar um segredo de cliente, considere se a sua carga de trabalho em produção seria melhor servida por certificados ou identidades geridas. O Key Vault é útil para ambientes de desenvolvimento partilhado ou staging, mas as aplicações de produção devem usar tipos de credenciais mais fortes.

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.

Importante

Regista o valor secreto num local seguro imediatamente após a criação. O Microsoft Entra ID só mostra o valor no momento da criação. Se perderes o valor, tens de criar um novo segredo.

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:

Anti-padrão Risco Recommendation
Inclusão fixa de informações confidenciais no código-fonte Segredo exposto no controlo de versões Use User Secrets, variáveis de ambiente ou Key Vault
Comprometer-se appsettings.Development.json com segredos Segredo exposto a qualquer pessoa com acesso ao repositório Adicione o ficheiro a .gitignore e use os Segredos de Utilizador em vez disso
Partilha de segredos entre ambientes Segredo de desenvolvimento comprometido expõe produção Use segredos únicos por ambiente
Utilização de segredos na produção Maior risco de roubo de credenciais Migrar para certificados ou identidades geridas
Criação de segredos sem plano de expiração Interrupção de aplicação quando o segredo expira Definir lembretes de expiração e implementar rotação
Registo de valores secretos Segredo exposto em ficheiros de registo Nunca registar os valores das credenciais; regista apenas o tipo de fonte da credencial
Armazenar segredos em ficheiros de texto simples em servidores Segredo exposto a qualquer pessoa com acesso ao servidor Use variáveis de ambiente ou Key Vault

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

  • Last updated on