Visão geral de credenciais para Microsoft. Identity.Web

Quando seu aplicativo é autenticado com o plataforma de identidade da Microsoft, ele apresenta uma credencial para provar sua identidade. Microsoft. O Identity.Web dá suporte a vários tipos de credencial, cada um adequado para diferentes ambientes e requisitos de segurança.

Este artigo ajuda você a entender os tipos de credencial disponíveis, escolher o ideal para seu cenário e configurar credenciais em seu aplicativo.

Por que a escolha da credencial importa

A credencial que seu aplicativo usa afeta diretamente sua postura de segurança, sobrecarga operacional e flexibilidade de implantação. Uma credencial mal escolhida pode expor segredos, exigir rotação manual ou limitar onde seu aplicativo pode ser executado.

Microsoft. O Identity.Web fornece um modelo de configuração unificado que permite:

• Especifique várias credenciais com fallback automático.
• Altere os tipos de credencial sem modificar o código do aplicativo.
• Use credenciais diferentes por ambiente (desenvolvimento, preparo, produção).

Tipos de credencial com suporte

Microsoft. O Identity.Web dá suporte a três categorias de credenciais para aplicativos cliente confidenciais:

Credenciais sem certificado (credenciais de Identidade Federada + Identidade Gerenciada)

As credenciais sem certificado usam Azure Identidade Gerenciada combinada com as Credenciais de Identidade Federadas (FIC) para autenticar seu aplicativo sem gerenciar segredos ou certificados. Azure manipula totalmente o ciclo de vida da credencial.

Como funciona: seu aplicativo usa sua identidade gerenciada para obter um token, que o plataforma de identidade da Microsoft aceita como prova da identidade do aplicativo por meio de uma relação de confiança de federação pré-configurada.

Ideal para: cargas de trabalho de produção que estão em execução no Azure.

Saiba mais sobre autenticação sem certificado

Certificados

Os certificados fornecem autenticação forte e assimétrica baseada em chave. Seu aplicativo prova sua identidade assinando uma declaração com a chave privada do certificado. Microsoft. Identity.Web pode carregar certificados de várias fontes:

• Azure Key Vault – armazenamento de certificados gerenciado centralizado com políticas de acesso.
• Certificate Store – repositório de certificados Windows (CurrentUser ou LocalMachine).
• Caminho do arquivo – Arquivo de certificado em disco (formato .pfx).
• Codificado em Base64 – Certificado inserido diretamente na configuração.

Melhor para: Cargas de trabalho de produção em que as credenciais sem certificado não estão disponíveis ou ambientes híbridos.

Saiba mais sobre credenciais de certificado

Segredos do cliente

Os segredos do cliente são cadeias de caracteres compartilhadas que seu aplicativo apresenta à plataforma de identidade da Microsoft. Eles são o tipo de credencial mais simples a ser configurado, mas oferecem a segurança mais fraca.

Melhor para: Somente desenvolvimento e teste local.

Saiba mais sobre segredos do cliente

Escolher o tipo de credencial correto

Use a árvore de decisão a seguir para determinar qual tipo de credencial é apropriado para seu cenário.

Is your application running on Azure?
├── Yes
│   ├── Can you use Managed Identity?
│   │   ├── Yes → Use certificateless credentials (recommended)
│   │   └── No → Use certificates from Azure Key Vault
└── No
    ├── Is this a production environment?
    │   ├── Yes → Use certificates (Key Vault, Certificate Store, or file path)
    │   └── No → Use client secrets for development/testing

Orientação geral

Siga estes princípios ao selecionar um tipo de credencial:

• Sempre prefira credenciais sem certificado quando o aplicativo é executado no Azure. Eles eliminam totalmente o gerenciamento de credenciais.
• Use certificados quando as credenciais sem certificado não estiverem disponíveis. Armazene-os em Azure Key Vault sempre que possível.
• Restrinja segredos do cliente a ambientes de desenvolvimento. Nunca use segredos do cliente em implantações de produção.

Comparar tipos de credencial

A tabela a seguir resume as principais diferenças entre os tipos de credencial:

Configurar credenciais no appsettings.json

Microsoft. O Identity.Web usa uma matriz ClientCredentials em sua configuração para especificar uma ou mais credenciais. Cada entrada na matriz inclui uma SourceType propriedade que indica de onde vem a credencial.

Estrutura de configuração

O exemplo a seguir mostra uma configuração mínima com uma única credencial sem certificado:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",

    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity",
        "ManagedIdentityClientId": "user-assigned-managed-identity-client-id"
      }
    ]
  }
}

Valores de SourceType

A propriedade SourceType corresponde à enumeração CredentialSource e determina como Microsoft. Identity.Web carrega a credencial:

Exemplos de credencial por tipo

Os exemplos a seguir mostram como configurar cada tipo de credencial em appsettings.json e, quando disponível, no código C#.

Sem certificado (identidade gerenciada)

Use uma identidade gerenciada atribuída pelo usuário especificando sua ID do cliente:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity",
        "ManagedIdentityClientId": "user-assigned-managed-identity-client-id"
      }
    ]
  }
}

Para a identidade gerenciada atribuída pelo sistema, omita a ManagedIdentityClientId propriedade:

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity"
      }
    ]
  }
}

Certificado de Azure Key Vault

Carregue um certificado armazenado em Azure Key Vault especificando a URL do cofre e o nome do certificado:

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

Você também pode usar o CredentialDescription método auxiliar em C#:

