Oktatóanyag: Bejelentkezés a felhasználókba, és a Microsoft Graph meghívása Windows megjelenítési alaprendszer (WPF) asztali alkalmazásban

Ebben az oktatóanyagban egy natív Windows Desktop .NET (XAML) alkalmazást fog létrehozni, amely bejelentkezik a felhasználókba, és hozzáférési jogkivonatot kap a Microsoft Graph API meghívásához.

Az útmutató elvégzése után az alkalmazás meghívhat egy személyes fiókokat használó védett API-t (beleértve outlook.com, live.com és másokat). Az alkalmazás a Microsoft Entra-azonosítót használó bármely vállalattól vagy szervezettől származó munkahelyi és iskolai fiókokat is használni fog.

Ebben az oktatóanyagban:

• Windows megjelenítési alaprendszer (WPF) projekt létrehozása a Visual Studióban
• A Microsoft Authentication Library (MSAL) telepítése a .NET-hez
• Az alkalmazás regisztrálása
• Kód hozzáadása a felhasználói bejelentkezés és kijelentkezés támogatásához
• Kód hozzáadása a Microsoft Graph API meghívásához
• Az alkalmazás tesztelése

Előfeltételek

• .NET-keretrendszer 4.8
• Visual Studio 2019

Az útmutató által létrehozott mintaalkalmazás működése

Az útmutatóval létrehozott mintaalkalmazás lehetővé teszi, hogy egy Windows Desktop-alkalmazás lekérdezi a Microsoft Graph API-t, vagy egy webes API-t, amely jogkivonatokat fogad el egy Microsoft Identitásplatform végpontról. Ebben a forgatókönyvben jogkivonatot ad hozzá a HTTP-kérésekhez az Engedélyezés fejlécen keresztül. A Microsoft Authentication Library (MSAL) kezeli a jogkivonatok beszerzését és megújítását.

Jogkivonat-beszerzés kezelése védett webes API-k eléréséhez

A felhasználó hitelesítése után a mintaalkalmazás kap egy jogkivonatot, amellyel lekérdezheti a Microsoft Graph API-t vagy egy webes API-t, amelyet a Microsoft Identitásplatform véd.

Az olyan API-knak, mint a Microsoft Graph, jogkivonatra van szükségük az egyes erőforrásokhoz való hozzáférés engedélyezéséhez. Például jogkivonatra van szükség egy felhasználó profiljának olvasásához, a felhasználó naptárához való hozzáféréshez vagy az e-mailek küldéséhez. Az alkalmazás az MSAL használatával hozzáférési jogkivonatot kérhet ezeknek az erőforrásoknak az API-hatókörök megadásával való eléréséhez. Ezt a hozzáférési jogkivonatot a rendszer hozzáadja a HTTP-engedélyezési fejléchez a védett erőforráson végrehajtott minden híváshoz.

Az MSAL kezeli a hozzáférési jogkivonatok gyorsítótárazását és frissítését, hogy az alkalmazásnak ne kelljen.

NuGet-csomagok

Ez az útmutató a következő NuGet-csomagokat használja:

Könyvtár	Leírás
Microsoft.Identity.Client	Microsoft Authentication Library (MSAL.NET)

A projekt beállítása

Ebben a szakaszban egy új projektet fog létrehozni, amely bemutatja, hogyan integrálható egy Windows Desktop .NET-alkalmazás (XAML) a Microsofttal való bejelentkezéssel, hogy az alkalmazás lekérdezhesse a jogkivonatot igénylő webes API-kat.

A létrehozott alkalmazás megjelenít egy gombot, amely meghívja a Microsoft Graph API-t, egy területet az eredmények megjelenítéséhez, és egy kijelentkezés gombot.

Feljegyzés

Inkább a minta Visual Studio-projektjét szeretné letölteni? Töltse le a projektet, és ugorjon a konfigurációs lépésre a kódminta konfigurálásához a végrehajtás előtt.

Hozza létre az alkalmazást az alábbi lépésekkel:

1. A Visual Studio megnyitása
2. A kezdőablakban válassza az Új projekt létrehozása lehetőséget.
3. A Minden nyelv legördülő listában válassza a C# lehetőséget.
4. Keresse meg és válassza ki a WPF-alkalmazás (.NET-keretrendszer) sablont, majd válassza a Tovább gombot.
5. A Projektnév mezőbe írjon be egy olyan nevet, mint a Win-App-calling-MsGraph.
6. Válasszon egy helyet a projekthez, vagy fogadja el az alapértelmezett beállítást.
7. A Keretrendszerben válassza a .NET-keretrendszer 4.8-at.
8. Válassza a Létrehozás lehetőséget.

MSAL hozzáadása a projekthez

1. A Visual Studióban válassza a Tools (Eszközök) >NuGet Package Manager (NuGet-csomagkezelő)>Package Manager Console (Csomagkezelő konzol) elemet.

2. A Csomagkezelő konzolablakban illessze be a következő Azure PowerShell-parancsot:

   Install-Package Microsoft.Identity.Client -Pre
   

Az alkalmazás regisztrálása

Tipp.

A cikkben szereplő lépések a portáltól függően kissé eltérhetnek.

Az alkalmazás regisztrálásához és konfigurálásához kövesse az alábbi lépéseket:

1. Jelentkezzen be a Microsoft Entra felügyeleti központba legalább alkalmazásfejlesztőként.
2. Ha több bérlőhöz is hozzáfér, a felső menü Gépház ikonjávalválthat arra a bérlőre, amelyben regisztrálni szeretné az alkalmazást a Könyvtárak + előfizetések menüből.
3. Keresse meg az identitásalkalmazásokat>> Alkalmazásregisztrációk.
4. Új regisztráció kiválasztása.
5. Adja meg például Win-App-calling-MsGraphaz alkalmazás nevét. Előfordulhat, hogy az alkalmazás felhasználói látják ezt a nevet, és később módosíthatja.
6. A Támogatott fióktípusok szakaszban válassza a Bármely szervezeti könyvtárban (Bármely Microsoft Entra címtár – Több-bérlős) és a személyes Microsoft-fiókokban (pl. Skype, Xbox) található Fiókok lehetőséget.
7. Válassza ki a pénztárgépet.
8. A Kezelés területen válassza a Hitelesítés>hozzáadása platformot.
9. Válassza ki a Mobil- és asztali alkalmazásokat.
10. Az Átirányítási URI-k szakaszban válassza a lehetőséget https://login.microsoftonline.com/common/oauth2/nativeclient.
11. Válassza a Konfigurálás lehetőséget.

A kód hozzáadása az MSAL inicializálásához

Ebben a lépésben létrehoz egy osztályt az MSAL-sel való interakció kezelésére, például a jogkivonatok kezelésére.

1. Nyissa meg a App.xaml.cs fájlt, majd adja hozzá az MSAL hivatkozását az osztályhoz:

   using Microsoft.Identity.Client;
   

2. Frissítse az alkalmazásosztályt a következőre:

   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; } }
   }
   

Az alkalmazás felhasználói felületének létrehozása

Ez a szakasz bemutatja, hogyan kérdezhet le egy alkalmazás védett háttérkiszolgálót, például a Microsoft Graphot.

A mainWindow.xaml fájl automatikusan létrejön a projektsablon részeként. Nyissa meg ezt a fájlt, majd cserélje le az alkalmazás Rács> csomópontját <a következő kódra:

<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>

Jogkivonat lekérése a Microsoft Graph API-hoz az MSAL használatával

Ebben a szakaszban az MSAL használatával szerez be egy jogkivonatot a Microsoft Graph API-hoz.

1. A MainWindow.xaml.cs fájlban adja hozzá az MSAL-ra vonatkozó hivatkozást az osztályhoz:

   using Microsoft.Identity.Client;
   

2. Cserélje le az MainWindow osztálykódot a következő kódra:

   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;
           }
       }
       }
   

További információ

Felhasználói jogkivonat interaktív lekérése

A metódus meghívása AcquireTokenInteractive egy olyan ablakban jelenik meg, amely felszólítja a felhasználókat a bejelentkezésre. Az alkalmazások általában megkövetelik, hogy a felhasználók interaktívan jelentkezzenek be, amikor először kell hozzáférniük egy védett erőforráshoz. Előfordulhat, hogy be kell jelentkezniük, ha egy jogkivonat beszerzéséhez szükséges csendes művelet meghiúsul (például ha egy felhasználó jelszava lejárt).

