Overzicht van referenties voor Microsoft.Identity.Web

Wanneer uw toepassing wordt geverifieerd met de Microsoft identity platform, wordt er een referentie weergegeven om de identiteit te bewijzen. Microsoft. Identity.Web ondersteunt verschillende referentietypen, die elk geschikt zijn voor verschillende omgevingen en beveiligingsvereisten.

In dit artikel krijgt u inzicht in de beschikbare referentietypen, kiest u de juiste referentie voor uw scenario en configureert u referenties in uw toepassing.

Waarom referentiekeuze belangrijk is

De referentie die uw toepassing gebruikt, is rechtstreeks van invloed op de beveiligingspostuur, operationele overhead en implementatieflexibiliteit. Een slecht gekozen referentie kan geheimen beschikbaar maken, handmatige rotatie vereisen of limiet vereisen waar uw toepassing kan worden uitgevoerd.

Microsoft. Identity.Web biedt een geïntegreerd configuratiemodel waarmee u het volgende kunt doen:

• Geef meerdere inloggegevens op met automatische fallback-methode.
• Wijzig referentietypen zonder toepassingscode te wijzigen.
• Gebruik verschillende referenties per omgeving (ontwikkeling, fasering, productie).

Ondersteunde referentietypen

Microsoft. Identity.Web ondersteunt drie categorieën referenties voor vertrouwelijke clienttoepassingen:

Referenties zonder certificaat (federatieve identiteitsreferenties + beheerde identiteit)

Certificaatloze referenties maken gebruik van Azure Managed Identity in combinatie met FIC (Federated Identity Credentials) om uw toepassing te verifiëren zonder geheimen of certificaten te beheren. Azure beheert de levenscyclus van referenties volledig.

Hoe het werkt: Uw toepassing gebruikt de beheerde identiteit om een token te verkrijgen dat de Microsoft identity platform accepteert als bewijs van de identiteit van de toepassing via een vooraf geconfigureerde federatieve vertrouwensrelatie.

Best voor: Productieworkloads die worden uitgevoerd op Azure.

Meer informatie over verificatie zonder certificaat

Certificaten

Certificaten bieden sterke, asymmetrische verificatie op basis van sleutels. Uw toepassing bewijst zijn identiteit door een verklaring te ondertekenen met de privésleutel van het certificaat. Microsoft. Identity.Web kan certificaten uit meerdere bronnen laden:

• Azure Key Vault - Gecentraliseerde, beheerde certificaatopslag met toegangsbeleid.
• Certificate Store - Windows certificatenopslag (CurrentUser of LocalMachine).
• Bestandspad - Certificaatbestand op schijf (.pfx-indeling).
• Base64-gecodeerd : certificaat dat rechtstreeks in de configuratie is ingesloten.

Geschikt voor: Productieworkloads waarbij certificaatloze referenties niet beschikbaar zijn of hybride omgevingen.

Meer informatie over certificaatreferenties

Clientgeheimen

Clientgeheimen worden gedeelde tekenreeksen die uw toepassing aan de Microsoft identity platform presenteert. Ze zijn het eenvoudigste referentietype om te configureren, maar bieden de zwakste beveiliging.

Geschikt voor: Alleen lokale ontwikkeling en testen.

Meer informatie over clientgeheimen

Het juiste type aanmeldgegevens kiezen

Gebruik de volgende beslissingsstructuur om te bepalen welk referentietype geschikt is voor uw scenario.

Is your application running on Azure?
├── Yes
│   ├── Can you use Managed Identity?
│   │   ├── Yes → Use certificateless credentials (recommended)
│   │   └── No → Use certificates from Azure Key Vault
└── No
    ├── Is this a production environment?
    │   ├── Yes → Use certificates (Key Vault, Certificate Store, or file path)
    │   └── No → Use client secrets for development/testing

Algemene richtlijnen

Volg deze principes bij het selecteren van een referentietype:

