Configure descriptografia de tokens no Microsoft.Identity.Web

Este artigo explica como configurar certificados para descriptografar tokens no Microsoft.Identity.Web para permitir que seu aplicativo descriptografe tokens criptografados da plataforma de identidade Microsoft.

Por padrão, o plataforma de identidade da Microsoft emite tokens (tokens de ID, tokens SAML) como JWTs assinados, mas não criptografados. Qualquer intermediário que intercepta um token pode ler suas declarações. Para aplicativos que lidam com declarações confidenciais ou operam em ambientes de conformidade estritos, o plataforma de identidade da Microsoft dá suporte à criptografia token. Quando habilitada, a plataforma de identidade criptografa o conteúdo do token usando uma chave pública registrada com seu aplicativo. Somente o aplicativo, que contém a chave privada correspondente, pode descriptografar e ler o token.

Como funciona a criptografia de token

1. Você gera um certificado com um par de chaves pública/privada.
2. Faça upload da chave pública (o arquivo .cer) no registro do aplicativo no Microsoft Entra ID.
3. Quando o plataforma de identidade da Microsoft emite um token para seu aplicativo, ele criptografa o token usando sua chave pública.
4. Seu aplicativo usa a chave privada para descriptografar o token antes de processar declarações.

A criptografia usa um esquema de duas camadas: o conteúdo do token é criptografado com uma chave de criptografia de conteúdo simétrica, que é encapsulada (criptografada) usando sua chave pública. Microsoft Entra dá suporte a algoritmos de encapsulamento de chave RSA-OAEP e RSA-OAEP-256.

Determinar quando configurar a descriptografia de um token

Configure a descriptografia de token quando seu aplicativo atender a uma das seguintes condições:

• Recebe tokens SAML criptografados — aplicativos empresariais que usam logon único baseado em SAML e exigem declarações SAML criptografadas por motivos de conformidade ou regulamentação.
• Recebe tokens de ID criptografados – aplicativos Web que optam pela criptografia de token de ID para proteger declarações confidenciais (associações de grupo, declarações personalizadas) de serem lidas em trânsito.
• Opera em ambientes de alta segurança – aplicativos em cenários governamentais, financeiros ou de saúde em que a confidencialidade do token é exigida pela política.

Atender aos pré-requisitos

Antes de configurar a descriptografia de token, verifique os seguintes requisitos:

• Um certificado X.509 com uma chave privada — você precisa de um certificado no formato .pfx (PKCS#12) ou armazenado em um local acessível ao seu aplicativo (Azure Key Vault, repositório de certificados ou sistema de arquivos). A chave privada é necessária para descriptografar tokens.
• Registro de aplicativo configurado para criptografia de token — Carregue a chave pública do certificado no registro de aplicativo no Microsoft Entra ID. Consulte Registrar o certificado de descriptografia 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 posterior.

Configurar descriptografia de token em appsettings.json

Microsoft. Identity.Web usa a matriz TokenDecryptionCredentials na seção de configuração AzureAd. Essa matriz segue o mesmo formato de descrição de credencial que ClientCredentials, para que você possa carregar certificados de descriptografia de Azure Key Vault, o repositório de certificados, um caminho de arquivo ou uma cadeia de caracteres codificada em Base64.

Configurar uma configuração básica

O exemplo a seguir mostra a configuração mínima para carregar um certificado de descriptografia de 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"
      }
    ]
  }
}

Nenhum código adicional é necessário. Quando o Microsoft.Identity.Web detecta a configuração TokenDecryptionCredentials, ele carrega automaticamente o certificado especificado e o registra no manipulador de autenticação do OpenID Connect para decodificação de token.

Escolher uma fonte de credencial

A TokenDecryptionCredentials matriz dá suporte aos mesmos tipos de origem que ClientCredentials. A tabela a seguir resume cada opção:

Key Vault (recomendado para produção)

A configuração a seguir carrega um certificado de descriptografia de Azure Key Vault:

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

A identidade gerenciada do aplicativo ou a entidade de serviço devem ter permissões Get e List nos certificados Key Vault.

Repositório de certificados (Windows)

A configuração a seguir carrega um certificado do repositório de certificados Windows por impressão digital:

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

Caminho do arquivo

A configuração a seguir carrega um certificado de um .pfx arquivo em disco:

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

Codificado em Base64

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

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

Essa opção é útil quando você insere o certificado através de uma variável de ambiente ou segredo no pipeline de CI/CD.

Configurar vários certificados de descriptografia

Você pode especificar vários certificados na TokenDecryptionCredentials matriz. Microsoft. Identity.Web tenta cada certificado em ordem até que um deles descriptografe o token com êxito. Essa funcionalidade é essencial para a rotação de certificados (consulte rotação de certificado).

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

Registrar o certificado de descriptografia no Microsoft Entra ID

Para que o plataforma de identidade da Microsoft criptografe tokens para seu aplicativo, você deve carregar a chave publica do certificado no registro do aplicativo:

1. Entre no centro de administração do Microsoft Entra.
2. Navegue até Identity>Applications>Registros de aplicativo e selecione seu aplicativo.
3. Selecione Certificados e segredos>Certificados>Carregar certificado.
4. Carregue o arquivo .cer do certificado de descriptografia (somente chave pública).
5. Depois de carregar, observe o valor da impressão digital – ele deve corresponder ao certificado que seu aplicativo usa.

Habilitar a criptografia de token para o aplicativo

Depois de carregar o certificado, você deve configurar seu aplicativo para receber tokens criptografados. No momento, essa configuração está disponível por meio do Microsoft API do Graph ou do PowerShell:

Using 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
}

Rotacionar certificados de decodificação

A rotação de certificados para a descriptografia de tokens requer uma abordagem cuidadosa e por etapas a fim de evitar interrupções no serviço.

Etapas de rotação

1. Gerar um novo certificado — crie um novo certificado X.509 com uma chave privada.
2. Adicione o novo certificado à configuração do aplicativo – adicione o novo certificado à TokenDecryptionCredentials matriz junto com o certificado existente. Coloque o novo certificado primeiro na matriz.
3. Carrege a nova chave pública — carregue o arquivo .cer do novo certificado no registro do aplicativo no Microsoft Entra.
4. Implantar seu aplicativo – Implante a configuração atualizada para que seu aplicativo possa descriptografar tokens com qualquer um dos certificados.
5. Alterne a chave de criptografia ativa – atualize o tokenEncryptionKeyId objeto do aplicativo para apontar para o novo certificado keyId.
6. Verifique — confirme que seu aplicativo consegue descriptografar com êxito os tokens que foram criptografados com o novo certificado.
7. Remova o certificado antigo — após um período de carência (pelo menos 24 horas para permitir que os tokens armazenados em cache expirem), remova o certificado antigo do registro do aplicativo e da configuração do aplicativo.

Configuração durante a rotação

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

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

Solucionar problemas de descriptografia de token

Use as diretrizes a seguir para diagnosticar e resolver problemas comuns de descriptografia de token.

Falhas na decriptação de token

Sintoma: Seu aplicativo gera um SecurityTokenDecryptionFailedException erro 401/500 ao processar tokens ou retorna um erro 401/500.

Causas comuns:

Chave privada não encontrada

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 – exporte novamente o certificado no .pfx formato e certifique-se de incluir a chave privada durante a exportação.
• Política de acesso do cofre de chaves — Ao usar o Azure Key Vault, verifique se a identidade do aplicativo tem a permissão para "Obter" em Certificados e Segredos. A chave privada é armazenada como um segredo em Key Vault.
• Certificate store permissions — No Windows, verifique se a identidade do pool de aplicativos ou a conta de serviço tem acesso de leitura à chave privada. Use a opção Gerenciar Chaves Privadas no snap-in MMC do repositório de certificados.

Incompatibilidade de algoritmo

Sintoma:SecurityTokenDecryptionFailedException com uma mensagem indicando um algoritmo sem suporte.

Causas e soluções:

• Tipo de chave não suportado — Microsoft Entra dá suporte a certificados RSA para criptografia de token. Verifique se o certificado usa um par de chaves RSA (não EC/ECDSA).
• Tamanho da chave muito pequeno – use um tamanho de chave de pelo menos 2.048 bits. Chaves RSA menores que 2048 bits podem ser rejeitadas.
• Algorithm sem suporte — Microsoft Entra usa RSA-OAEP para encapsulamento de chave. Verifique se o certificado e a infraestrutura do aplicativo dão suporte a esse algoritmo.

Tokens criptografados não estão sendo emitidos.

Sintoma: Seu aplicativo recebe tokens não criptografados mesmo que você tenha configurado a descriptografia de token.

Causas e soluções:

• tokenEncryptionKeyId não configurado – você deve definir explicitamente essa propriedade por meio de Microsoft Graph. Apenas carregar o certificado não é suficiente.
• Certificado expirado no registro do aplicativo – verifique se o certificado carregado no registro do aplicativo não expirou. Carregue um novo certificado, se necessário.
• Tokens de acesso não são criptografados – a criptografia de token se aplica somente a tokens de ID e tokens SAML . Os tokens de acesso de Microsoft Entra não são criptografados com seu certificado.

Comparar descriptografia de tokens e credenciais de clientes

As credenciais de descriptografia de token servem a uma finalidade diferente das credenciais do cliente. Seu aplicativo pode usar o mesmo certificado para ambos ou usar certificados separados.

O exemplo a seguir mostra uma configuração que usa o mesmo certificado Key Vault para autenticação e descriptografia de token:

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

Seguir as práticas recomendadas

Aplique essas recomendações ao implementar a descriptografia de token.

Use Azure Key Vault — armazene certificados de descriptografia em Key Vault para gerenciamento centralizado, controle de acesso e log de auditoria.

Planejar a rotação – sempre tenha uma estratégia de rotação antes de implantar a criptografia de token. Inclua os certificados novos e antigos durante a janela de rotação.

Use chaves RSA de 2048 bits ou maiores – verifique se seus certificados usam chaves RSA de pelo menos 2.048 bits para segurança adequada.

Monitor certificate expiration — Configure alertas no Azure Key Vault ou no sistema de monitoramento para notificá-lo antes que os certificados expirem.

Teste em um ambiente de teste – verifique a criptografia e descriptografia de token em um ambiente de teste antes de habilitá-la em produção.

Não armazene chaves privadas no controle do código-fonte — use Key Vault, variáveis de ambiente ou um gerenciador de segredos para armazenamento de certificados.

Não remova o certificado antigo muito cedo durante a rotação – mantenha ambos os certificados ativos por pelo menos 24 horas para permitir que os tokens armazenados em cache expirem.

Não habilite a criptografia de token sem um certificado de descriptografia configurado . Seu aplicativo falhará ao processar tokens se não puder descriptografá-los.

Conteúdo relacionado

• Visão geral das credenciais
• Visão geral do cache de token
• Autorização em APIs Web
• Credenciais de certificado