Visão geral das credenciais para a Microsoft. Identity.Web

Quando a sua aplicação se autentica com a plataforma de identidades da Microsoft, apresenta uma credencial para provar a sua identidade. Microsoft. O Identity.Web suporta vários tipos de credenciais, cada um adequado a diferentes ambientes e requisitos de segurança.

Este artigo ajuda-o a compreender os tipos de credenciais disponíveis, escolher a certa para o seu cenário e configurar as credenciais na sua candidatura.

Por que a escolha da credencial é importante

A credencial que a sua aplicação utiliza afeta diretamente a sua postura de segurança, sobrecarga operacional e flexibilidade de implementação. Uma credencial mal escolhida pode expor segredos, exigir rotação manual ou limitar onde a sua candidatura pode correr.

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

• Especifique múltiplas credenciais com recuo automático.
• Alterar os tipos de credenciais sem modificar o código da aplicação.
• Use credenciais diferentes consoante o ambiente (desenvolvimento, encenação, produção).

Tipos de credenciais suportados

Microsoft. O Identity.Web suporta três categorias de credenciais para aplicações cliente confidenciais:

Credenciais sem certificado (credenciais Federated Identity + Managed Identity)

As credenciais sem certificado utilizam a Identidade Gerida do Azure combinada com Credenciais de Identidade Federada (FIC) para autenticar a sua aplicação sem gerir quaisquer segredos ou certificados. O Azure gere completamente o ciclo de vida das credenciais.

Como funciona: A sua aplicação usa a sua identidade gerida para obter um token, que o plataforma de identidades da Microsoft aceita como prova da identidade da aplicação através de um trust de federação pré-configurado.

Melhor para: Cargas de trabalho de produção executadas no Azure.

Saiba mais sobre autenticação sem certificado

Certificados

Os certificados fornecem uma autenticação forte e assimétrica baseada em chaves. A sua aplicação prova a sua identidade ao assinar uma afirmação com a chave privada do certificado. Microsoft. O Identity.Web pode carregar certificados de múltiplas fontes:

• Azure Key Vault - Armazenamento centralizado e gerido de certificados com políticas de acesso.
• Certificate Store - armazenamento de certificados do Windows (CurrentUser ou LocalMachine).
• Caminho do ficheiro - Ficheiro de certificado no disco (formato .pfx).
• Base64-codificado - Certificado incorporado diretamente na configuração.

Melhor para: Cargas de trabalho em produção onde não existem credenciais sem certificado, ou ambientes híbridos.

Saiba mais sobre credenciais de certificado

Segredos de cliente

Os segredos do cliente são cadeias partilhadas que a sua aplicação apresenta à plataforma de identidades da Microsoft. São o tipo de credencial mais simples de configurar, mas oferecem a segurança mais fraca.

Melhor para: Desenvolvimento local e testes apenas.

Saiba mais sobre segredos de clientes

Escolha o tipo de credencial certo

Use a seguinte árvore de decisão para determinar qual o tipo de credencial mais adequado para o seu caso.

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ções gerais

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

• Prefere sempre credenciais sem certificado quando a sua aplicação corre em Azure. Eliminam completamente a gestão de credenciais.
• Use certificados quando as credenciais sem certificado não estiverem disponíveis. Guarde-os no Azure Key Vault sempre que possível.
• Restringa os segredos dos clientes a ambientes de desenvolvimento. Nunca uses segredos do cliente em implementações de produção.

Compare tipos de credenciais

A tabela seguinte resume as principais diferenças entre os tipos de credenciais:

Configurar credenciais em appsettings.json

Microsoft. O Identity.Web utiliza um array ClientCredentials na sua configuração para especificar uma ou mais credenciais. Cada entrada no array inclui uma SourceType propriedade que indica a origem da credencial.

Estrutura de configuração

O exemplo seguinte 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 ao enum CredentialSource e determina como o Microsoft.Identity.Web carrega a credencial:

Exemplos de credenciais por tipo

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

Sem certificado (identidade gerida)

Use uma identidade gerida atribuída pelo utilizador, especificando o seu ID de 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 gerida atribuída ao sistema, omita a ManagedIdentityClientId propriedade:

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

Certificado do Azure Key Vault

Carregue um certificado armazenado no 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"
      }
    ]
  }
}

Também podes usar o CredentialDescription método helper em C#:

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

Certificado da loja de certificados

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

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

Também pode usar um nome distinto, 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#, usa o método helper:

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

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

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

Certificado codificado em Base64

Incorpore um certificado diretamente na configuração como uma cadeia codificada em Base64:

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

Segredo do cliente

Especifique um segredo de cliente para desenvolvimento e teste:

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

Utilize múltiplas credenciais com opção de fallback

Podes especificar múltiplas credenciais no ClientCredentials array. Microsoft.Identity.Web tenta cada credencial pela ordem e recorre à seguinte se a atual falhar. Este padrão é útil para aplicações que correm em múltiplos 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. A aplicação tenta primeiro autenticação sem certificado com identidade gerida (funciona no Azure).
2. Se a identidade gerida não estiver disponível, recorre a um certificado do Key Vault.
3. Como último recurso, utiliza um segredo do cliente (para desenvolvimento local).

Esta abordagem permite-lhe usar o mesmo ficheiro de configuração entre ambientes sem alterações de código.

Configurar credenciais no código

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 desencriptação de tokens

Para além das credenciais do cliente para autenticação, a Microsoft. O Identity.Web também suporta credenciais para desencriptação de tokens. Use credenciais de desencriptação de tokens quando a sua aplicação receber tokens encriptados e precisar de os desencriptar.

As credenciais de desencriptação de tokens usam os mesmos SourceType valores e padrões de configuração que as credenciais do cliente, mas são especificadas no TokenDecryptionCredentials array:

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

Saiba mais sobre desencriptação de tokens

Melhores práticas

Tenha estas recomendações em mente ao configurar as credenciais para a sua aplicação:

Prefiro credenciais sem certificado em produção. Eliminam o risco de exposição secreta e eliminam a sobrecarga de rotação. Use-os sempre que a sua aplicação corra em recursos computacionais do Azure que suportem identidade gerida.

Use uma solução de recurso para as credenciais para garantir a portabilidade. Configure múltiplas credenciais por ordem de prioridade para que a sua aplicação funcione durante o desenvolvimento, staging e produção sem alterações no código.

Nunca uses segredos de clientes em produção. Os segredos do cliente podem ser divulgados através de logs, ficheiros de configuração ou controlo de versão. Use certificados ou credenciais sem certificado em vez disso.

Armazene valores sensíveis fora dos ficheiros de configuração. Use o Azure Key Vault, variáveis de ambiente ou o ASP.NET Core Secret Manager para palavras-passe de certificados e segredos do cliente. Não comprometas valores sensíveis no controlo de versão.

Rode os certificados antes de expirar. Monitorizar as datas de validade dos certificados e estabelecer um processo de rotação. O Azure Key Vault pode automatizar a renovação de certificados.

Use o Azure Key Vault para armazenamento de certificados. O Key Vault fornece gestão centralizada, políticas de acesso, registo de auditorias e rotação automática de certificados.

Conteúdo relacionado

• Autenticação sem certificado
• Credenciais de certificação
• Desencriptação de tokens
• Segredos dos clientes