Kurz: Přihlášení uživatelů a volání Microsoft Graphu v desktopové aplikaci WPF (Windows Presentation Foundation)

Platí pro: Zelený kruh se symbolem bílé značky zaškrtnutí, který označuje následující obsah platí pro tenanty pracovních sil. Tenanti pracovních sil zelený kruh se symbolem bílé značky zaškrtnutí, který označuje následující obsah platí pro externí tenanty. Externí tenanti (další informace)

V tomto kurzu vytvoříte nativní desktopovou aplikaci .NET (XAML), která přihlásí uživatele a získá přístupový token pro volání rozhraní Microsoft Graph API.

Po dokončení průvodce bude vaše aplikace moct volat chráněné rozhraní API, které používá osobní účty (včetně outlook.com, live.com a dalších). Aplikace bude také používat pracovní a školní účty z libovolné společnosti nebo organizace, která používá ID Microsoft Entra.

V tomto kurzu se naučíte:

  • Vytvoření projektu Windows Presentation Foundation (WPF) v sadě Visual Studio
  • Instalace knihovny Microsoft Authentication Library (MSAL) pro .NET
  • Registrace aplikace
  • Přidání kódu pro podporu přihlášení a odhlášení uživatele
  • Přidání kódu pro volání rozhraní Microsoft Graph API
  • Otestování aplikace

Požadavky

  • Součást pracovního týmu. Můžete použít výchozí adresář nebo nastavit nového tenanta.
  • Zaregistrujte novou aplikaci v Centru pro správu Microsoft Entra nakonfigurované pro účty v libovolném organizačním adresáři a osobních účtech Microsoft. Další podrobnosti najdete v tématu Registrace aplikace . Na stránce Přehled aplikace si poznamenejte následující hodnoty pro pozdější použití:
    • ID aplikace (klienta)
    • ID adresáře (klienta)
  • Přidejte následující URI přesměrování pomocí konfigurace platformy Mobilní a desktopové aplikace. Další podrobnosti najdete v tématu Jak přidat přesměrovací URI do vaší aplikace.
    • Identifikátor URI přesměrování: https://login.microsoftonline.com/common/oauth2/nativeclient
  • .NET Framework 4.8
  • Visual Studio 2019

Jak funguje ukázková aplikace generovaná touto příručkou

Snímek obrazovky s fungováním ukázkové aplikace vygenerované v tomto kurzu

Ukázková aplikace, kterou vytvoříte pomocí této příručky, umožňuje tvorbu desktopové aplikace pro Windows, jež využívá Microsoft Graph API nebo webové rozhraní API, které přijímá tokeny z koncového bodu platformy Microsoft Identity. V tomto scénáři přidáte token do požadavků HTTP prostřednictvím autorizační hlavičky. Knihovna MSAL (Microsoft Authentication Library) zpracovává získání a obnovení tokenu.

Zpracování získávání tokenů pro přístup k chráněným webovým rozhraním API

Po ověření uživatele obdrží ukázková aplikace token, který můžete použít k dotazování rozhraní Microsoft Graph API nebo webového rozhraní API zabezpečeného platformou Microsoft Identity Platform.

Rozhraní API, jako je Microsoft Graph, vyžadují token pro povolení přístupu ke konkrétním prostředkům. Například token se vyžaduje ke čtení profilu uživatele, přístupu ke kalendáři uživatele nebo k odesílání e-mailů. Aplikace může požádat o přístupový token pomocí knihovny MSAL pro přístup k těmto prostředkům zadáním oborů rozhraní API. Tento přístupový token se pak přidá do hlavičky autorizace HTTP pro každé volání provedené proti chráněnému prostředku.

MSAL spravuje ukládání do mezipaměti a aktualizaci přístupových tokenů za vás, aby vaše aplikace nemusela.

Balíčky NuGet

Tato příručka používá následující balíčky NuGet:

Knihovna Popis
Microsoft.Identity.Client Knihovna ověřování společnosti Microsoft (MSAL.NET)

Nastavení projektu

