Sdílet prostřednictvím

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

  • Článek

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:

  • 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

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 desktopovou aplikaci pro Windows, která se dotazuje rozhraní Microsoft Graph API nebo webového rozhraní API, které přijímá tokeny z koncového bodu platformy Microsoft Identity Platform. 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 Microsoft Authentication Library (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:

Raději si raději stáhněte projekt sady Visual Studio této ukázky? Stáhněte si projekt a přejděte ke kroku Konfigurace, abyste před spuštěním nakonfigurovali ukázku kódu.

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

  1. Otevřete sadu 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řidání KNIHOVNY MSAL do 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

Registrace aplikace

Tip

Postup v tomto článku se může mírně lišit v závislosti na portálu, od který začínáte.

Aplikaci zaregistrujete a nakonfigurujete takto:

  1. Přihlaste se do Centra pro správu Microsoft Entra jako alespoň vývojář aplikací.
  2. Pokud máte přístup k více tenantům, pomocí ikony Nastavení v horní nabídce přepněte na tenanta, ve kterém chcete aplikaci zaregistrovat z nabídky Adresáře a předplatná.
  3. Přejděte k aplikacím> identit>Registrace aplikací.
  4. Vyberte Nová registrace.
  5. Zadejte název aplikace, například Win-App-calling-MsGraph. Uživatelé vaší aplikace můžou vidět tento název a později ho můžete změnit.
  6. V části Podporované typy účtů vyberte Účty v libovolném organizačním adresáři (libovolný adresář Microsoft Entra – Víceklient) a osobní účty Microsoft (např. Skype, Xbox).
  7. Vyberte Zaregistrovat.
  8. V části Spravovat vyberte Možnost Přidat platformu pro ověřování>.
  9. Vyberte Mobilní a desktopové aplikace.
  10. V části Identifikátory URI pro přesměrování vyberte https://login.microsoftonline.com/common/oauth2/nativeclient.
  11. Vyberte Konfigurovat.

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> vaší aplikace <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>

Získání tokenu pro rozhraní Microsoft Graph API pomocí KNIHOVNY MSAL

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 AcquireTokenInteractive prvním AcquireTokenSilent spuštění je obvyklou metodou, která se používá k získání tokenů, které přistupují k chráněným prostředkům pro následné volání, protože volání pro vyžádání nebo obnovení tokenů jsou bezobslužná.

Nakonec může dojít k AcquireTokenSilent selhání metody. 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 aplikace nepoužil žádný uživatel, PublicClientApp.Users.FirstOrDefault() obsahuje hodnotu null a MsalUiRequiredException je vyvolán 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 se aplikace může opakovat AcquireTokenSilent 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í, až bude dočasně nedostupná.

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

Přidejte do svého MainWindow.xaml.cssouboru 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 SignOutButton_Click metoda odebere uživatele z mezipaměti uživatelů MSAL, což v podstatě informuje MSAL, aby zapomněl aktuálního uživatele, aby budoucí požadavek na získání tokenu byl úspěšný pouze v případě, že bude interaktivní.

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 vybrat tlačítko Volat rozhraní Microsoft Graph API několikrát a zjistit, že se stejný token znovu použil pro následné žádosti. Můžete se také podívat na datum vypršení platnosti, které se 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 poli 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ší DateTime Č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-endový server můžou vyžadovat více oborů. 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 acquireTokenSilent volání přidejte obor Calendars.Read.

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