Użyj certyfikatów z Microsoft. Identity.Web

Microsoft.Identity.Web obsługuje uwierzytelnianie oparte na certyfikatach jako bezpieczną alternatywę dla tajnych danych klienta dla poufnych aplikacji klienckich. Certyfikaty używają kryptografii asymetrycznej, więc tylko właściciel klucza prywatnego może się uwierzytelnić.

W tym artykule skonfigurujesz poświadczenia certyfikatu z różnych źródeł, zarejestrujesz je w aplikacji i zarządzajesz nimi w środowisku produkcyjnym.

Dlaczego warto używać certyfikatów?

Czynnik	Tajemnica klienta	Certyfikat
Bezpieczeństwo	Wspólny sekret (symetryczny)	Para kluczy asymetrycznych
Rotacja	Wymaga ponownego wdrożenia aplikacji lub zmiany konfiguracji	Można zautomatyzować za pośrednictwem Key Vault
Ryzyko narażenia	Wpis tajny w konfiguracji może zostać ujawniony	Klucz prywatny pozostaje w bezpiecznym magazynie
Zgodność z przepisami	Może nie spełniać zasad przedsiębiorstwa	Spełnia większość wymagań dotyczących zabezpieczeń przedsiębiorstwa
Zalecane dla	Programowanie, tworzenie prototypów	Obciążenia produkcyjne

Ważna

Microsoft zaleca certyfikaty zamiast tajemnic klienta dla aplikacji produkcyjnych. Aby uzyskać najwyższy poziom zabezpieczeń, należy użyć uwierzytelniania bez certyfikatu (tożsamości zarządzanej lub federacji tożsamości obciążenia), gdy środowisko hostingu go obsługuje.

Jak to działa

Generujesz lub uzyskujesz certyfikat X.509 z kluczem prywatnym.
Zarejestrujesz klucz publiczny certyfikatu (lub odcisk palca) przy użyciu rejestracji aplikacji Microsoft Entra.
W czasie wykonywania Microsoft. Identity.Web ładuje certyfikat (w tym klucz prywatny) ze skonfigurowanego źródła.
Biblioteka używa klucza prywatnego do podpisania potwierdzenia klienta, które wysyła do Microsoft Entra ID w celu uzyskania tokenów.

Źródła certyfikatów

Microsoft. Usługa Identity.Web obsługuje ładowanie certyfikatów z wielu źródeł:

Typ źródła	wartość `SourceType`	Najbardziej odpowiedni dla
Azure Key Vault	`KeyVault`	Produkcja (zalecana)
Magazyn certyfikatów	`StoreWithThumbprint` lub `StoreWithDistinguishedName`	Windows serwerów lokalnych
Ścieżka pliku	`Path`	Tworzenie, konteneryzowane aplikacje
Ciąg zakodowany w formacie Base64	`Base64Encoded`	Sekrety Kubernetes, potoki CI/CD

Konfigurujesz poświadczenia certyfikatu w tablicy ClientCertificates w ramach swojej sekcji konfiguracji AzureAd (lub AzureAdB2C). Można określić wiele certyfikatów dla scenariuszy rotacji — Microsoft. Identity.Web używa pierwszego prawidłowego certyfikatu, który znajduje.

Z Azure Key Vault (zalecane)

Azure Key Vault jest zalecanym źródłem certyfikatów w środowisku produkcyjnym. Zapewnia scentralizowane zarządzanie, kontrolę dostępu, audytowanie i możliwości automatycznej rotacji.

Konfiguracja

Dodaj konfigurację certyfikatu do elementu 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"
      }
    ]
  }
}

Majątek	Opis
`SourceType`	Musi mieć wartość `"KeyVault"`.
`KeyVaultUrl`	Identyfikator URI Azure Key Vault (na przykład `https://myapp-kv.vault.azure.net`).
`KeyVaultCertificateName`	Nazwa certyfikatu przechowywana w Key Vault.

Konfigurowanie zasad dostępu Key Vault

