Configurar a desencriptação de tokens na Microsoft. Identity.Web

Este artigo explica como configurar certificados de desencriptação de tokens na Microsoft. Identity.Web para que a sua aplicação possa desencriptar tokens encriptados da plataforma de identidades da Microsoft.

Por defeito, a plataforma de identidade da Microsoft emite tokens (ID tokens, tokens SAML) como JWTs assinados mas não encriptados. Qualquer intermediário que intercete um token pode ler as suas reivindicações. Para aplicações que lidam com reclamações sensíveis ou operam em ambientes de conformidade rigorosa, o plataforma de identidades da Microsoft suporta encriptação token. Quando ativada, a plataforma de identidade encripta o payload do token usando uma chave pública registada na sua aplicação. Só a sua aplicação — que detém a chave privada correspondente — pode desencriptar e ler o token.

Como funciona a encriptação de tokens

  1. Geras um certificado com um par de chaves pública/privada.
  2. Carregas o chave pública (o ficheiro .cer) para o registo da tua aplicação em Microsoft Entra ID.
  3. Quando a plataforma de identidades da Microsoft emite um token para a sua aplicação, encripta o token usando a sua chave pública.
  4. A sua aplicação usa a chave privada para desencriptar o token antes de processar as reclamações.

A encriptação utiliza um esquema de duas camadas: a carga útil do token é encriptada com uma chave de encriptação de conteúdo simétrica, que é enrolada (encriptada) usando a sua chave pública. Microsoft Entra suporta algoritmos de enrolamento de chaves RSA-OAEP e RSA-OAEP-256.

Determinar quando configurar a desencriptação de tokens

Configure a desencriptação de tokens quando a sua aplicação cumpra uma das seguintes condições:

  • Recebe tokens SAML encriptados — Aplicações empresariais que utilizam login único baseado em SAML e requerem asserções SAML encriptadas por razões de conformidade ou regulatórias.
  • Recebe tokens de identificação encriptados — Aplicações web que optam por encriptar tokens de identificação para proteger reivindicações sensíveis (pertenças a grupos, reivindicações personalizadas) de serem lidas em trânsito.
  • Opera em ambientes de alta segurança — Aplicações em cenários governamentais, financeiros ou de saúde onde a confidencialidade dos tokens é exigida pela política.

Observação

A encriptação de tokens é opcional. A maioria das aplicações não precisa disso. Só ativa a encriptação do token se tiveres um requisito específico, porque acrescenta complexidade operacional (gestão de certificados, rotação) e torna a resolução de problemas mais difícil.

Cumprir os pré-requisitos

Antes de configurar a desencriptação de tokens, verifique os seguintes requisitos:

  • Um certificado X.509 com chave privada — Precisa de um certificado no formato .pfx (PKCS#12) ou armazenado num local acessível à sua aplicação (Azure Key Vault, armazenamento de certificados ou sistema de ficheiros). A chave privada é necessária para desencriptar tokens.
  • Registo de aplicações configurado para encriptação de tokens — Carregue a chave pública do certificado para o registo da sua aplicação em Microsoft Entra ID. Consulte Registar o certificado de desencriptação mais adiante neste artigo.
  • Microsoft. Identity.Web 2.1.0 ou posterior — A propriedade de configuração TokenDecryptionCredentials está disponível em Microsoft. Identity.Web 2.1.0 e posteriores.

Configurar a desencriptação de tokens no appsettings.json

Microsoft.Identity.Web utiliza o array TokenDecryptionCredentials na secção de configuração AzureAd. Este array segue o mesmo formato de descrição de credenciais que ClientCredentials, pelo que pode carregar certificados de desencriptação a partir de Azure Key Vault, do armazenamento de certificados, de um caminho de ficheiro ou de uma cadeia codificada em Base64.

Configurar uma configuração básica

O exemplo seguinte mostra a configuração mínima para carregar um certificado de desencriptação do Azure Key Vault:

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

    "TokenDecryptionCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
        "KeyVaultCertificateName": "MyCertificate"
      }
    ]
  }
}

