Use certificados com Microsoft.Identity.Web

Microsoft. O Identity.Web suporta autenticação baseada em certificados como alternativa segura aos segredos do cliente para aplicações confidenciais do cliente. Os certificados utilizam criptografia assimétrica, pelo que apenas o detentor da chave privada pode autenticar.

Neste artigo, configura credenciais de certificados de várias fontes, regista-as na sua aplicação e gere-as em produção.

Por que usar certificados?

Como funciona

1. Gera ou obtém um certificado X.509 com uma chave privada.
2. Registe a chave pública (ou impressão digital) do certificado junto com o registo da tua aplicação de Microsoft Entra.
3. Durante a execução, o Microsoft.Identity.Web carrega o certificado (incluindo a chave privada) da fonte configurada.
4. A biblioteca utiliza a chave privada para assinar uma declaração do cliente, que é enviada para o Microsoft Entra ID para obter tokens.

Fontes de certificados

Microsoft. O Identity.Web suporta o carregamento de certificados de múltiplas fontes:

Configura as credenciais de certificado no ClientCertificates array dentro da sua AzureAd (ou AzureAdB2C) secção de configuração. Pode especificar múltiplos certificados para cenários de rotação — Microsoft. O Identity.Web utiliza o primeiro certificado válido que encontra.

From Azure Key Vault (recomendado)

Azure Key Vault é a fonte recomendada para certificados em produção. Proporciona gestão centralizada, controlo de acessos, auditoria e capacidades de 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 ao Key Vault

A identidade da sua aplicação deve ter permissão para ler certificados do Key Vault. Como concede este acesso dependerá de se utiliza o modelo de política de acesso ao cofre ou o controlo de acesso baseado em funções do Azure (RBAC).

Opção 1: Política de acesso ao 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 o papel Key Vault Certificate User à identidade da sua aplicação:

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>

Utilize uma Identidade Gerida para aceder ao Key Vault

Quando a sua aplicação estiver em execução no Azure (App Service, Funções do Azure, Azure Kubernetes Service, VMs), utilize a Identidade Gerida para efetuar a autenticação no Key Vault. Isto elimina a necessidade de quaisquer credenciais para aceder ao cofre.

Identidade Gerida Atribuída ao Sistema

Se a sua aplicação tiver uma Identidade Gerida atribuída ao sistema ativada, o Microsoft.Identity.Web utiliza automaticamente DefaultAzureCredential para autenticar no Key Vault. Não é necessária nenhuma configuração adicional para 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 pelo usuário

Para uma Identidade Gerida atribuída pelo utilizador, especifique o ManagedIdentityClientId no descritor do 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"
      }
    ]
  }
}

Da loja de certificados (apenas no Windows)

No Windows, pode carregar certificados a partir da Loja de Certificados do Windows. Isto é comum para implementações on-premises ou alojadas por IIS.

Por impressão digital

Use StoreWithThumbprint para identificar o certificado pela 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 distinto

Use StoreWithDistinguishedName para identificar o certificado pelo nome do assunto:

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

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

Localizações de lojas de certificados

A tabela seguinte lista caminhos comuns de armazenamento de certificados e as permissões necessárias para aceder a eles:

A partir do caminho do ficheiro

Pode carregar um certificado diretamente a partir de um .pfx ficheiro (PKCS#12) no disco.

Configuração

Adicione o caminho do ficheiro de certificado e a palavra-passe 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"

A partir do valor codificado em Base64

Pode fornecer o certificado como uma cadeia codificada em Base64. Esta abordagem é útil ao injetar certificados através 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 ficheiro para uma cadeia 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 num segredo 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 na sua implementaçã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

Utilização em pipelines CI/CD

No Azure DevOps ou GitHub Actions, armazena o certificado codificado em Base64 como variável secreta e depois define-o como variável de ambiente em tempo de execução.

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 em código C#

Além da configuração JSON, pode configurar credenciais de certificado de forma programática usando a classe CredentialDescription da Microsoft.Identity.Abstractions.

Métodos auxiliares

A CredentialDescription classe fornece métodos auxiliares estáticos para cada tipo de fonte 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...");

Utilização no ASP.NET Core

Passe diretamente as descrições das credenciais 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")
        };
    });

Crie um certificado auto-assinado para desenvolvimento

Para desenvolvimento e testes locais, pode criar um certificado auto-assinado. Não uses certificados autoassinados na produção.

Utilização do PowerShell (Windows)

Execute os seguintes comandos para criar um certificado auto-assinado, exportá-lo e mostrar 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)"

Utilização do OpenSSL (multiplataforma)

Execute os seguintes comandos para gerar um certificado, empacote-o como ficheiro .pfx e mostre 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

Utilizar a CLI do .NET

Exporte um certificado HTTPS de desenvolvimento como ficheiro .pfx :

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

Registe o certificado no Microsoft Entra ID