V této části vytvoříte nový projekt, který předvede, jak integrovat desktopovou aplikaci .NET (XAML) s přihlášením k Microsoftu , aby aplikace dokázala dotazovat webová rozhraní API, která vyžadují token.

Aplikace, kterou vytvoříte, zobrazí tlačítko, které bude volat rozhraní Microsoft Graph API, oblast pro zobrazení výsledků a tlačítko odhlášení.

Poznámka:

Chcete raději stáhnout projekt této ukázky pro Visual Studio? Stáhněte si projekt a zaregistrujte aplikaci, abyste před spuštěním nakonfigurovali ukázku kódu.

Aplikaci vytvořte pomocí následujícího postupu:

  1. Otevřete Visual Studio
  2. V úvodním okně vyberte Vytvořit nový projekt.
  3. V rozevíracím seznamu Všechny jazyky vyberte C#.
  4. Vyhledejte a zvolte šablonu aplikace WPF (.NET Framework) a pak vyberte Další.
  5. Do pole Název projektu zadejte název, jako je Win-App-calling-MsGraph.
  6. Zvolte umístění projektu nebo přijměte výchozí možnost.
  7. V rozhraní vyberte rozhraní .NET Framework 4.8.
  8. Vyberte Vytvořit.

Přidejte MSAL do svého projektu

  1. V aplikaci Visual Studio zvolte Nástroje>Správce balíčků NuGet>Konzola Správce balíčků.

  2. V okně konzoly Správce balíčků vložte následující příkaz Azure PowerShellu:

    Install-Package Microsoft.Identity.Client -Pre

Přidání kódu pro inicializaci knihovny MSAL

V tomto kroku vytvoříte třídu pro zpracování interakce s knihovnou MSAL, jako je zpracování tokenů.

  1. Otevřete App.xaml.cs soubor a přidejte odkaz msAL do třídy:

    using Microsoft.Identity.Client;

  2. Aktualizujte třídu aplikace na následující:

    public partial class App : Application
{
    static App()
    {
        _clientApp = PublicClientApplicationBuilder.Create(ClientId)
            .WithAuthority(AzureCloudInstance.AzurePublic, Tenant)
            .WithDefaultRedirectUri()
            .Build();
    }

    // Below are the clientId (Application Id) of your app registration and the tenant information.
    // You have to replace:
    // - the content of ClientID with the Application Id for your app registration
    // - the content of Tenant by the information about the accounts allowed to sign-in in your application:
    //   - For Work or School account in your org, use your tenant ID, or domain
    //   - for any Work or School accounts, use `organizations`
    //   - for any Work or School accounts, or Microsoft personal account, use `common`
    //   - for Microsoft Personal account, use consumers
    private static string ClientId = "Enter_the_Application_Id_here";

    private static string Tenant = "common";

    private static IPublicClientApplication _clientApp ;

    public static IPublicClientApplication PublicClientApp { get { return _clientApp; } }
}

Vytvoření uživatelského rozhraní aplikace

Tato část ukazuje, jak může aplikace dotazovat chráněný back-endový server, jako je Microsoft Graph.

Soubor MainWindow.xaml se automaticky vytvoří jako součást šablony projektu. Otevřete tento soubor a pak nahraďte uzel Grid<>následujícím kódem:

<Grid>
    <StackPanel Background="Azure">
        <StackPanel Orientation="Horizontal" HorizontalAlignment="Right">
            <Button x:Name="CallGraphButton" Content="Call Microsoft Graph API" HorizontalAlignment="Right" Padding="5" Click="CallGraphButton_Click" Margin="5" FontFamily="Segoe Ui"/>
            <Button x:Name="SignOutButton" Content="Sign-Out" HorizontalAlignment="Right" Padding="5" Click="SignOutButton_Click" Margin="5" Visibility="Collapsed" FontFamily="Segoe Ui"/>
        </StackPanel>
        <Label Content="API Call Results" Margin="0,0,0,-5" FontFamily="Segoe Ui" />
        <TextBox x:Name="ResultText" TextWrapping="Wrap" MinHeight="120" Margin="5" FontFamily="Segoe Ui"/>
        <Label Content="Token Info" Margin="0,0,0,-5" FontFamily="Segoe Ui" />
        <TextBox x:Name="TokenInfoText" TextWrapping="Wrap" MinHeight="70" Margin="5" FontFamily="Segoe Ui"/>
    </StackPanel>
