Use certificados com Microsoft.Identity.Web

Microsoft. O Identity.Web dá suporte à autenticação baseada em certificado como uma alternativa segura aos segredos do cliente para aplicativos cliente confidenciais. Os certificados usam criptografia assimétrica, portanto, somente o titular da chave privada pode se autenticar.

Neste artigo, você configura as credenciais de certificado de várias fontes, registra-as em seu aplicativo e as gerencia em produção.

Por que usar certificados?

Como funciona

1. Você gera ou obtém um certificado X.509 com uma chave privada.
2. Registre a chave public key (ou impressão digital) do certificado com o registro do aplicativo Microsoft Entra.
3. Em tempo de execução, Microsoft.Identity.Web carrega o certificado (incluindo a chave privada) da fonte configurada.
4. A biblioteca usa a chave privada para assinar uma declaração de cliente, que ela envia para Microsoft Entra ID para obter tokens.

Fontes de certificado

Microsoft. O Identity.Web dá suporte ao carregamento de certificados de várias fontes:

Você configura as credenciais de certificado na matriz ClientCertificates dentro da sua AzureAd seção de configuração (ou AzureAdB2C). Você pode especificar vários certificados para cenários de rotação – Microsoft. Identity.Web usa o primeiro certificado válido encontrado.

De Azure Key Vault (recomendado)

Azure Key Vault é a origem recomendada para certificados em produção. Ele fornece recursos centralizados de gerenciamento, controle de acesso, auditoria e rotação automática.

Configuração

Adicione a configuração do certificado ao seu appsettings.json:

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

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

Configurar políticas de acesso Key Vault

A identidade do aplicativo deve ter permissão para ler certificados do Key Vault. A maneira como você concede isso depende de você usar o modelo de política de acesso do cofre ou o controle de acesso baseado em funções do Azure (RBAC).

Opção 1: política de acesso do cofre

az keyvault set-policy \
  --name your-keyvault-name \
  --object-id <app-or-managed-identity-object-id> \
  --certificate-permissions get list \
  --secret-permissions get

Opção 2: Azure RBAC

Atribua a função Key Vault Certificate User à identidade do aplicativo:

az role assignment create \
  --role "Key Vault Certificate User" \
  --assignee <app-or-managed-identity-object-id> \
  --scope /subscriptions/<sub-id>/resourceGroups/<rg>/providers/Microsoft.KeyVault/vaults/<vault-name>

Usar a Identidade Gerenciada para acessar Key Vault

Quando seu aplicativo é executado em Azure (Serviço de Aplicativo, Azure Functions, Serviço de Kubernetes do Azure, VMs), use a Identidade Gerenciada para autenticar para Key Vault. Isso elimina a necessidade de quaisquer credenciais para acessar o cofre em si.

Identidade Gerenciada atribuída pelo sistema

Se o aplicativo tiver uma Identidade Administrada atribuída pelo sistema habilitada, o Microsoft.Identity.Web usa DefaultAzureCredential automaticamente para se autenticar no Cofre de Chaves. Nenhuma configuração extra é necessária além da ClientCertificates entrada:

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

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

Identidade gerenciada atribuída ao usuário

Para uma Identidade Gerenciada atribuída pelo usuário, especifique o ManagedIdentityClientId no descritor de certificado Key Vault:

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

    "ClientCertificates": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://your-keyvault-name.vault.azure.net",
        "KeyVaultCertificateName": "your-certificate-name",
        "ManagedIdentityClientId": "user-assigned-managed-identity-client-id"
      }
    ]
  }
}

No repositório de certificados (somente Windows)

No Windows, você pode carregar certificados do repositório de certificados Windows. Isso é comum para implantações locais ou hospedadas no IIS.

Por impressão digital

Use StoreWithThumbprint para identificar o certificado por sua impressão digital SHA-1:

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

    "ClientCertificates": [
      {
        "SourceType": "StoreWithThumbprint",
        "CertificateStorePath": "CurrentUser/My",
        "CertificateThumbprint": "A1B2C3D4E5F6A1B2C3D4E5F6A1B2C3D4E5F6A1B2"
      }
    ]
  }
}

Por nome diferenciado

Use StoreWithDistinguishedName para identificar o certificado pelo nome da entidade:

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

    "ClientCertificates": [
      {
        "SourceType": "StoreWithDistinguishedName",
        "CertificateStorePath": "CurrentUser/My",
        "CertificateDistinguishedName": "CN=MyAppCertificate"
      }
    ]
  }
}

Locais do repositório de certificados

A tabela a seguir lista os caminhos comuns do repositório de certificados e as permissões necessárias para acessá-los:

Do caminho do arquivo