var credential = CredentialDescription.FromKeyVault(
    "https://your-keyvault.vault.azure.net",
    "your-certificate-name");

Certificado do repositório de certificados

Carregue um certificado do repositório de certificados Windows por impressão digital:

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "StoreWithThumbprint",
        "CertificateThumbprint": "ABC123DEF456...",
        "CertificateStorePath": "CurrentUser/My"
      }
    ]
  }
}

Você também pode usar um nome diferenciado, o que simplifica a rotação de certificados porque o novo certificado é selecionado automaticamente:

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "StoreWithDistinguishedName",
        "CertificateDistinguishedName": "CN=YourAppCertificate",
        "CertificateStorePath": "CurrentUser/My"
      }
    ]
  }
}

Em C#, use o método auxiliar:

// By thumbprint
var credential = CredentialDescription.FromCertificateStore(
    "CurrentUser/My",
    thumbprint: "ABC123DEF456...");

// By distinguished name (recommended for rotation)
var credential = CredentialDescription.FromCertificateStore(
    "CurrentUser/My",
    distinguishedName: "CN=YourAppCertificate");

Certificado a partir do caminho do arquivo

Carregar um certificado a partir de um arquivo .pfx no disco:

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "Path",
        "CertificateDiskPath": "/var/certs/app-cert.pfx",
        "CertificatePassword": "certificate-password"
      }
    ]
  }
}

Certificado codificado em Base64

Insira um certificado diretamente na configuração como uma cadeia de caracteres codificada em Base64:

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "Base64Encoded",
        "Base64EncodedValue": "MIIKcQIBAzCCCi0..."
      }
    ]
  }
}

Segredo do cliente

Especifique uma cadeia de caracteres de segredo do cliente para desenvolvimento e teste:

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "ClientSecret",
        "ClientSecret": "your-client-secret"
      }
    ]
  }
}

Usar múltiplas credenciais com alternativa de segurança

Você pode especificar várias credenciais na ClientCredentials matriz. Microsoft. Identity.Web tenta cada credencial em ordem e volta para a próxima se a atual falhar. Esse padrão é útil para aplicativos executados em vários ambientes.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity",
        "ManagedIdentityClientId": "your-managed-identity-client-id"
      },
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://your-keyvault.vault.azure.net",
        "KeyVaultCertificateName": "your-certificate-name"
      },
      {
        "SourceType": "ClientSecret",
        "ClientSecret": "development-only-secret"
      }
    ]
  }
}

Neste exemplo:

1. O aplicativo primeiro tenta autenticação sem certificado com identidade gerenciada (funciona em Azure).
2. Se a identidade gerenciada não estiver disponível, ela retornará a um certificado de Key Vault.
3. Como último recurso, ele usa um segredo do cliente (para desenvolvimento local).

Essa abordagem permite que você use o mesmo arquivo de configuração em ambientes sem alterações de código.

Configurar credenciais no código

Você também pode configurar credenciais programaticamente em Program.cs ou Startup.cs:

using Microsoft.Identity.Web;

builder.Services.AddMicrosoftIdentityWebAppAuthentication(builder.Configuration, "AzureAd")
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddDownstreamApi("MyApi", builder.Configuration.GetSection("MyApi"))
    .AddDistributedTokenCaches();

// Or configure credentials programmatically
builder.Services.Configure<MicrosoftIdentityOptions>(options =>
{
    options.ClientCredentials = new[]
    {
        new CredentialDescription
        {
            SourceType = CredentialSource.SignedAssertionFromManagedIdentity,
            ManagedIdentityClientId = "your-managed-identity-client-id"
        }
    };
});

Credenciais de descriptografia de token

Além das credenciais do cliente para autenticação, Microsoft. Identity.Web também dá suporte a credenciais para descriptografia de token. Use credenciais para descriptografia de tokens quando seu aplicativo receber tokens criptografados e precisar descriptografá-los.

As credenciais de descriptografia de token usam os mesmos SourceType valores e padrões de configuração que as credenciais do cliente, mas são especificados na TokenDecryptionCredentials matriz:

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

Saiba mais sobre a descriptografia de token

Práticas recomendadas

Tenha estas recomendações em mente ao configurar credenciais para seu aplicativo:

Prefira credenciais sem certificado na produção. Eles eliminam o risco de exposição de segredos e removem a sobrecarga associada à rotação. Use-os sempre que seu aplicativo for executado em recursos de computação do Azure que suportam identidade gerenciada.

Use alternativa de credencial para portabilidade. Configure várias credenciais em ordem de prioridade para que seu aplicativo funcione entre desenvolvimento, preparo e produção sem alterações de código.

Nunca use segredos do cliente em produção. Os segredos do cliente podem vazar por meio de logs, arquivos de configuração ou controle do código-fonte. Em vez disso, use certificados ou credenciais sem certificado.

Armazene valores confidenciais fora dos arquivos de configuração. Use Azure Key Vault, variáveis de ambiente ou o Gerenciador de Segredos ASP.NET Core para senhas de certificado e segredos do cliente. Não confirme valores confidenciais no controle do código-fonte.

Renove certificados antes de expirarem. Monitore as datas de validade do certificado e estabeleça um processo de rotação. Azure Key Vault pode automatizar a renovação do certificado.

Use Azure Key Vault para armazenamento de certificados. Key Vault fornece gerenciamento centralizado, políticas de acesso, log de auditoria e rotação automática para certificados.

Conteúdo relacionado

• Autenticação sem certificado
• Credenciais de certificado
• Descriptografia de token
• Segredos do cliente