Clienttoepassingen initialiseren met behulp van MSAL.NET

In dit artikel wordt beschreven hoe u openbare client- en vertrouwelijke clienttoepassingen initialiseert met behulp van de Microsoft Authentication Library voor .NET (MSAL.NET). Zie Openbare client- en vertrouwelijke clienttoepassingen voor meer informatie over de typen clienttoepassingen.

Met MSAL.NET 3.x is de aanbevolen manier om een toepassing te instantiëren met behulp van de toepassingsbouwers: PublicClientApplicationBuilder en ConfidentialClientApplicationBuilder. Ze bieden een krachtig mechanisme voor het configureren van de toepassing vanuit de code, een configuratiebestand of zelfs door beide benaderingen te combineren.

Prerequisites

Voordat u een toepassing initialiseert, moet u deze eerst registreren, zodat uw app kan worden geïntegreerd met de Microsoft identity platform. Raadpleeg de quickstart: Een toepassing registreren bij de Microsoft identity platform voor meer informatie. Na de registratie hebt u de volgende informatie nodig. Deze vindt u op de pagina app-registratie in de Microsoft Entra-beheercentrum.

  • Toepassings-id (client): dit is een tekenreeks die een GUID vertegenwoordigt.
  • Directory-id (tenant) - biedt mogelijkheden voor identiteits- en toegangsbeheer (IAM) voor toepassingen en hulpbronnen die door uw organisatie worden gebruikt. U kunt opgeven of u alleen een Line-Of-Business-toepassing schrijft voor uw organisatie (ook wel toepassing met één tenant genoemd).
  • De URL van de identiteitsprovider (de zogeheten instance) en de aanmeldingsdoelgroep voor uw applicatie. Deze twee parameters worden gezamenlijk de autoriteit genoemd.
  • Clientreferenties : deze kunnen de vorm aannemen van een toepassingsgeheim (clientgeheimtekenreeks) of certificaat (van het type X509Certificate2) als het een vertrouwelijke client-app is.
  • Voor web-apps en soms voor openbare client-apps (met name wanneer uw app een broker moet gebruiken), moet u de omleidings-URI instellen waar de id-provider contact opneemt met uw toepassing met de beveiligingstokens.

Toepassingen initialiseren

Er zijn veel verschillende manieren om clienttoepassingen te instantiëren.

Een openbare clienttoepassing initialiseren vanuit code

Met de volgende code wordt een openbare clienttoepassing geïnstitueert, gebruikers aangemeld in de Microsoft Azure openbare cloud, met hun werk-, school- of persoonlijke Microsoft-accounts.

IPublicClientApplication app = PublicClientApplicationBuilder.Create(clientId)
    .Build();

Een vertrouwelijke clienttoepassing initialiseren vanuit code