Tożsamość Twojej aplikacji musi mieć uprawnienia do odczytu certyfikatów z Key Vault. Sposób udzielenia tego dostępu zależy od tego, czy używasz modelu zasad dostępu do skarbca, czy kontroli dostępu opartej na rolach Azure (RBAC).

Opcja 1: Zasady dostępu do sejfu

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

Uwaga / Notatka

Wymagane jest uprawnienie --secret-permissions get, ponieważ Azure Key Vault przechowuje klucz prywatny jako klucz tajny połączony z certyfikatem. Microsoft. Identity.Web musi mieć dostęp zarówno do certyfikatu, jak i jego klucza prywatnego.

Opcja 2: Azure RBAC

Przypisz rolę użytkownika certyfikatu Key Vault do tożsamości aplikacji:

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>

Uzyskiwanie dostępu do Key Vault przy użyciu tożsamości zarządzanej

Gdy aplikacja działa w usłudze Azure (App Service, Azure Functions, Azure Kubernetes Service, VM), użyj tożsamości zarządzanej do uwierzytelniania dla Key Vault. Eliminuje to konieczność uzyskiwania jakichkolwiek poświadczeń, aby uzyskać dostęp do samego skarbca.

Tożsamość zarządzana przypisana przez system

Jeśli aplikacja ma włączoną tożsamość zarządzaną przypisaną przez system, Microsoft.Identity.Web automatycznie używa DefaultAzureCredential do uwierzytelniania w Key Vault. Nie jest wymagana żadna dodatkowa konfiguracja poza wpisem ClientCertificates :

{
  "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"
      }
    ]
  }
}

Tożsamość zarządzana przypisana przez użytkownika

W przypadku tożsamości zarządzanej przypisanej przez użytkownika określ ManagedIdentityClientId w deskryptorze certyfikatu 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"
      }
    ]
  }
}

Wskazówka

W przypadku uruchamiania lokalnego podczas programowania DefaultAzureCredential wraca do poświadczeń Azure CLI lub Visual Studio. Upewnij się, że zalogowano się przy użyciu az login i że konto dewelopera ma odpowiednie uprawnienia Key Vault.

Z magazynu certyfikatów (tylko Windows)

W Windows można załadować certyfikaty z magazynu certyfikatów Windows. Jest to typowe w przypadku wdrożeń lokalnych lub hostowanych przez usługi IIS.

Przez odcisk palca

Użyj StoreWithThumbprint do zidentyfikowania certyfikatu na podstawie odcisku palca SHA-1.

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

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

Majątek	Opis
`SourceType`	Musi mieć wartość `"StoreWithThumbprint"`.
`CertificateStorePath`	Lokalizacja magazynu certyfikatów. Typowe wartości: `"CurrentUser/My"`, `"LocalMachine/My"`.
`CertificateThumbprint`	Odcisk palca SHA-1 certyfikatu (40 znaków szesnastkowych).

Według nazwy wyróżniającej

Użyj StoreWithDistinguishedName, aby zidentyfikować certyfikat według jego nazwy podmiotu:

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

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

Majątek	Opis
`SourceType`	Musi mieć wartość `"StoreWithDistinguishedName"`.
`CertificateStorePath`	Lokalizacja magazynu certyfikatów. Typowe wartości: `"CurrentUser/My"`, `"LocalMachine/My"`.
`CertificateDistinguishedName`	Nazwa wyróżniająca podmiotu certyfikatu (na przykład `"CN=MyAppCertificate"`).

Lokalizacje magazynu certyfikatów

W poniższej tabeli wymieniono typowe ścieżki magazynu certyfikatów i uprawnienia wymagane do uzyskania do nich dostępu:

Path	Opis	Wymagane uprawnienia
`CurrentUser/My`	Sklep osobisty bieżącego użytkownika	Dostęp na poziomie użytkownika
`LocalMachine/My`	Magazyn osobisty na poziomie całej maszyny	Dostęp administratora
`LocalMachine/Root`	Zaufane główne urzędy certyfikacji	Dostęp administratora
`CurrentUser/Root`	Zaufane główne urzędy certyfikacji bieżącego użytkownika	Dostęp na poziomie użytkownika