Felhasználói jogkivonat csendes beszerzése

A AcquireTokenSilent metódus felhasználói beavatkozás nélkül kezeli a jogkivonatok beszerzését és megújítását. Az első AcquireTokenSilent végrehajtás után AcquireTokenInteractive a szokásos módszer a védett erőforrásokhoz hozzáférő jogkivonatok lekérésére a későbbi hívásokhoz, mivel a jogkivonatok kérésére vagy megújítására irányuló hívások csendesen zajosak.

Végül előfordulhat, hogy a AcquireTokenSilent metódus sikertelen lesz. A hiba oka lehet, hogy a felhasználó kijelentkezett vagy módosította a jelszavát egy másik eszközön. Ha az MSAL azt észleli, hogy a probléma interaktív művelet megkövetelésével megoldható, kivételt MsalUiRequiredException jelez. Az alkalmazás kétféleképpen tudja kezelni ezt a kivételt:

• Azonnal hívást AcquireTokenInteractive kezdeményezhet. Ez a hívás arra kéri a felhasználót, hogy jelentkezzen be. Ezt a mintát olyan online alkalmazásokban használják, ahol nincs elérhető offline tartalom a felhasználó számára. A beállítás által létrehozott minta ezt a mintát követi, amely a minta első végrehajtásakor látható működés közben.

• Mivel egyetlen felhasználó sem használta az alkalmazást, PublicClientApp.Users.FirstOrDefault() null értéket tartalmaz, és MsalUiRequiredException kivételt eredményez.

• A mintában lévő kód ezután hívással AcquireTokenInteractivekezeli a kivételt, ami arra kéri a felhasználót, hogy jelentkezzen be.

• Ehelyett vizuális jelzést jeleníthet meg a felhasználóknak arról, hogy interaktív bejelentkezésre van szükség, hogy kiválaszthassák a megfelelő időpontot a bejelentkezéshez. Vagy az alkalmazás később újra próbálkozhat AcquireTokenSilent . Ezt a mintát gyakran használják, ha a felhasználók más alkalmazásfunkciót is használhatnak megszakítás nélkül. Ha például offline tartalom érhető el az alkalmazásban. Ebben az esetben a felhasználók eldönthetik, hogy mikor szeretnének bejelentkezni a védett erőforrás eléréséhez vagy az elavult adatok frissítéséhez. Másik lehetőségként az alkalmazás dönthet úgy is, hogy újra próbálkozik AcquireTokenSilent , ha a hálózat ideiglenesen nem érhető el.

A Microsoft Graph API meghívása az imént beszerzett jogkivonat használatával

Adja hozzá a következő új metódust a sajátjához MainWindow.xaml.cs. A metódus a Graph API-val kapcsolatos kérések hitelesítése fejléc használatával történik GET :

/// <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();
    }
}

További információ a REST-hívások védett API-val való indításáról

Ebben a mintaalkalmazásban a GetHttpContentWithToken módszerrel HTTP-kérést GET hajthat létre egy jogkivonatot igénylő védett erőforráson, majd visszaadja a tartalmat a hívónak. Ez a metódus hozzáadja a beszerzett jogkivonatot a HTTP-engedélyezési fejléchez. Ebben a mintában az erőforrás a Microsoft Graph API me végpontja, amely megjeleníti a felhasználó profiladatait.

Felhasználó kijelentkezési módszerének hozzáadása

Felhasználó kijelentkezéséhez adja hozzá a következő metódust a MainWindow.xaml.cs fájlhoz:

/// <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}";
        }
    }
}

További információ a felhasználói kijelentkezésről

A SignOutButton_Click metódus eltávolítja a felhasználókat az MSAL felhasználói gyorsítótárából, amely gyakorlatilag arra utasítja az MSAL-t, hogy felejtse el az aktuális felhasználót, hogy a jogkivonat beszerzésére irányuló jövőbeli kérés csak akkor legyen sikeres, ha interaktívvá lett téve.

Bár a mintában szereplő alkalmazás támogatja az önálló felhasználókat, az MSAL olyan forgatókönyveket támogat, amelyekbe egyszerre több fiók is bejelentkezhet. Ilyen például egy olyan e-mail-alkalmazás, amelyben egy felhasználó több fiókkal rendelkezik.