Op dezelfde manier instantieert de volgende code een vertrouwelijke toepassing (een web-app op https://myapp.azurewebsites.net) die tokens verwerkt van gebruikers in de openbare Microsoft Azure-cloud, met hun werk- of schoolaccount of hun persoonlijke Microsoft-account. De toepassing wordt geïdentificeerd met de id-provider door een clientgeheim te delen:

string redirectUri = "https://myapp.azurewebsites.net";
IConfidentialClientApplication app = ConfidentialClientApplicationBuilder.Create(clientId)
    .WithClientSecret(clientSecret)
    .WithRedirectUri(redirectUri )
    .Build();

In productie worden certificaten echter aanbevolen omdat ze veiliger zijn dan clientgeheimen. Ze kunnen worden gemaakt en geüpload naar de Microsoft Entra-beheercentrum. De code zou dan het volgende zijn:

IConfidentialClientApplication app = ConfidentialClientApplicationBuilder.Create(clientId)
    .WithCertificate(certificate)
    .WithRedirectUri(redirectUri )
    .Build();

Een openbare clienttoepassing initialiseren vanuit configuratieopties

Met de volgende code wordt een openbare clienttoepassing geïnstitueert vanuit een configuratieobject, dat programmatisch kan worden ingevuld of kan worden gelezen uit een configuratiebestand:

PublicClientApplicationOptions options = GetOptions(); // your own method
IPublicClientApplication app = PublicClientApplicationBuilder.CreateWithApplicationOptions(options)
    .Build();

Een vertrouwelijke clienttoepassing initialiseren vanuit configuratieopties

Hetzelfde type patroon is van toepassing op vertrouwelijke clienttoepassingen. U kunt ook andere parameters toevoegen met .WithXXX modifiers. In dit voorbeeld wordt .WithCertificategebruikt.

ConfidentialClientApplicationOptions options = GetOptions(); // your own method
IConfidentialClientApplication app = ConfidentialClientApplicationBuilder.CreateWithApplicationOptions(options)
    .WithCertificate(certificate)
    .Build();

Builder-modificatoren

In de codefragmenten met behulp van toepassingsbouwers kunnen veel .With methoden worden toegepast als modifiers (bijvoorbeeld .WithCertificate en .WithRedirectUri).

Modifiers die gebruikelijk zijn voor openbare en vertrouwelijke clienttoepassingen

De modifiers die u kunt instellen op een openbare client of vertrouwelijke clienttoepassingsbouwer vindt u in de AbstractApplicationBuilder<T> klasse. De verschillende methoden vindt u in de Azure SDK voor .NET documentatie.

Modifiers specifiek voor Xamarin.iOS-toepassingen

De modifiers die u kunt instellen op een openbare clienttoepassingsbouwer op Xamarin.iOS zijn:

Aanpasser Description
.WithIosKeychainSecurityGroup() alleen Xamarin.iOS: hiermee stelt u de beveiligingsgroep voor de iOS-sleutelketen in (voor de persistentie van de cache).

Modifiers die specifiek zijn voor vertrouwelijke clienttoepassingen

De modifiers die specifiek zijn voor een bouwer van vertrouwelijke clienttoepassingen vindt u in de ConfidentialClientApplicationBuilder klasse. De verschillende methoden vindt u in de Azure SDK voor .NET documentatie.

Modifiers zoals .WithCertificate(X509Certificate2 certificate) en .WithClientSecret(string clientSecret) sluiten elkaar wederzijds uit. Als u beide opgeeft, geeft MSAL een betekenisvolle uitzondering.

Voorbeeld van het gebruik van modifiers

Stel dat uw toepassing een Line-Of-Business-toepassing is, die alleen voor uw organisatie geldt. Vervolgens kunt u het volgende schrijven:

IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(clientId)
        .WithAuthority(AzureCloudInstance.AzurePublic, tenantId)
        .Build();

Programmeren voor nationale clouds is vereenvoudigd, dus als u wilt dat uw toepassing een toepassing met meerdere tenants in een nationale cloud is, kunt u bijvoorbeeld schrijven:

IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(clientId)
        .WithAuthority(AzureCloudInstance.AzureUsGovernment, AadAuthorityAudience.AzureAdMultipleOrgs)
        .Build();

Er is ook een overschrijving voor ADFS (MSAL.NET ondersteunt alleen ADFS 2019 of nieuwer):

IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(clientId)
        .WithAdfsAuthority("https://consoso.com/adfs")
        .Build();

Als u een Azure AD B2C-ontwikkelaar bent, kunt u uw tenant als volgt opgeven:

IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(clientId)
        .WithB2CAuthority("https://fabrikamb2c.b2clogin.com/tfp/{tenant}/{PolicySignInSignUp}")
        .Build();

Zie ook

API-referentiedocumentatie

Pakket op NuGet

Broncode van een bibliotheek

Codevoorbeelden

Volgende stappen 

Nadat u de clienttoepassing hebt geïnitialiseerd, is de volgende taak het toevoegen van ondersteuning voor gebruikersaanmelding, geautoriseerde API-toegang of beide.

Onze documentatie over het toepassingsscenario biedt richtlijnen voor het aanmelden bij een gebruiker en het verkrijgen van een toegangstoken voor toegang tot een API namens die gebruiker:

  • Last updated on