Inicializace klientských aplikací pomocí MSAL.NET

Tento článek popisuje inicializaci veřejných klientů a důvěrných klientských aplikací pomocí Identity a ověřování Microsoftu pro .NET (MSAL.NET). Další informace o typech klientských aplikací najdete v tématu Veřejný klient a důvěrné klientské aplikace.

S MSAL.NET 3.x doporučujeme vytvořit instanci aplikace pomocí tvůrce aplikací: PublicClientApplicationBuilder a ConfidentialClientApplicationBuilder. Nabízejí výkonný mechanismus konfigurace aplikace z kódu, konfiguračního souboru nebo dokonce kombinací obou přístupů.

Předpoklady

Před inicializací aplikace je nejprve potřeba ji zaregistrovat, aby byla aplikace integrovaná s Microsoft identity platform. Další informace najdete v článku Rychlý start: Registrace aplikace na platformě Microsoft identity. Po registraci budete potřebovat následující informace, které najdete na stránce registrace aplikace v Centrum pro správu Microsoft Entra.

  • ID aplikace (klienta) – jedná se o řetězec představující identifikátor GUID.
  • ID adresáře (tenanta) – Poskytuje možnosti správy identit a přístupu (IAM) aplikacím a prostředkům používaným vaší organizací. Může určit, jestli píšete obchodní aplikaci výhradně pro vaši organizaci (také pojmenovanou jednoklientovou aplikaci).
  • Adresa URL zprostředkovatele identity (pojmenovaná instance) a cílová skupina přihlašování pro vaši aplikaci. Tyto dva parametry se souhrnně označují jako autorita.
  • Přihlašovací údaje klienta – které můžou mít formu tajného klíče aplikace (řetězec tajného klíče klienta) nebo certifikátu (typu X509Certificate2), pokud se jedná o důvěrnou klientskou aplikaci.
  • U webových aplikací a někdy také u veřejných klientských aplikací (zejména když vaše aplikace potřebuje použít zprostředkovatele) musíte nastavit identifikátor URI pro přesměrování, na který poskytovatel identity odešle zpět do vaší aplikace bezpečnostní tokeny.

Inicializace aplikací

Existuje mnoho různých způsobů vytvoření instance klientských aplikací.

Inicializace veřejné klientské aplikace z kódu

Následující kód vytvoří instanci veřejné klientské aplikace, která přihlašuje uživatele do veřejného cloudu Microsoft Azure pomocí jejich pracovních, školních nebo osobních účtů Microsoft.

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

Inicializace důvěrné klientské aplikace z kódu

Stejně tak následující kód vytvoří instanci důvěrné aplikace (webová aplikace umístěná na https://myapp.azurewebsites.netadrese) zpracovávající tokeny od uživatelů ve veřejném cloudu Microsoft Azure, s pracovními a školními účty nebo osobními Microsoft účty. Aplikace je identifikována s zprostředkovatelem identity sdílením tajného klíče klienta:

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

V produkčním prostředí se ale certifikáty doporučují, protože jsou bezpečnější než tajné klíče klienta. Je možné je vytvořit a nahrát do Centrum pro správu Microsoft Entra. Kód by pak byl následující:

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

Inicializace veřejné klientské aplikace z možností konfigurace

Následující kód vytvoří instanci veřejné klientské aplikace z objektu konfigurace, který by mohl být vyplněn programově nebo číst z konfiguračního souboru:

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

Inicializace důvěrné klientské aplikace z možností konfigurace

Stejný druh vzoru platí pro důvěrné klientské aplikace. Můžete také přidat další parametry pomocí .WithXXX modifikátorů. Tento příklad používá .WithCertificate.

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

Modifikátory builderu

V fragmentech kódu pomocí tvůrce aplikací lze mnoho .With metod použít jako modifikátory (například .WithCertificate a .WithRedirectUri).

Modifikátory společné pro veřejné a důvěrné klientské aplikace

Modifikátory, které můžete nastavit pro veřejného klienta nebo tvůrce důvěrných klientských aplikací, najdete ve AbstractApplicationBuilder<T> třídě. Různé metody najdete v Azure SDK pro .NET dokumentaci.

Modifikátory specifické pro aplikace Xamarin.iOS

Modifikátory, které můžete nastavit v tvůrci veřejných klientských aplikací v Xamarin.iOS, jsou:

Modifikátor Description
.WithIosKeychainSecurityGroup() pouze Xamarin.iOS: Nastaví skupinu zabezpečení řetězu klíčů iOS (pro trvalost mezipaměti).

Modifikátory specifické pro důvěrné klientské aplikace

Modifikátory specifické pro tvůrce důvěrných klientských aplikací lze nalézt ve ConfidentialClientApplicationBuilder třídě. Různé metody najdete v Azure SDK pro .NET dokumentaci.

Modifikátory, například .WithCertificate(X509Certificate2 certificate) a .WithClientSecret(string clientSecret), se vzájemně vylučují. Pokud zadáte obojí, nástroj MSAL vyvolá smysluplnou výjimku.

Příklad použití modifikátorů

Předpokládejme, že vaše aplikace je obchodní aplikace, která je určená jenom pro vaši organizaci. Pak můžete napsat:

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

Programování pro národní cloudy se zjednodušilo, takže pokud chcete, aby vaše aplikace byla víceklientská aplikace v národním cloudu, můžete napsat například:

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

K dispozici je také možnost přepsání nastavení pro ADFS (MSAL.NET podporuje pouze ADFS 2019 nebo novější):

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

A nakonec, pokud vyvíjíte pro Azure AD B2C, můžete svého tenanta zadat takto:

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

Viz také

Referenční dokumentace k rozhraní API

Balíček na NuGetu

Zdrojový kód knihovny

Ukázky kódu

Další kroky

Po inicializaci klientské aplikace je vaším dalším úkolem přidat podporu pro přihlašování uživatelů, autorizovaný přístup k rozhraní API nebo obojí.

Naše dokumentace ke scénáři aplikace obsahuje pokyny pro přihlášení uživatele a získání přístupového tokenu pro přístup k rozhraní API jménem tohoto uživatele:

  • Last updated on