• Geef altijd de voorkeur aan certificaatloze referenties wanneer uw toepassing op Azure wordt uitgevoerd. Ze elimineren referentiebeheer volledig.
• Gebruik certificaten wanneer certificaatloze referenties niet beschikbaar zijn. Sla ze waar mogelijk op in Azure Key Vault.
• Beperk clientgeheimen tot ontwikkelomgevingen. Gebruik nooit clientgeheimen in productie-implementaties.

Referentietypen vergelijken

De volgende tabel bevat een overzicht van de belangrijkste verschillen tussen referentietypen:

Aanmeldgegevens configureren in appsettings.json

Microsoft. Identity.Web maakt gebruik van een ClientCredentials matrix in uw configuratie om een of meer referenties op te geven. Elke vermelding in de matrix bevat een SourceType eigenschap die aangeeft waar de referentie vandaan komt.

Configuratiestructuur

In het volgende voorbeeld ziet u een minimale configuratie met één certificaatloze referentie:

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

    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity",
        "ManagedIdentityClientId": "user-assigned-managed-identity-client-id"
      }
    ]
  }
}

SourceType-waarden

De eigenschap SourceType komt overeen met de enum CredentialSource en bepaalt hoe Microsoft. Identity.Web laadt de referentie:

Referentievoorbeelden per type

In de volgende voorbeelden ziet u hoe u elk type referentie in appsettings.json kunt configureren en, indien beschikbaar, in C#-code.

Certificaatloos (beheerde identiteit)

Gebruik een door de gebruiker toegewezen beheerde identiteit door de client-id op te geven:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity",
        "ManagedIdentityClientId": "user-assigned-managed-identity-client-id"
      }
    ]
  }
}

Laat de ManagedIdentityClientId eigenschap weg voor door het systeem toegewezen beheerde identiteit:

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity"
      }
    ]
  }
}

Certificaat van Azure Key Vault

Laad een certificaat dat is opgeslagen in Azure Key Vault door de kluis-URL en certificaatnaam op te geven:

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

U kunt ook de CredentialDescription helpermethode gebruiken in C#:

var credential = CredentialDescription.FromKeyVault(
    "https://your-keyvault.vault.azure.net",
    "your-certificate-name");

Certificaat uit certificaatarchief

Laad een certificaat uit het Windows certificaatarchief met vingerafdruk:

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "StoreWithThumbprint",
        "CertificateThumbprint": "ABC123DEF456...",
        "CertificateStorePath": "CurrentUser/My"
      }
    ]
  }
}

U kunt ook een onderscheidende naam (DN) gebruiken, wat certificaatrotatie vereenvoudigt omdat het nieuwe certificaat automatisch wordt geselecteerd:

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "StoreWithDistinguishedName",
        "CertificateDistinguishedName": "CN=YourAppCertificate",
        "CertificateStorePath": "CurrentUser/My"
      }
    ]
  }
}

Gebruik in C# de helpermethode:

// By thumbprint
var credential = CredentialDescription.FromCertificateStore(
    "CurrentUser/My",
    thumbprint: "ABC123DEF456...");

// By distinguished name (recommended for rotation)
var credential = CredentialDescription.FromCertificateStore(
    "CurrentUser/My",
    distinguishedName: "CN=YourAppCertificate");

Certificaat uit bestandspad

Een certificaat laden vanuit een .pfx bestand op schijf:

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "Path",
        "CertificateDiskPath": "/var/certs/app-cert.pfx",
        "CertificatePassword": "certificate-password"
      }
    ]
  }
}

Met Base64 gecodeerd certificaat

Sluit een certificaat rechtstreeks in de configuratie in als een met Base64 gecodeerde tekenreeks:

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "Base64Encoded",
        "Base64EncodedValue": "MIIKcQIBAzCCCi0..."
      }
    ]
  }
}

Clientgeheim

Geef een client-secret tekenreeks op voor ontwikkeling en testen:

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "ClientSecret",
        "ClientSecret": "your-client-secret"
      }
    ]
  }
}

Meerdere referenties gebruiken met noodoplossing