Você pode carregar um certificado diretamente de um .pfx arquivo (PKCS#12) em disco.

Configuração

Adicione o caminho do arquivo de certificado e a senha ao seu appsettings.json:

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

    "ClientCertificates": [
      {
        "SourceType": "Path",
        "CertificateDiskPath": "/path/to/certificate.pfx",
        "CertificatePassword": "your-certificate-password"
      }
    ]
  }
}

dotnet user-secrets set "AzureAd:ClientCertificates:0:CertificatePassword" "your-password"

export AzureAd__ClientCertificates__0__CertificatePassword="your-password"

Do valor codificado em Base64

Você pode fornecer o certificado como uma cadeia de caracteres codificada em Base64. Essa abordagem é útil quando você injeta certificados por meio de variáveis de ambiente, segredos do Kubernetes ou variáveis de pipeline de CI/CD.

Configuração

Adicione o valor do certificado codificado em Base64 ao seu appsettings.json:

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

    "ClientCertificates": [
      {
        "SourceType": "Base64Encoded",
        "Base64EncodedValue": "MIIKcQIBAzCCCi0GCSqGSIb3DQEHAaCCCh4Egg..."
      }
    ]
  }
}

Gerar o valor Base64

Converter um .pfx arquivo em uma cadeia de caracteres Base64:

PowerShell:

$certBytes = [System.IO.File]::ReadAllBytes("path/to/certificate.pfx")
$base64 = [System.Convert]::ToBase64String($certBytes)
$base64 | Set-Clipboard  # Copies to clipboard

Bash:

base64 -w 0 path/to/certificate.pfx

Uso com segredos do Kubernetes

Armazene o certificado codificado em Base64 em um segredo do Kubernetes e mapeie-o para uma variável de ambiente:

apiVersion: v1
kind: Secret
metadata:
  name: app-cert-secret
type: Opaque
data:
  AzureAd__ClientCertificates__0__Base64EncodedValue: <base64-encoded-pfx>

Faça referência ao segredo em sua implantação:

env:
  - name: AzureAd__ClientCertificates__0__SourceType
    value: "Base64Encoded"
  - name: AzureAd__ClientCertificates__0__Base64EncodedValue
    valueFrom:
      secretKeyRef:
        name: app-cert-secret
        key: AzureAd__ClientCertificates__0__Base64EncodedValue

Usar em pipelines de CI/CD

Em Azure DevOps ou GitHub Actions, armazene o certificado codificado em Base64 como uma variável secreta e, em seguida, defina-o como uma variável de ambiente em runtime.

Exemplo de GitHub Actions:

env:
  AzureAd__ClientCertificates__0__SourceType: "Base64Encoded"
  AzureAd__ClientCertificates__0__Base64EncodedValue: ${{ secrets.APP_CERTIFICATE_BASE64 }}

Azure DevOps exemplo:

variables:
  AzureAd__ClientCertificates__0__SourceType: "Base64Encoded"
  AzureAd__ClientCertificates__0__Base64EncodedValue: $(AppCertificateBase64)

Configurar certificados no código C#

Além da configuração JSON, você pode configurar credenciais de certificado programaticamente usando a classe CredentialDescription de Microsoft.Identity.Abstractions.

Métodos auxiliares

A CredentialDescription classe fornece métodos auxiliares estáticos para cada tipo de origem de certificado:

using Microsoft.Identity.Abstractions;

// From Azure Key Vault
var kvCredential = CredentialDescription.FromKeyVault(
    "https://your-keyvault-name.vault.azure.net",
    "your-certificate-name");

// From certificate store (by thumbprint)
var thumbprintCredential = CredentialDescription.FromCertificateStore(
    "CurrentUser/My",
    thumbprint: "A1B2C3D4E5F6A1B2C3D4E5F6A1B2C3D4E5F6A1B2");

// From certificate store (by distinguished name)
var dnCredential = CredentialDescription.FromCertificateStore(
    "CurrentUser/My",
    distinguishedName: "CN=MyAppCertificate");

// From file path
var pathCredential = CredentialDescription.FromCertificatePath(
    "/path/to/certificate.pfx",
    "your-certificate-password");

// From Base64-encoded string
var base64Credential = CredentialDescription.FromBase64String(
    "MIIKcQIBAzCCCi0GCSqGSIb3DQEHAaCCCh4Egg...");

Utilizar no ASP.NET Core

Passe as descrições de credencial diretamente ao configurar a autenticação:

builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApp(options =>
    {
        options.Instance = "https://login.microsoftonline.com/";
        options.TenantId = "your-tenant-id";
        options.ClientId = "your-client-id";
        options.ClientCredentials = new[]
        {
            CredentialDescription.FromKeyVault(
                "https://your-keyvault-name.vault.azure.net",
                "your-certificate-name")
        };
    });