Uwaga / Notatka

W przypadku hostowania w usługach IIS tożsamość puli aplikacji musi mieć dostęp do odczytu do klucza prywatnego certyfikatu. Można to przyznać za pomocą opcji Zarządzaj kluczami prywatnymi w przystawce MMC do zarządzania certyfikatami.

Ze ścieżki pliku

Certyfikat można załadować bezpośrednio z .pfx pliku (PKCS#12) na dysku.

Ostrzeżenie

Przechowywanie plików certyfikatów na dysku z hasłami w konfiguracji nie jest zalecane w środowisku produkcyjnym. Użyj tego podejścia tylko w przypadku lokalnego programowania lub w środowiskach, w których system plików jest zabezpieczony (na przykład zainstalowane wpisy tajne w kontenerach).

Konfiguracja

Dodaj ścieżkę pliku certyfikatu i hasło do 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"
      }
    ]
  }
}

Majątek	Opis
`SourceType`	Musi mieć wartość `"Path"`.
`CertificateDiskPath`	Ścieżka bezwzględna lub względna do pliku `.pfx`.
`CertificatePassword`	Hasło do `.pfx` pliku. Jeśli certyfikat nie ma hasła, pomiń tę właściwość lub ustaw ją na pusty ciąg.

Wskazówka

Aby uniknąć przechowywania hasła w postaci zwykłego tekstu w appsettings.json, należy odwołać się do hasła ze zmiennej środowiskowej lub menedżera tajnych.

Za pomocą tajnych danych użytkownika .NET (rozwój):

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

Używanie zmiennej środowiskowej:

export AzureAd__ClientCertificates__0__CertificatePassword="your-password"

Z wartości zakodowanej w formacie Base64

Certyfikat można podać jako ciąg zakodowany w formacie Base64. Takie podejście jest przydatne przy wstrzykiwaniu certyfikatów przez zmienne środowiskowe, tajemnice Kubernetes lub zmienne potoku CI/CD.

Konfiguracja

Dodaj wartość certyfikatu zakodowanego w formacie Base64 do elementu appsettings.json:

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

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

Majątek	Opis
`SourceType`	Musi mieć wartość `"Base64Encoded"`.
`Base64EncodedValue`	Pełny certyfikat (w tym klucz prywatny) zakodowany jako ciąg Base64.

Generowanie wartości Base64

Przekonwertuj .pfx plik na ciąg 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

Używanie z sekretami Kubernetes

Zapisz certyfikat zakodowany w formacie Base64 w kluczu tajnym Kubernetes i zamapuj go na zmienną środowiskową:

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

Odwołaj się do wpisu tajnego we wdrożeniu:

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

Używanie w potokach ciągłej integracji/ciągłego wdrażania

W Azure DevOps lub GitHub Actions zapisz certyfikat zakodowany w formacie Base64 jako zmienną tajną, a następnie ustaw go jako zmienną środowiskową podczas wykonywania.

GitHub Actions example:

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

Azure DevOps przykład:

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

Ważna

Mimo że certyfikat jest zakodowany w formacie Base64, zawiera klucz prywatny i musi być traktowany jako wpis tajny. Zawsze używaj zmiennych tajnych w pipeline'ach CI/CD — nigdy nie zatwierdzaj certyfikatów zakodowanych w formacie Base64 do systemu kontroli wersji.

Konfigurowanie certyfikatów w kodzie języka C#

Oprócz konfiguracji JSON można programowo skonfigurować poświadczenia certyfikatu przy użyciu klasy CredentialDescription z Microsoft.Identity.Abstractions.

Metody pomocnicze

Klasa CredentialDescription udostępnia statyczne metody pomocnika dla każdego typu źródła certyfikatu:

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...");

Używanie w ASP.NET Core

Przekaż opisy poświadczeń bezpośrednio podczas konfigurowania uwierzytelniania:

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")
        };
    });

Wskazówka