</Grid>

Použijte MSAL k získání tokenu pro Microsoft Graph API

V této části použijete MSAL k získání tokenu pro rozhraní Microsoft Graph API.

  1. Do souboru MainWindow.xaml.cs přidejte odkaz msAL do třídy:

    using Microsoft.Identity.Client;

  2. MainWindow Nahraďte kód třídy následujícím kódem:

    public partial class MainWindow : Window
{
    //Set the API Endpoint to Graph 'me' endpoint
    string graphAPIEndpoint = "https://graph.microsoft.com/v1.0/me";

    //Set the scope for API call to user.read
    string[] scopes = new string[] { "user.read" };


    public MainWindow()
    {
        InitializeComponent();
    }

  /// <summary>
    /// Call AcquireToken - to acquire a token requiring user to sign-in
    /// </summary>
    private async void CallGraphButton_Click(object sender, RoutedEventArgs e)
    {
        AuthenticationResult authResult = null;
        var app = App.PublicClientApp;
        ResultText.Text = string.Empty;
        TokenInfoText.Text = string.Empty;

        var accounts = await app.GetAccountsAsync();
        var firstAccount = accounts.FirstOrDefault();

        try
        {
            authResult = await app.AcquireTokenSilent(scopes, firstAccount)
                .ExecuteAsync();
        }
        catch (MsalUiRequiredException ex)
        {
            // A MsalUiRequiredException happened on AcquireTokenSilent.
            // This indicates you need to call AcquireTokenInteractive to acquire a token
            System.Diagnostics.Debug.WriteLine($"MsalUiRequiredException: {ex.Message}");

            try
            {
                authResult = await app.AcquireTokenInteractive(scopes)
                    .WithAccount(accounts.FirstOrDefault())
                    .WithPrompt(Prompt.SelectAccount)
                    .ExecuteAsync();
            }
            catch (MsalException msalex)
            {
                ResultText.Text = $"Error Acquiring Token:{System.Environment.NewLine}{msalex}";
            }
        }
        catch (Exception ex)
        {
            ResultText.Text = $"Error Acquiring Token Silently:{System.Environment.NewLine}{ex}";
            return;
        }

        if (authResult != null)
        {
            ResultText.Text = await GetHttpContentWithToken(graphAPIEndpoint, authResult.AccessToken);
            DisplayBasicTokenInfo(authResult);
            this.SignOutButton.Visibility = Visibility.Visible;
        }
    }
    }

Více informací

Interaktivní získání tokenu uživatele

AcquireTokenInteractive Volání metody způsobí, že se zobrazí okno s výzvou, aby se uživatelé přihlásili. Aplikace obvykle vyžadují, aby se uživatelé přihlašovali interaktivně při prvním přístupu k chráněnému prostředku. Při neúspěšném získání tokenu se může také muset přihlásit, když dojde k selhání tiché operace (například když vyprší platnost hesla uživatele).

Získání tokenu uživatele bez upozornění

Metoda AcquireTokenSilent zpracovává získání a obnovení tokenů bez zásahu uživatele. Po prvním provedení AcquireTokenInteractive je obvyklou metodou AcquireTokenSilent, která se používá k tišému získávání tokenů pro přístup k chráněným prostředkům při následných voláních, protože volání pro vyžádání nebo obnovení tokenů jsou prováděna tiše.

