Clienttoepassingen initialiseren

  • 3 minuten

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

Voordat u een toepassing initialiseert, moet u deze eerst registreren, zodat uw app kan worden geïntegreerd met het Microsoft Identity-platform. Na de registratie hebt u mogelijk de volgende informatie nodig (die u kunt vinden in de Azure Portal):

  • Toepassings-id (client): dit is een tekenreeks die een GUID vertegenwoordigt.
  • Directory-id (tenant): biedt mogelijkheden voor identiteits- en toegangsbeheer (IAM) voor toepassingen en resources 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 id-provider (de naam van het exemplaar) en de aanmeldingsdoelgroep voor uw toepassing. 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.

Openbare en vertrouwelijke clienttoepassingen initialiseren vanuit code

Met de volgende code wordt een openbare clienttoepassing gestart, gebruikers aangemeld in de openbare Cloud van Microsoft Azure, met hun werk- en schoolaccounts of hun persoonlijke Microsoft-accounts.

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

Op dezelfde manier wordt met de volgende code een vertrouwelijke toepassing gestart (een web-app op https://myapp.azurewebsites.net) die tokens verwerkt van gebruikers in de openbare Microsoft Azure-cloud, met hun werk- en schoolaccounts of hun persoonlijke Microsoft-accounts. 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();

Aanpassingsfuncties voor opbouwfunctie

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

  • .WithAuthority modifier: De .WithAuthority wijzigingsfunctie stelt de standaardinstantie van de toepassing in op een Microsoft Entra-instantie, met de mogelijkheid om de Azure Cloud, de doelgroep, de tenant (tenant-id of domeinnaam) te kiezen of rechtstreeks de instantie-URI op te geven.

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

  • .WithRedirectUri modifier: de .WithRedirectUri modifier overschrijft de standaardomleidings-URI.

    IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(client_id)
    .WithAuthority(AzureCloudInstance.AzurePublic, tenant_id)
    .WithRedirectUri("http://localhost")
    .Build();

Modifiers die gebruikelijk zijn voor openbare en vertrouwelijke clienttoepassingen

De onderstaande tabel bevat enkele van de modifiers die u kunt instellen op een openbare of vertrouwelijke client.

Modifier Beschrijving
.WithAuthority() Stelt de standaardinstantie van de toepassing in op een Microsoft Entra-instantie, met de mogelijkheid om de Azure Cloud, de doelgroep, de tenant (tenant-id of domeinnaam) te kiezen of rechtstreeks de instantie-URI op te geven.
.WithTenantId(string tenantId) Hiermee wordt de tenant-id of de beschrijving van de tenant overschreven.
.WithClientId(string) Hiermee wordt de client-id overschreven.
.WithRedirectUri(string redirectUri) Hiermee wordt de standaard URI voor omleiding overschreven. Dit is handig voor scenario's waarvoor een broker is vereist.
.WithComponent(string) Hiermee stelt u de naam van de bibliotheek in met behulp van MSAL.NET (vanwege telemetrie).
.WithDebugLoggingCallback() Als de toepassing wordt aangeroepen Debug.Write , worden traceringen voor foutopsporing ingeschakeld.
.WithLogging() Als deze wordt aangeroepen, roept de toepassing een callback aan met traceringen voor foutopsporing.
.WithTelemetry(TelemetryCallback telemetryCallback) Hiermee stelt u de gemachtigde in die wordt gebruikt voor het verzenden van telemetrie.

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, genereert MSAL een zinvolle uitzondering.