Metody pomocnicze są równoważne ustawieniu właściwości obiektu CredentialDescription ręcznie. Zapewniają one bardziej zwięzłą składnię podczas konfigurowania poświadczeń w kodzie, a nie za pomocą metody appsettings.json.

Tworzenie certyfikatu z podpisem własnym na potrzeby programowania

W przypadku lokalnego programowania i testowania można utworzyć certyfikat z podpisem własnym. Nie używaj certyfikatów z podpisem własnym w środowisku produkcyjnym.

Korzystanie z programu PowerShell (Windows)

Uruchom następujące polecenia, aby utworzyć certyfikat z podpisem własnym, wyeksportować go i wyświetlić odcisk palca:

$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)"

Korzystanie z protokołu OpenSSL (międzyplatformowego)

Uruchom następujące polecenia, aby wygenerować certyfikat, spakować go jako .pfx plik i wyświetlić odcisk palca:

# 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

Korzystanie z interfejsu wiersza polecenia .NET

Wyeksportuj certyfikat HTTPS deweloperski jako plik .pfx.

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

Uwaga / Notatka

Polecenie dotnet dev-certs generuje certyfikat dewelopera HTTPS. Chociaż może być używany do testowania ładowania certyfikatów, jest przeznaczony głównie dla lokalnego protokołu HTTPS i może nie być odpowiedni dla wszystkich scenariuszy testowania uwierzytelniania.

Rejestrowanie certyfikatu w Microsoft Entra ID

Po utworzeniu lub uzyskaniu certyfikatu należy zarejestrować jego klucz publiczny przy użyciu rejestracji aplikacji w Microsoft Entra ID.

Korzystanie z portalu Azure

Przejdź do portalu Azure i przejdź do Microsoft Entra ID>Rejestracje aplikacji.
Wybierz aplikację.
Wybierz pozycję Certyfikaty i wpisy tajne>Certyfikaty>Przekaż certyfikat.
Przekaż plik .cer lub .pem zawierający tylko klucz publiczny. Nie przesyłaj pliku .pfx, który zawiera klucz prywatny.
Zanotuj wartość odcisku palca wyświetlaną po przekazaniu — może być konieczne jej skonfigurowanie.

Korzystanie z Azure CLI

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

Flaga --append dodaje certyfikat bez usuwania istniejących poświadczeń.

Korzystanie z programu 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)

Ważna

Tylko przekaż klucz publiczny (.cer lub .pem) do rejestracji aplikacji. Nigdy nie przekaż .pfx pliku, który zawiera klucz prywatny. Klucz prywatny musi pozostać bezpiecznie przechowywany i dostępny tylko dla aplikacji.

Rotacja certyfikatów

Rotacja certyfikatów zastępuje wygasający certyfikat nowym, zanim wygaśnie, zapewniając nieprzerwaną obsługę.

Strategia: nakładające się certyfikaty

Zalecane podejście używa nakładających się okresów ważności:

Wygeneruj nowy certyfikat przed wygaśnięciem bieżącego certyfikatu (na przykład 30–60 dni wcześniej).
Registerowanie nowego certyfikatu w rejestracji aplikacji Microsoft Entra obok istniejącego. Microsoft Entra ID akceptuje tokeny podpisane przez dowolny zarejestrowany certyfikat.
Wdróż nowy certyfikat do źródła certyfikatów aplikacji (Key Vault, magazynu certyfikatów itd.).
Zaktualizuj konfigurację (w razie potrzeby), aby wskazać nowy certyfikat.
Usuń stary certyfikat z rejestracji aplikacji po potwierdzeniu, że wszystkie instancje używają nowego.

Wiele certyfikatów w konfiguracji

Microsoft. Usługa Identity.Web obsługuje określanie wielu certyfikatów. Biblioteka testuje je po kolei i korzysta z pierwszego poprawnego certyfikatu.

{
  "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"
      }
    ]
  }
}

Automatyczna rotacja z Azure Key Vault

Azure Key Vault obsługuje automatyczne odnawianie certyfikatów. Po włączeniu automatycznego obracania:

Key Vault generuje nową wersję certyfikatu przed wygaśnięciem.
Microsoft. Usługa Identity.Web automatycznie pobiera najnowszą wersję (podczas następnego pobierania certyfikatu).
Stara wersja certyfikatu pozostaje prawidłowa, dopóki nie wygaśnie.

Aby skonfigurować automatyczne obracanie w Key Vault:

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

Wskazówka

W przypadku aplikacji z długotrwałymi procesami rozważ zaimplementowanie okresowego odświeżania certyfikatu. Microsoft. Identity.Web buforuje certyfikat w pamięci. Jeśli certyfikat jest obracany w Key Vault, aplikacja pobiera nowy certyfikat przy następnej konieczności utworzenia nowego poufnego klienta aplikacji MSAL.

Rozwiązywanie problemów z błędami certyfikatów

W tej sekcji wymieniono typowe komunikaty o błędach i ich rozwiązania.

Typowe błędy

Nie znaleziono certyfikatu

Komunikat o błędzie:

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

Możliwe przyczyny i rozwiązania:

Przyczyna	Rozwiązanie
Nieprawidłowy odcisk palca	Sprawdź, czy odcisk palca w konfiguracji jest zgodny z zainstalowanym certyfikatem. Usuń wszelkie ukryte znaki (spacje, niewidzialne znaki Unicode).
Nieprawidłowy magazyn certyfikatów	Potwierdź, że `CertificateStorePath` odpowiada miejscu, w którym certyfikat jest zainstalowany (`CurrentUser/My` vs `LocalMachine/My`).
Certyfikat nie jest zainstalowany	Zaimportuj certyfikat do odpowiedniego magazynu przy użyciu ( `certmgr.msc` CurrentUser) lub `certlm.msc` (LocalMachine).
niezgodność nazw Key Vault	Sprawdź `KeyVaultUrl` i `KeyVaultCertificateName` są poprawne.
Nie znaleziono pliku	Potwierdź, że `CertificateDiskPath` wskazuje istniejący `.pfx` plik, a aplikacja ma dostęp do odczytu.

Odmowa dostępu do Key Vault

Komunikat o błędzie:

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

Rozwiązania:

Sprawdź, czy zasady dostępu udzielają get uprawnień zarówno dla certyfikatów, jak i tajemnic.
W przypadku korzystania z kontroli dostępu opartej na rolach Azure upewnij się, że tożsamość ma rolę Key Vault Certificate User.
W przypadku tożsamości zarządzanej upewnij się, że tożsamość jest włączona, a prawidłowy identyfikator obiektu jest używany w zasadach.

Klucz prywatny certyfikatu jest niedostępny

Komunikat o błędzie:

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

Rozwiązania:

W Windows/IIS upewnij się, że tożsamość puli aplikacji ma read dostęp do klucza prywatnego. Użyj przystawki Certyfikaty MMC, aby udzielić dostępu za pośrednictwem Zarządzaj kluczami prywatnymi.
W systemie Linux sprawdź, czy .pfx plik ma odpowiednie uprawnienia do pliku (chmod 600).
Upewnij się, że certyfikat został wyeksportowany z kluczem prywatnym (Export-PfxCertificate lub openssl pkcs12 -export).

Certyfikat wygasł

Komunikat o błędzie:

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

Rozwiązania:

Sprawdź okres ważności certyfikatu: openssl x509 -in cert.pem -noout -dates.
Wygeneruj nowy certyfikat i zaktualizuj zarówno rejestrację aplikacji, jak i konfigurację aplikacji.
Zaimplementuj rotację certyfikatów, aby zapobiec przyszłym problemom z wygaśnięciem. Zobacz Rotacja certyfikatów.

Nieprawidłowe hasło certyfikatu

Komunikat o błędzie:

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

Rozwiązania:

Sprawdź, czy CertificatePassword jest zgodne z hasłem używanym podczas eksportowania .pfx pliku.
Jeśli używasz zmiennych środowiskowych, sprawdź, czy występują problemy z kodowaniem (końcowe znaki nowej linii, znaki specjalne).
Ponownie wyeksportuj certyfikat ze znanym hasłem.