Alapszintű jogkivonat-információk megjelenítése

A jogkivonat alapvető információinak megjelenítéséhez adja hozzá a következő metódust a MainWindow.xaml.cs fájlhoz:

/// <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;
    }
}

További információ

A Microsoft Graph API meghívásához használt hozzáférési jogkivonaton kívül, miután a felhasználó bejelentkezett, az MSAL egy azonosító jogkivonatot is beszerez. Ez a jogkivonat a felhasználók számára lényeges információk egy kis részét tartalmazza. A DisplayBasicTokenInfo metódus megjeleníti a jogkivonatban található alapvető információkat. Megjeleníti például a felhasználó megjelenítendő nevét és azonosítóját, valamint a jogkivonat lejárati dátumát és magát a hozzáférési jogkivonatot képviselő sztringet. Többször is kiválaszthatja a Microsoft Graph API meghívása gombot, és láthatja, hogy ugyanazt a jogkivonatot újra felhasználták a későbbi kérésekhez. Azt is láthatja, hogy a lejárati dátum meghosszabbodik, amikor az MSAL úgy dönt, hogy ideje megújítani a jogkivonatot.

A kód tesztelése

A projekt futtatásához a Visual Studióban válassza az F5 lehetőséget. A MainWindow alkalmazás az alábbi módon jelenik meg:

Amikor először futtatja az alkalmazást, és a Microsoft Graph API meghívása gombra kattint, a rendszer kérni fogja a bejelentkezést. Microsoft Entra-fiók (munkahelyi vagy iskolai fiók) vagy Microsoft-fiók (live.com, outlook.com) használatával tesztelheti.

Hozzájárulás megadása az alkalmazáshoz való hozzáféréshez

Amikor első alkalommal jelentkezik be az alkalmazásba, a rendszer arra is kéri, hogy adjon hozzájárulást ahhoz, hogy az alkalmazás hozzáférhessen a profiljához, és bejelentkezhessen, ahogy az itt látható:

Alkalmazás eredményeinek megtekintése

A bejelentkezés után látnia kell a Microsoft Graph API hívása által visszaadott felhasználói profiladatokat. Az eredmények az API-hívás eredményei mezőben jelennek meg. A jogkivonattal kapcsolatos alapvető információk, amelyeket a hívással AcquireTokenInteractive szereztek be, vagy AcquireTokenSilent amelyek a Jogkivonat adatai mezőben láthatók. Az eredmények a következő tulajdonságokat tartalmazzák:

Tulajdonság	Formátum	Leírás
Felhasználónév	user@domain.com	A felhasználó azonosításához használt felhasználónév.
A jogkivonat lejár	Dátum/idő	A jogkivonat lejáratának időpontja. Az MSAL a jogkivonat szükség szerinti megújításával meghosszabbítja a lejárati dátumot.

További információ a hatókörökről és a delegált engedélyekről

A Microsoft Graph API-hoz a user.read hatókörnek be kell olvasnia egy felhasználó profilját. Ez a hatókör alapértelmezés szerint automatikusan hozzáadódik minden olyan alkalmazáshoz, amely regisztrálva van az alkalmazásregisztrációs portálon. A Microsoft Graph egyéb API-jai, valamint a háttérkiszolgáló egyéni API-jai további hatóköröket igényelhetnek. A Microsoft Graph API-hoz a Calendars.Read hatókörre van szükség a felhasználó naptárainak listázásához.

Ha egy alkalmazás kontextusában szeretné elérni a felhasználó naptárait, adja hozzá a Calendars.Read delegált engedélyt az alkalmazásregisztrációs adatokhoz. Ezután adja hozzá a Calendars.Read hatókört a acquireTokenSilent híváshoz.

Feljegyzés

Előfordulhat, hogy a felhasználó további hozzájárulást kér a hatókörök számának növelésekor.

Súgó és támogatás

Ha segítségre van szüksége, szeretne jelentést készíteni egy problémáról, vagy szeretne többet megtudni a támogatási lehetőségekről, olvassa el a súgót és a fejlesztők támogatását.

Következő lépések

További információ a védett webes API-kat hívó asztali alkalmazások készítéséről a többrészes forgatókönyv-sorozatunkban:

Forgatókönyv: Webes API-kat hívó asztali alkalmazás