U kunt meerdere referenties opgeven in de ClientCredentials matrix. Microsoft. Identity.Web probeert elke referentie in de juiste volgorde en valt terug naar de volgende referentie als de huidige mislukt. Dit patroon is handig voor toepassingen die in meerdere omgevingen worden uitgevoerd.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity",
        "ManagedIdentityClientId": "your-managed-identity-client-id"
      },
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://your-keyvault.vault.azure.net",
        "KeyVaultCertificateName": "your-certificate-name"
      },
      {
        "SourceType": "ClientSecret",
        "ClientSecret": "development-only-secret"
      }
    ]
  }
}

In dit voorbeeld:

1. De toepassing probeert eerst certificaatloze verificatie met beheerde identiteit (werkt op Azure).
2. Als beheerde identiteit niet beschikbaar is, valt deze terug op een certificaat van Key Vault.
3. Als laatste redmiddel gebruikt het een clientgeheim (voor lokale ontwikkeling).

Met deze methode kunt u hetzelfde configuratiebestand gebruiken in omgevingen zonder codewijzigingen.

Inloggegevens configureren in code

U kunt referenties ook programmatisch configureren in Program.cs of Startup.cs:

using Microsoft.Identity.Web;

builder.Services.AddMicrosoftIdentityWebAppAuthentication(builder.Configuration, "AzureAd")
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddDownstreamApi("MyApi", builder.Configuration.GetSection("MyApi"))
    .AddDistributedTokenCaches();

// Or configure credentials programmatically
builder.Services.Configure<MicrosoftIdentityOptions>(options =>
{
    options.ClientCredentials = new[]
    {
        new CredentialDescription
        {
            SourceType = CredentialSource.SignedAssertionFromManagedIdentity,
            ManagedIdentityClientId = "your-managed-identity-client-id"
        }
    };
});

Tokenontsleutelingsreferenties

Naast clientreferenties voor verificatie Microsoft. Identity.Web ondersteunt ook referenties voor tokenontsleuteling. Gebruik tokenontsleutelingsreferenties wanneer uw toepassing versleutelde tokens ontvangt en deze moet ontsleutelen.

Tokenontsleutelingsreferenties gebruiken dezelfde SourceType waarden en configuratiepatronen als clientreferenties, maar worden opgegeven in de TokenDecryptionCredentials matrix:

{
  "AzureAd": {
    "TokenDecryptionCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://your-keyvault.vault.azure.net",
        "KeyVaultCertificateName": "token-decryption-cert"
      }
    ]
  }
}

Meer informatie over tokenontsleuteling

Beste praktijken

Houd rekening met deze aanbevelingen bij het configureren van referenties voor uw toepassing:

Geef de voorkeur aan certificaatloze referenties in productie. Ze elimineren risico's voor geheime blootstelling en verwijderen rotatieoverhead. Gebruik deze wanneer uw toepassing wordt uitgevoerd op Azure rekenresources die beheerde identiteit ondersteunen.

Gebruik referentievalval voor draagbaarheid. Configureer meerdere referenties in prioriteitsvolgorde, zodat uw toepassing werkt in ontwikkeling, fasering en productie zonder codewijzigingen.

Gebruik nooit clientgeheimen in productie. Clientgeheimen kunnen lekken via logboeken, configuratiebestanden of broncodebeheer. Gebruik in plaats daarvan certificaten of certificaatloze referenties.

Sla gevoelige waarden buiten configuratiebestanden op. Gebruik Azure Key Vault, omgevingsvariabelen of de ASP.NET Core Secret Manager voor certificaatwachtwoorden en clientgeheimen. Voer geen gevoelige waarden door aan broncodebeheer.

Certificaten roteren voordat ze verlopen. Bewaak de vervaldatums van het certificaat en stel een rotatieproces in. Azure Key Vault kunt het vernieuwen van certificaten automatiseren.

Gebruik Azure Key Vault voor certificaatopslag. Key Vault biedt gecentraliseerd beheer, toegangsbeleid, auditlogboekregistratie en automatische rotatie voor certificaten.

Verwante inhoud

• Verificatie zonder certificaat
• Certificaatreferenties
• Tokenontsleuteling
• Client Secret