Nakonec může selhání metody AcquireTokenSilent nastat. Důvodem selhání může být, že se uživatel buď odhlásil, nebo změnil heslo na jiném zařízení. Když služba MSAL zjistí, že problém je možné vyřešit vyžadováním interaktivní akce, aktivuje MsalUiRequiredException výjimku. Vaše aplikace může tuto výjimku zpracovat dvěma způsoby:

  • Může okamžitě zavolat AcquireTokenInteractive. Výsledkem tohoto volání je výzva, aby se uživatel přihlásil. Tento model se používá v online aplikacích, kde není k dispozici offline obsah pro uživatele. Ukázka vygenerovaná tímto nastavením se řídí tímto vzorem, který lze vidět v akci při prvním spuštění ukázky.

  • Vzhledem k tomu, že aplikaci nepoužil žádný uživatel, PublicClientApp.Users.FirstOrDefault() obsahuje hodnotu null a je vyvolána MsalUiRequiredException výjimka.

  • Kód v ukázce pak zpracuje výjimku voláním AcquireTokenInteractive, což vede k výzvě uživatele k přihlášení.

  • Místo toho může uživatelům prezentovat vizuální označení, že se vyžaduje interaktivní přihlášení, aby mohli vybrat správný čas pro přihlášení. Nebo může aplikace zkusit AcquireTokenSilent znovu později. Tento model se často používá, když uživatelé můžou bez přerušení používat jiné funkce aplikace. Pokud je například v aplikaci k dispozici offline obsah. V takovém případě se uživatelé můžou rozhodnout, kdy se chtějí přihlásit, aby získali přístup k chráněnému prostředku, nebo aktualizovat zastaralé informace. Případně se může aplikace rozhodnout opakovat AcquireTokenSilent, když se síť obnoví po dočasné nedostupnosti.

Volání rozhraní Microsoft Graph API pomocí tokenu, který jste právě získali

Přidejte do svého MainWindow.xaml.cs následující novou metodu. Metoda se používá k vytvoření GET požadavku na rozhraní Graph API pomocí hlavičky Authorize:

/// <summary>
/// Perform an HTTP GET request to a URL using an HTTP Authorization header
/// </summary>
/// <param name="url">The URL</param>
/// <param name="token">The token</param>
/// <returns>String containing the results of the GET operation</returns>
public async Task<string> GetHttpContentWithToken(string url, string token)
{
    var httpClient = new System.Net.Http.HttpClient();
    System.Net.Http.HttpResponseMessage response;
    try
    {
        var request = new System.Net.Http.HttpRequestMessage(System.Net.Http.HttpMethod.Get, url);
        //Add the token in Authorization header
        request.Headers.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", token);
        response = await httpClient.SendAsync(request);
        var content = await response.Content.ReadAsStringAsync();
        return content;
    }
    catch (Exception ex)
    {
        return ex.ToString();
    }
}

Další informace o volání REST proti chráněnému rozhraní API

V této ukázkové aplikaci použijete metodu GetHttpContentWithToken k vytvoření požadavku HTTP GET na chráněný prostředek, který vyžaduje token, a pak vrátí obsah volajícímu. Tato metoda přidá získaný token do hlavičky autorizace HTTP. V této ukázce je prostředek koncovým bodem rozhraní Microsoft Graph API me , který zobrazuje informace o profilu uživatele.

Přidání metody pro odhlášení uživatele

Pokud se chcete odhlásit uživatele, přidejte do MainWindow.xaml.cs souboru následující metodu:

/// <summary>
/// Sign out the current user
/// </summary>
private async void SignOutButton_Click(object sender, RoutedEventArgs e)
{
    var accounts = await App.PublicClientApp.GetAccountsAsync();

    if (accounts.Any())
    {
        try
        {
            await App.PublicClientApp.RemoveAsync(accounts.FirstOrDefault());
            this.ResultText.Text = "User has signed-out";
            this.CallGraphButton.Visibility = Visibility.Visible;
            this.SignOutButton.Visibility = Visibility.Collapsed;
        }
        catch (MsalException ex)
        {
            ResultText.Text = $"Error signing-out user: {ex.Message}";
        }
    }
}

Další informace o odhlášení uživatele

Tato metoda SignOutButton_Click odebere uživatele z MSAL mezipaměti, čímž MSAL v podstatě umožní zapomenout na aktuálního uživatele, takže budoucí požadavek na získání tokenu bude úspěšný pouze v interaktivním režimu.

I když aplikace v této ukázce podporuje jednotlivé uživatele, MSAL podporuje scénáře, ve kterých může být současně přihlášeno více účtů. Příkladem je e-mailová aplikace, ve které má uživatel více účtů.