Criar um certificado autoassinado para desenvolvimento

Para desenvolvimento e teste local, você pode criar um certificado autoassinado. Não use certificados autoassinados em produção.

Usando o PowerShell (Windows)

Execute os seguintes comandos para criar um certificado autoassinado, exportá-lo e exibir a impressão digital:

$cert = New-SelfSignedCertificate `
  -Subject "CN=MyDevCertificate" `
  -CertStoreLocation "Cert:\CurrentUser\My" `
  -KeyExportPolicy Exportable `
  -KeySpec Signature `
  -KeyLength 2048 `
  -KeyAlgorithm RSA `
  -HashAlgorithm SHA256 `
  -NotAfter (Get-Date).AddYears(2)

# Export the .pfx file (with private key)
$password = ConvertTo-SecureString -String "YourPassword123!" -Force -AsPlainText
Export-PfxCertificate -Cert $cert -FilePath ".\MyDevCertificate.pfx" -Password $password

# Export the .cer file (public key only — for app registration)
Export-Certificate -Cert $cert -FilePath ".\MyDevCertificate.cer"

# Display the thumbprint
Write-Host "Thumbprint: $($cert.Thumbprint)"

Usando o OpenSSL (multiplataforma)

Execute os seguintes comandos para gerar um certificado, empacotá-lo como um .pfx arquivo e exibir a impressão digital:

# Generate a self-signed certificate and private key
openssl req -x509 -newkey rsa:2048 \
  -keyout key.pem -out cert.pem \
  -days 730 -nodes \
  -subj "/CN=MyDevCertificate"

# Package into a .pfx file
openssl pkcs12 -export \
  -out MyDevCertificate.pfx \
  -inkey key.pem -in cert.pem \
  -passout pass:YourPassword123!

# Get the thumbprint
openssl x509 -in cert.pem -noout -fingerprint -sha1

Usando .NET CLI

Exportar um certificado HTTPS de desenvolvimento como um .pfx arquivo:

dotnet dev-certs https --export-path ./MyDevCertificate.pfx --password YourPassword123!

Registrar o certificado no Microsoft Entra ID

Depois de criar ou obter um certificado, você deve registrar sua chave pública com o registro do aplicativo no Microsoft Entra ID.

Usando o portal Azure

1. Acesse o portal Azure e navegue até Microsoft Entra ID>Registros de aplicativo.
2. Selecione seu aplicativo.
3. Selecione Certificados e segredos>Certificados>Carregar certificado.
4. Carregue o arquivo .cer ou .pem que contém apenas a chave pública. Não carregue o .pfx arquivo, que contém a chave privada.
5. Observe o valor de Thumbprint exibido após o upload — você pode precisar dele para a configuração.

Usando CLI do Azure

az ad app credential reset \
  --id <application-client-id> \
  --cert @/path/to/certificate.pem \
  --append

O --append sinalizador adiciona o certificado sem remover as credenciais existentes.

Usando Microsoft Graph PowerShell

$certData = [System.IO.File]::ReadAllBytes(".\MyDevCertificate.cer")
$base64Cert = [System.Convert]::ToBase64String($certData)

$keyCredential = @{
    type = "AsymmetricX509Cert"
    usage = "Verify"
    key = [System.Convert]::FromBase64String($base64Cert)
    displayName = "MyAppCertificate"
}

Update-MgApplication -ApplicationId <app-object-id> -KeyCredentials @($keyCredential)

Rotação de certificados

A rotação de certificado substitui um certificado expirando por um novo antes de expirar, garantindo o serviço ininterrupto.

Estratégia: Sobreposição de certificados

A abordagem recomendada usa períodos de validade sobrepostos:

1. Gere um novo certificado antes que o atual expire (por exemplo, de 30 a 60 dias de antecedência).
2. Register o novo certificado no registro do aplicativo Microsoft Entra junto com o existente. Microsoft Entra ID aceita tokens assinados por qualquer certificado registrado.
3. Implante o novo certificado na fonte de certificados do seu aplicativo (Cofre de Chaves, armazenamento de certificados, etc.).
4. Atualize a configuração (se necessário) para apontar para o novo certificado.
5. Remova o certificado antigo do registro do aplicativo depois de confirmar que todas as instâncias usam o novo.

Vários certificados na configuração

Microsoft. O Identity.Web dá suporte à especificação de vários certificados. A biblioteca testa-os em sequência e usa o primeiro certificado válido:

{
  "AzureAd": {
    "ClientCertificates": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://your-keyvault.vault.azure.net",
        "KeyVaultCertificateName": "new-cert-2026"
      },
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://your-keyvault.vault.azure.net",
        "KeyVaultCertificateName": "current-cert-2025"
      }
    ]
  }
}

Rotação automática com Azure Key Vault

Azure Key Vault dá suporte à renovação automática do certificado. Quando você habilita a rotação automática:

1. Key Vault gera uma nova versão de certificado antes da expiração.
2. Microsoft. Identity.Web pega a versão mais recente automaticamente (na próxima busca de certificado).
3. A versão do certificado antigo permanece válida até expirar.

Para configurar a rotação automática no Key Vault:

az keyvault certificate set-attributes \
  --vault-name your-keyvault-name \
  --name your-certificate-name \
  --policy @rotation-policy.json

Solucionar erros de certificado

Esta seção lista mensagens de erro comuns e suas soluções.

Erros comuns

Certificado não encontrado

Mensagem de erro:

System.Security.Cryptography.CryptographicException: The certificate cannot be found.

Possíveis causas e soluções:

Acesso negado ao Key Vault

Mensagem de erro:

Azure.RequestFailedException: The user, group or application '...' does not have certificates get permission on key vault '...'

Soluções:

• Verifique se as políticas de acesso concedem get permissão para certificados e segredos.
• Se estiver usando Azure RBAC, verifique se a identidade tem a função Key Vault Certificate User.
• Para Identidade Gerenciada, confirme se a identidade está habilitada e se a ID de objeto correta é usada na política.

Chave privada de certificado não acessível

Mensagem de erro:

System.Security.Cryptography.CryptographicException: Keyset does not exist.

Soluções:

• No Windows/IIS, verifique se a identidade do pool de aplicativos possui permissão de leitura à chave privada. Use o snap-in MMC de certificados para conceder acesso através de Gerenciar Chaves Privadas.
• No Linux, verifique se o .pfx arquivo tem permissões de arquivo apropriadas (chmod 600).
• Verifique se o certificado foi exportado com a chave privada (Export-PfxCertificate ou openssl pkcs12 -export).

Certificado expirado

Mensagem de erro:

AADSTS700027: Client assertion contains an invalid signature. The key was expired.

Soluções:

• Verifique o período de validade do certificado: openssl x509 -in cert.pem -noout -dates.
• Gere um novo certificado e atualize o registro do aplicativo e a configuração do aplicativo.
• Implemente a rotação de certificados para evitar problemas futuros de expiração. Consulte a rotação de certificados.

Senha de certificado incorreta

Mensagem de erro:

System.Security.Cryptography.CryptographicException: The specified network password is not correct.

Soluções:

• Verifique se CertificatePassword corresponde à senha usada ao exportar o .pfx arquivo.
• Se estiver usando variáveis de ambiente, verifique se há problemas de codificação, como novas linhas ao final e caracteres especiais.
• Exporte novamente o certificado com uma senha conhecida.

Lista de verificação de diagnóstico

Use esta lista de verificação quando a autenticação de certificado não estiver funcionando:

• [ ] Validade do certificado — O certificado está dentro do período de validade? Verifique as datas NotBefore e NotAfter.
• [ ] Registro de aplicativo — A chave pública do certificado é carregada no registro correto do aplicativo?
• [ ] Correspondência de impressão digital – A impressão digital em sua configuração corresponde ao certificado no registro do aplicativo?
• [ ] Acesso à chave privada — O processo do aplicativo pode ler a chave privada do certificado?
• [ ] Permissões do Key Vault — Para fontes do Key Vault, a identidade tem permissões certificates/get e secrets/get?
• [ ] Seção de configuração — A configuração do certificado está na seção correta (AzureAd ou AzureAdB2C)?
• [ ] NuGet packages — Microsoft.Identity.Web está atualizado? Versões mais antigas podem não ter suporte para determinados tipos de origem de certificado.

Habilitar registro de log

Para obter informações detalhadas de diagnóstico, habilite o log do MSAL.

builder.Services.AddMicrosoftIdentityWebAppAuthentication(builder.Configuration, "AzureAd")
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddInMemoryTokenCaches();

builder.Logging.AddFilter("Microsoft.Identity", LogLevel.Debug);

Examine os logs para obter mensagens sobre carregamento de certificado, criação de declaração de cliente e aquisição de token.

Conteúdo relacionado

• Visão geral das credenciais
• Autenticação sem certificado – Federação de Identidade Gerenciada e Identidade de Carga de Trabalho
• Segredos do cliente – tipo de credencial alternativa para aplicativos confidenciais
• Descriptografia de token – usando certificados para descriptografia de token
• Log e diagnóstico