Não é necessário código adicional. Quando a Microsoft.Identity.Web deteta a configuração TokenDecryptionCredentials, carrega automaticamente o certificado especificado e regista-o com o handler de autenticação OpenID Connect para decifração de tokens.

Escolha uma fonte de credencial

O TokenDecryptionCredentials array suporta os mesmos tipos de fonte que ClientCredentials. A tabela seguinte resume cada opção:

Tipo de fonte Descrição Propriedades necessárias
KeyVault Carregue o certificado do Azure Key Vault. Recomendado para produção. KeyVaultUrl, KeyVaultCertificateName
StoreWithThumbprint Carregue a partir da loja de certificados local por impressão digital. CertificateStorePath, CertificateThumbprint
ArmazenarComNomeDistinguido Carregue na loja local de certificados por assunto, nome distinto. CertificateStorePath, CertificateDistinguishedName
Path Carregar a partir de um .pfx ficheiro no sistema de ficheiros. CertificateDiskPath, CertificatePassword
Base64Encoded Carregar a partir de uma cadeia codificada .pfx em Base64 (útil para variáveis de ambiente). Base64EncodedValue

A seguinte configuração carrega um certificado de desencriptação do Azure Key Vault:

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "KeyVault",
      "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
      "KeyVaultCertificateName": "TokenDecryptionCert"
    }
  ]
}

A identidade gerida ou o principal de serviço da sua aplicação deve ter permissões Get e List nos certificados de Key Vault.

Armazenamento de certificados (Windows)

A seguinte configuração carrega um certificado do armazenamento de certificados do Windows por impressão digital:

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "StoreWithThumbprint",
      "CertificateStorePath": "CurrentUser/My",
      "CertificateThumbprint": "A1B2C3D4E5F6..."
    }
  ]
}

Caminho do arquivo

A seguinte configuração carrega um certificado a partir de um .pfx ficheiro no disco:

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "Path",
      "CertificateDiskPath": "/var/ssl/private/decrypt-cert.pfx",
      "CertificatePassword": "your-certificate-password"
    }
  ]
}

Advertência

Evite armazenar palavras-passe de certificado em appsettings.json no ambiente de produção. Use variáveis de ambiente, referências ao Azure Key Vault ou um gestor de segredos em vez disso.

Codificado em Base64

A seguinte configuração carrega um certificado a partir de uma cadeia codificada em Base64:

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "Base64Encoded",
      "Base64EncodedValue": "MIIJ..."
    }
  ]
}

Esta opção é útil quando injeta o certificado através de uma variável de ambiente ou de um segredo do pipeline CI/CD.

Configurar múltiplos certificados de desencriptação

Pode especificar múltiplos certificados no TokenDecryptionCredentials array. Microsoft.Identity.Web testa cada certificado por ordem até que um que descodifique com sucesso o token. Esta capacidade é essencial para a rotação de certificados (ver rotação de certificados).

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "KeyVault",
      "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
      "KeyVaultCertificateName": "TokenDecryptionCert-New"
    },
    {
      "SourceType": "KeyVault",
      "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
      "KeyVaultCertificateName": "TokenDecryptionCert-Old"
    }
  ]
}

Registar o certificado de desencriptação no Microsoft Entra ID

Para que a plataforma de identidades da Microsoft encripte tokens para a sua aplicação, deve carregar a c0 do certificado para o registo da sua aplicação:

  1. Inicia sessão no centro de administração Microsoft Entra.
  2. Navegue até Identidade>Applications>Registos de aplicações e selecione a sua aplicação.
  3. Selecione Certificados & segredos>>
  4. Carrega o .cer ficheiro (apenas chave pública) do teu certificado de desencriptação.
  5. Após o carregamento, note o valor da impressão digital — deve corresponder ao certificado que a sua candidatura utiliza.

Ativar a encriptação de tokens para a aplicação

Após carregar o certificado, deve configurar a sua aplicação para receber tokens encriptados. Esta configuração está atualmente disponível através da Microsoft Graph API ou PowerShell:

Usando Microsoft Graph PowerShell:

# Get the key credential ID of the uploaded certificate
$app = Get-MgApplication -Filter "appId eq 'your-client-id'"
$keyId = ($app.KeyCredentials | Where-Object { $_.DisplayName -eq "CN=TokenDecryptionCert" }).KeyId

# Set the token encryption key ID
Update-MgApplication -ApplicationId $app.Id -BodyParameter @{
    "tokenEncryptionKeyId" = $keyId
}

Importante

A propriedade tokenEncryptionKeyId no objeto de aplicação identifica qual certificado carregado Microsoft Entra utiliza para encriptar tokens. Apenas uma chave de encriptação pode estar ativa de cada vez.

Rotação dos certificados de desencriptação

A rotação de certificados para desencriptação de tokens requer uma abordagem cuidadosa e faseada para evitar tempos de inatividade:

Passos de rotação

  1. Gerar um novo certificado — Criar um novo certificado X.509 com uma chave privada.
  2. Adicione o novo certificado à configuração da sua aplicação — Adicione o novo certificado ao TokenDecryptionCredentials array juntamente com o certificado existente. Coloque o novo certificado primeiro na matriz.
  3. Carregar a nova chave pública — Carregue o ficheiro .cer do novo certificado para o registo da sua aplicação em Microsoft Entra.
  4. Implemente a sua aplicação — Implemente a configuração atualizada para que a sua aplicação possa desencriptar tokens com qualquer um dos certificados.
  5. Mudar a chave de encriptação ativa — Atualizar o tokenEncryptionKeyId no objeto de aplicação para apontar para o novo certificado keyId.
  6. Verificar — Confirme que a sua aplicação desencripta com sucesso os tokens encriptados com o novo certificado.
  7. Remover o certificado antigo — Após um período de carência (pelo menos 24 horas para permitir que os tokens em cache expirem), remova o certificado antigo tanto do registo da sua aplicação como da configuração da sua aplicação.

Configuração durante a rotação

Durante a janela de rotação, o seu TokenDecryptionCredentials deve conter ambos os certificados:

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "KeyVault",
      "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
      "KeyVaultCertificateName": "TokenDecryptionCert-2026"
    },
    {
      "SourceType": "KeyVault",
      "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
      "KeyVaultCertificateName": "TokenDecryptionCert-2025"
    }
  ]
}

Sugestão

Automatize a rotação de certificados usando a funcionalidade de rotação automática do Azure Key Vault combinada com notificações de eventos do Key Vault para desencadear reimplantações de aplicações.

Resolução de problemas na desencriptação de tokens

Utilize as seguintes orientações para diagnosticar e resolver problemas comuns de desencriptação de tokens.

Falhas na desencriptação de tokens

Sintoma: A sua aplicação gera ou SecurityTokenDecryptionFailedException devolve um erro 401/500 ao processar tokens.

Causas comuns:

Motivo Solução
Certificado não encontrado Verifique se o certificado existe no local configurado (Key Vault, armazenamento ou caminho do ficheiro). Verifica se a tua aplicação tem as permissões necessárias para aceder.
Certificado errado Verifique se a impressão digital do certificado na configuração da sua aplicação corresponde ao certificado carregado no registo da aplicação.
tokenEncryptionKeyId não definido Defina a propriedade tokenEncryptionKeyId no objeto de aplicação em Microsoft Entra. Sem esta propriedade, a plataforma de identidade não encripta tokens.

Chave privada em falta

Sintoma:CryptographicException: The certificate key is not accessible ou InvalidOperationException: Certificate does not have a private key.

Causas e soluções:

  • Certificado exportado sem chave privada — Reexporte o certificado em .pfx formato e certifique-se de que inclui a chave privada durante a exportação.
  • Política de acesso do Key Vault — Ao usar o Azure Key Vault, certifique-se de que a identidade da sua aplicação tem a permissão Get tanto em Certificados como em Segredos. A chave privada é armazenada como segredo no Key Vault.
  • Permissões da loja de certificados — No Windows, verifique se a identidade do pool de aplicações ou a conta de serviço tem acesso de leitura à chave privada. Use a opção Gerir Chaves Privadas no snap-in MMC da loja de certificados.