Zobrazení základních informací o tokenu

Pokud chcete zobrazit základní informace o tokenu, přidejte do souboru MainWindow.xaml.cs následující metodu:

/// <summary>
/// Display basic information contained in the token
/// </summary>
private void DisplayBasicTokenInfo(AuthenticationResult authResult)
{
    TokenInfoText.Text = "";
    if (authResult != null)
    {
        TokenInfoText.Text += $"Username: {authResult.Account.Username}" + Environment.NewLine;
        TokenInfoText.Text += $"Token Expires: {authResult.ExpiresOn.ToLocalTime()}" + Environment.NewLine;
    }
}

Více informací

Kromě přístupového tokenu, který se používá k volání rozhraní Microsoft Graph API, získá služba MSAL také token ID po přihlášení uživatele. Tento token obsahuje malou podmnožinu informací, které se týkají uživatelů. Metoda DisplayBasicTokenInfo zobrazí základní informace obsažené v tokenu. Zobrazí například zobrazované jméno a ID uživatele, datum vypršení platnosti tokenu a řetězec představující samotný přístupový token. Můžete několikrát stisknout tlačítko Spustit Microsoft Graph API a zjistit, že byl stejný token znovu použit pro následné žádosti. Můžete se také podívat, jak se datum vypršení platnosti prodlouží, když MSAL rozhodne, že je čas token obnovit.

Testování kódu

Pokud chcete projekt spustit, vyberte v sadě Visual Studio F5. Zobrazí se vaše aplikace MainWindow .

Při prvním spuštění aplikace a výběru tlačítka Volat rozhraní Microsoft Graph API se zobrazí výzva k přihlášení. K otestování použijte účet Microsoft Entra (pracovní nebo školní účet) nebo účet Microsoft (live.com, outlook.com).

Přihlaste se k aplikaci.

Při prvním přihlášení k aplikaci se zobrazí výzva k udělení souhlasu s povolením přístupu aplikace k vašemu profilu a přihlášení, jak je znázorněno tady:

Zadejte svůj souhlas s přístupem k aplikaci.

Zobrazení výsledků aplikace

Po přihlášení by se měly zobrazit informace o profilu uživatele vrácené voláním rozhraní Microsoft Graph API. Výsledky se zobrazí v okně Výsledky volání rozhraní API. Základní informace o tokenu získaném voláním AcquireTokenInteractive nebo AcquireTokenSilent by měly být viditelné v poli Informace o tokenu. Výsledky obsahují následující vlastnosti:

Vlastnost Formát Popis
Uživatelské jméno user@domain.com Uživatelské jméno, které slouží k identifikaci uživatele.
Platnost tokenu vyprší Datum a čas Čas vypršení platnosti tokenu. MSAL rozšiřuje datum vypršení platnosti obnovením tokenu podle potřeby.

Další informace o oborech a delegovaných oprávněních

Rozhraní Microsoft Graph API vyžaduje obor user.read ke čtení profilu uživatele. Tento obor se automaticky přidá ve výchozím nastavení v každé aplikaci, která je zaregistrovaná na portálu pro registraci aplikací. Další rozhraní API pro Microsoft Graph a vlastní rozhraní API pro váš back-end server mohou vyžadovat více oprávnění. Rozhraní Microsoft Graph API vyžaduje obor Calendars.Read k zobrazení seznamu kalendářů uživatele.

Pro přístup ke kalendářům uživatele v kontextu aplikace přidejte delegovaná oprávnění Calendars.Read k informacím o registraci aplikace. Potom do volání přidejte acquireTokenSilent.

Poznámka:

Když zvýšíte počet oborů, může se uživateli zobrazit výzva k zadání dalších souhlasů.

Nápověda a podpora

Pokud potřebujete pomoc, chcete nahlásit problém nebo se chcete dozvědět o možnostech podpory, přečtěte si nápovědu a podporu pro vývojáře.

Další krok

Přečtěte si další informace o vytváření desktopových aplikací, které volají chráněná webová rozhraní API v naší řadě scénářů s více částmi:

Scénář: Desktopová aplikace, která volá webová rozhraní API

  • Last updated on