Depois de criar ou obter um certificado, deve registar a sua chave pública com o registo da sua aplicação no Microsoft Entra ID.

Usando o portal Azure

1. Vá ao portal Azure e navegue até Microsoft Entra ID>Registos de aplicações.
2. Selecione a sua candidatura.
3. Selecione Certificados & segredos>>
4. Carregue o ficheiro .cer ou .pem que contenha apenas a chave pública. Não carregue o .pfx ficheiro que contém a chave privada.
5. Note o valor da impressão digital apresentado após o upload — pode ser necessário para a configuração.

Usar CLI do Azure

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

A --append bandeira adiciona o certificado sem remover credenciais existentes.

Utilização do 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 certificados substitui um certificado a expirar por um novo antes de este expirar, garantindo um serviço ininterrupto.

Estratégia: Certificados sobrepostos

A abordagem recomendada utiliza períodos de validade sobrepostos:

1. Gerar um novo certificado antes do atual expirar (por exemplo, com 30 a 60 dias de antecedência).
2. Regista o novo certificado no registo da tua aplicação de Microsoft Entra juntamente com o existente. O Microsoft Entra ID aceita tokens assinados por qualquer certificado registado.
3. Implementa o novo certificado na fonte do certificado da tua aplicação (Key Vault, armazenamento de certificados, etc.).
4. Atualize a configuração (se necessário) para apontar para o novo certificado.
5. Remova o certificado antigo do registo da aplicação depois de confirmar que todas as instâncias usam o novo.

Múltiplos certificados em configuração

Microsoft. O Identity.Web suporta a especificação de múltiplos certificados. A biblioteca testa-os por ordem e utiliza 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 suporta renovação automática de certificados. Quando ativas a rotação automática:

1. O Key Vault gera uma nova versão do certificado antes da expiração.
2. Microsoft. O Identity.Web detecta automaticamente a versão mais recente (na próxima busca do certificado).
3. A versão antiga do certificado mantém-se 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

Resolver problemas de erros de certificado

Esta secção lista mensagens de erro comuns e as 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:

• As políticas de verificação de acesso concedem get permissão tanto para certificados como para segredos.
• Se usar Azure RBAC, certifique-se de que a identidade tem o papel Utilizador de Certificado do Key Vault.
• Para a Identidade Gerida, confirme que a identidade está ativada e que o ID correto do objeto é usado na política.

Chave privada do certificado não acessível

Mensagem de erro:

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

Soluções:

• No Windows/IIS, certifique-se de que a identidade do pool de aplicações tem acesso read à chave privada. Use a consola de gestão MMC de Certificados para conceder acesso usando Gerir Chaves Privadas.
• No Linux, verifique se o .pfx ficheiro tem permissões apropriadas (chmod 600).
• Certifique-se de que 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 tanto o registo da aplicação como a configuração da sua aplicação.
• Implemente a rotação de certificados para evitar futuros problemas de expiração. Consulte rotação de certificados.

Palavra-passe errada do certificado

Mensagem de erro:

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

Soluções:

• Verifique se CertificatePassword coincide com a palavra-passe usada quando exportar o ficheiro .pfx.
• Se usares variáveis de ambiente, verifica se há problemas de codificação (linhas novas, caracteres especiais).
• Reexporte o certificado com uma palavra-passe conhecida.

Lista de verificação diagnóstica

Use esta lista de verificação quando a autenticação de certificados não estiver a funcionar:

• [ ] Validade do certificado — O certificado está dentro do seu período de validade? Verifica as datas NotBefore e NotAfter.
• [ ] Registo da aplicação — A chave pública do certificado é carregada para o registo correto da aplicação?
• [ ] A impressão digital corresponde — A impressão digital na sua configuração corresponde ao certificado no registo da aplicação?
• [ ] Acesso à chave privada — O processo de candidatura pode ler a chave privada do certificado?
• [ ] Permissões de Key Vault — Para fontes de Key Vault, a identidade tem tanto as permissões certificates/get como secrets/get?
• [ ] Secção de configuração — A configuração do certificado está sob a secção correta (AzureAd ou AzureAdB2C)?
• [ ] NuGet packages — O Microsoft.Identity.Web está atualizado? Versões mais antigas podem não suportar certos tipos de código-fonte de certificados.

Ativar registo de logs

Para obter informações de diagnóstico detalhadas, ative o registo MSAL:

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

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

Revise os registos para mensagens sobre carregamento de certificados, criação de asserções de clientes e aquisição de tokens.

Conteúdo relacionado

• Visão geral das credenciais
• Autenticação sem certificado — Federação de Identidade Gerida e Identidade de Carga de Trabalho
• Segredos do cliente — tipo alternativo de credencial para aplicações confidenciais
• Desencriptação de tokens — utilização de certificados para desencriptação de tokens
• Registo e diagnóstico