Inicjowanie aplikacji klienckich

  • 3 min

W przypadku MSAL.NET 3.x zalecanym sposobem utworzenia wystąpienia aplikacji jest użycie konstruktorów aplikacji: PublicClientApplicationBuilder i ConfidentialClientApplicationBuilder. Oferują one zaawansowany mechanizm konfigurowania aplikacji z poziomu kodu lub pliku konfiguracji, a nawet przez mieszanie obu podejść.

Przed zainicjowaniem aplikacji należy ją najpierw zarejestrować, aby można było ją zintegrować z Platforma tożsamości Microsoft. Po rejestracji mogą być potrzebne następujące informacje (które można znaleźć w witrynie Azure Portal):

  • Identyfikator aplikacji (klienta) — jest to ciąg reprezentujący identyfikator GUID.
  • Identyfikator katalogu (dzierżawy) — zapewnia funkcje zarządzania tożsamościami i dostępem (IAM) do aplikacji i zasobów używanych przez organizację. Może określić, czy piszesz aplikację biznesową wyłącznie dla organizacji (nazywanej również aplikacją z jedną dzierżawą).
  • Adres URL dostawcy tożsamości (nazwany wystąpienie) i odbiorcy logowania dla aplikacji. Te dwa parametry są określane zbiorczo jako urząd.
  • Poświadczenia klienta — które mogą mieć postać wpisu tajnego aplikacji (ciąg wpisu tajnego klienta) lub certyfikatu (typu X509Certificate2), jeśli jest to poufne aplikacje klienckie.
  • W przypadku aplikacji internetowych, a czasami w przypadku publicznych aplikacji klienckich (w szczególności gdy aplikacja musi używać brokera), należy ustawić identyfikator URI przekierowania, w którym dostawca tożsamości będzie kontaktować się z powrotem z aplikacją przy użyciu tokenów zabezpieczających.

Inicjowanie publicznych i poufnych aplikacji klienckich z kodu

Poniższy kod tworzy wystąpienie publicznej aplikacji klienckiej, logując użytkowników w chmurze publicznej Microsoft Azure, przy użyciu kont służbowych lub osobistych kont Microsoft.

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

W ten sam sposób poniższy kod tworzy wystąpienie poufnej aplikacji (aplikacji internetowej znajdującej się w https://myapp.azurewebsites.netlokalizacji ) obsługującej tokeny od użytkowników w chmurze publicznej Microsoft Azure przy użyciu kont służbowych lub osobistych kont Microsoft. Aplikacja jest identyfikowana z dostawcą tożsamości przez udostępnienie klucza tajnego klienta:

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

Modyfikatory konstruktora

W fragmentach kodu przy użyciu konstruktorów .With aplikacji metody można stosować jako modyfikatory (na przykład .WithAuthority i .WithRedirectUri).

  • .WithAuthority modyfikator: .WithAuthority modyfikator ustawia urząd domyślny aplikacji na urząd firmy Microsoft Entra, z możliwością wybrania chmury platformy Azure, odbiorców, dzierżawy (identyfikatora dzierżawy lub nazwy domeny) lub podania bezpośrednio identyfikatora URI urzędu.

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

  • .WithRedirectUri modyfikator: .WithRedirectUri modyfikator zastępuje domyślny identyfikator URI przekierowania.

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

Modyfikatory wspólne dla publicznych i poufnych aplikacji klienckich

W poniższej tabeli wymieniono niektóre modyfikatory, które można ustawić na publicznym lub poufnym kliencie.

Modyfikator opis
.WithAuthority() Ustawia domyślny urząd aplikacji na urząd firmy Microsoft Entra, z możliwością wybrania chmury platformy Azure, odbiorców, dzierżawy (identyfikatora dzierżawy lub nazwy domeny) lub podania bezpośrednio identyfikatora URI urzędu.
.WithTenantId(string tenantId) Zastępuje identyfikator dzierżawy lub opis dzierżawy.
.WithClientId(string) Zastępuje identyfikator klienta.
.WithRedirectUri(string redirectUri) Zastępuje domyślny identyfikator URI przekierowania. Jest to przydatne w scenariuszach wymagających brokera.
.WithComponent(string) Ustawia nazwę biblioteki przy użyciu MSAL.NET (ze względów telemetrycznych).
.WithDebugLoggingCallback() Jeśli zostanie wywołana, aplikacja wywołuje Debug.Write po prostu włączanie śledzenia debugowania.
.WithLogging() W przypadku wywołania aplikacja wywołuje wywołanie zwrotne ze śladami debugowania.
.WithTelemetry(TelemetryCallback telemetryCallback) Ustawia delegata używanego do wysyłania danych telemetrycznych.

Modyfikatory specyficzne dla poufnych aplikacji klienckich

Modyfikatory specyficzne dla poufnego konstruktora aplikacji klienckich można znaleźć w ConfidentialClientApplicationBuilder klasie . Różne metody można znaleźć w dokumentacji zestawu Azure SDK dla platformy .NET.

Modyfikatory, takie jak .WithCertificate(X509Certificate2 certificate) i .WithClientSecret(string clientSecret) wzajemnie się wykluczają. Jeśli podasz oba te elementy, biblioteka MSAL zgłosi znaczący wyjątek.