Incompatibilidade de algoritmos

Sintoma:SecurityTokenDecryptionFailedException com uma mensagem que indica um algoritmo não suportado.

Causas e soluções:

  • Tipo de chave não suportado — Microsoft Entra suporta certificados RSA para encriptação de tokens. Garante que o teu certificado utiliza um par de chaves RSA (não EC/ECDSA).
  • Tamanho da chave demasiado pequeno — Use um tamanho de chave de pelo menos 2048 bits. Chaves RSA menores que 2048 bits podem ser rejeitadas.
  • Algoritmo não suportado — Microsoft Entra usa RSA-OAEP para envolvimento de chaves. Assegure que o seu certificado e infraestrutura de aplicação suportam este algoritmo.

Tokens encriptados não estão a ser emitidos

Sintoma: A sua aplicação recebe tokens não encriptados mesmo tendo configurado a desencriptação dos tokens.

Causas e soluções:

  • tokenEncryptionKeyId não configurado — Deve definir explicitamente esta propriedade através de Microsoft Graph. Carregar apenas o certificado não é suficiente.
  • Certificado expirado no registo da aplicação — Verifique se o certificado carregado no registo da sua aplicação não expirou. Carregue um novo certificado se necessário.
  • Os tokens de acesso não são encriptados — A encriptação dos tokens aplica-se apenas a tokens ID e tokens SAML . Os tokens de acesso da Microsoft Entra não estão encriptados com o seu certificado.

Compare a desencriptação de tokens e as credenciais do cliente

As credenciais de desencriptação de tokens têm um propósito diferente das credenciais do cliente. A sua aplicação pode usar o mesmo certificado para ambos, ou usar certificados separados.

O exemplo seguinte mostra uma configuração que utiliza o mesmo certificado Key Vault tanto para autenticação como para desencriptação de tokens:

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
        "KeyVaultCertificateName": "AppAuthCert"
      }
    ],
    "TokenDecryptionCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
        "KeyVaultCertificateName": "AppAuthCert"
      }
    ]
  }
}

Observação

Quando usas o mesmo certificado para ambos os propósitos, o certificado deve ter a KeyEncipherment utilização da chave e usar a KeyExchange especificação da chave (não Signature). Os certificados gerados com KeySpec = Signature funcionam para as credenciais de cliente, mas falham na descriptação de tokens.

Siga as melhores práticas

Aplique estas recomendações ao implementar a desencriptação de tokens.

Use Azure Key Vault — Armazene certificados de desencriptação em Key Vault para gestão centralizada, controlo de acesso e registo de auditorias.

Planeie a rotação — Tenha sempre uma estratégia de rotação antes de implementar a encriptação dos tokens. Inclua tanto os certificados novos como os antigos durante o período de rotação.

Use chaves RSA de 2048 bits ou maiores — Certifique-se de que os seus certificados utilizam chaves RSA de pelo menos 2048 bits para garantir uma segurança adequada.

Monitorizar expiração do certificado — Configure alertas no Azure Key Vault ou no seu sistema de monitorização para o notificar antes de os certificados expirarem.

Teste num ambiente de staging — Verifique a encriptação e desencriptação dos tokens num ambiente não de produção antes de o ativar em produção.

Não armazene chaves privadas no controlo de versão — Use Key Vault, variáveis de ambiente ou um gestor de segredos para armazenamento de certificados.

Não remova o certificado antigo demasiado cedo durante a rotação — Mantenha ambos os certificados ativos durante pelo menos 24 horas para permitir que os tokens em cache expirem.

Não ative a encriptação de tokens sem um certificado de desencriptação configurado — A sua aplicação falhará em processar tokens se não conseguir desencriptá-los.

Conteúdo relacionado

  • Last updated on