Lista kontrolna diagnostyki

Użyj tej listy kontrolnej, gdy uwierzytelnianie certyfikatu nie działa:

[ ] Ważność certyfikatu — czy certyfikat jest w okresie ważności? Sprawdź daty NotBefore i NotAfter.
[ ] Rejestracja aplikacji — czy klucz publiczny certyfikatu jest przekazywany do właściwej rejestracji aplikacji?
[ ] Dopasowanie odcisku palca — czy odcisk palca w konfiguracji jest zgodny z certyfikatem w rejestracji aplikacji?
[ ] Dostęp do klucza prywatnego — czy proces aplikacji może odczytać klucz prywatny certyfikatu?
[ ] Uprawnienia Key Vault — Czy tożsamość ma oba uprawnienia w przypadku źródeł Key Vault: certificates/get i secrets/get?
[ ] Sekcja konfiguracji — czy konfiguracja certyfikatu jest w odpowiedniej sekcji (AzureAd lub AzureAdB2C)?
[ ] NuGet packages — Czy Microsoft.Identity.Web aktualne? Starsze wersje mogą nie obsługiwać niektórych typów źródeł certyfikatów.

Włącz rejestrowanie

Aby uzyskać szczegółowe informacje diagnostyczne, włącz logowanie MSAL.

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

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

Przejrzyj dzienniki komunikatów dotyczących ładowania certyfikatów, tworzenia asercji klienta i pozyskiwania tokenu.

Omówienie poświadczeń
Uwierzytelnianie bez certyfikatów — tożsamość zarządzana i federacja tożsamości obciążenia
Wpisy tajne klienta — alternatywny typ poświadczeń dla aplikacji poufnych
Odszyfrowywanie tokenów — używanie certyfikatów do odszyfrowywania tokenów
Rejestrowanie i diagnostyka

Opinia

Czy ta strona była pomocna?

Last updated on 2026-04-29

Użyj certyfikatów z Microsoft. Identity.Web

Dlaczego warto używać certyfikatów?

Jak to działa

Źródła certyfikatów

Z Azure Key Vault (zalecane)

Konfiguracja

Konfigurowanie zasad dostępu Key Vault

Opcja 1: Zasady dostępu do sejfu

Opcja 2: Azure RBAC

Uzyskiwanie dostępu do Key Vault przy użyciu tożsamości zarządzanej

Tożsamość zarządzana przypisana przez system

Tożsamość zarządzana przypisana przez użytkownika

Z magazynu certyfikatów (tylko Windows)

Przez odcisk palca

Według nazwy wyróżniającej

Lokalizacje magazynu certyfikatów

Ze ścieżki pliku

Konfiguracja

Z wartości zakodowanej w formacie Base64

Konfiguracja

Generowanie wartości Base64

Używanie z sekretami Kubernetes

Używanie w potokach ciągłej integracji/ciągłego wdrażania

Konfigurowanie certyfikatów w kodzie języka C#

Metody pomocnicze

Używanie w ASP.NET Core

Tworzenie certyfikatu z podpisem własnym na potrzeby programowania

Korzystanie z programu PowerShell (Windows)

Korzystanie z protokołu OpenSSL (międzyplatformowego)

Korzystanie z interfejsu wiersza polecenia .NET

Rejestrowanie certyfikatu w Microsoft Entra ID

Korzystanie z portalu Azure

Korzystanie z Azure CLI

Korzystanie z programu Microsoft Graph PowerShell

Rotacja certyfikatów

Strategia: nakładające się certyfikaty

Wiele certyfikatów w konfiguracji

Automatyczna rotacja z Azure Key Vault

Rozwiązywanie problemów z błędami certyfikatów

Typowe błędy

Nie znaleziono certyfikatu

Odmowa dostępu do Key Vault

Klucz prywatny certyfikatu jest niedostępny

Certyfikat wygasł

Nieprawidłowe hasło certyfikatu

Lista kontrolna diagnostyki

Włącz rejestrowanie

Treści powiązane

Opinia

Dodatkowe zasoby