Zelfstudie: Gebruikers aanmelden en Microsoft Graph aanroepen in de bureaublad-app Windows Presentation Foundation (WPF)

  • Artikel

In deze zelfstudie bouwt u een systeemeigen Windows Desktop .NET-app (XAML) waarmee gebruikers worden aangemeld en een toegangstoken wordt opgehaald om de Microsoft Graph API aan te roepen.

Wanneer u de handleiding hebt voltooid, kan uw toepassing een beveiligde API aanroepen die gebruikmaakt van persoonlijke accounts (inclusief outlook.com, live.com en andere). De toepassing gebruikt ook werk- en schoolaccounts van een bedrijf of organisatie die gebruikmaakt van Microsoft Entra-id.

In deze zelfstudie:

  • Een Windows Presentation Foundation-project (WPF) maken in Visual Studio
  • Microsoft Authentication Library (MSAL) voor .NET installeren
  • Registreer de toepassing
  • Code toevoegen voor de ondersteuning van het aan- en afmelden van gebruikers
  • Code toevoegen om de Microsoft Graph API aan te roepen
  • De app testen

Vereisten

Hoe de voorbeeld-app werkt die wordt gegenereerd in deze gids

Screenshot of how the sample app generated by this tutorial works.

Met de voorbeeldtoepassing die u met deze handleiding maakt, wordt een Windows-bureaubladtoepassing ingeschakeld waarmee een query wordt uitgevoerd op de Microsoft Graph API of een web-API die tokens accepteert van een Microsoft Identity Platform-eindpunt. Voor dit scenario voegt u een token toe aan HTTP-aanvragen via de autorisatie-header. Het verkrijgen en vernieuwen van tokens wordt afgehandeld via MSAL (Microsoft Authentication Library).

Het afhandelen van tokens voor toegang tot beveiligde web-API's

Nadat de gebruiker is geverifieerd, ontvangt de voorbeeldtoepassing een token dat u kunt gebruiken om een query uit te voeren op Microsoft Graph API of een web-API die wordt beveiligd door het Microsoft Identity Platform.

API's zoals Microsoft Graph vereisen een token om toegang tot specifieke resources toe te staan. Een token is bijvoorbeeld vereist om het profiel van een gebruiker te lezen, toegang te krijgen tot de agenda van een gebruiker of e-mail te verzenden. Uw toepassing kan een toegangstoken aanvragen met behulp van MSAL om toegang te krijgen tot deze resources door de API-bereiken op te geven. Deze toegangstoken wordt vervolgens toegevoegd aan de HTTP-autorisatie-header voor elke aanroep die wordt gedaan voor de beveiligde resource.

MSAL beheert de cachebewerkingen en vernieuwt toegangstokens voor u, zodat uw toepassing dat niet hoeft te doen.

NuGet-pakketten

In deze handleiding wordt gebruikgemaakt van de volgende NuGet-pakketten:

Bibliotheek Beschrijving
Microsoft.Identity.Client Microsoft Authentication Library (MSAL.NET)

Uw project instellen

In deze sectie maakt u een nieuw project om te laten zien hoe u een Windows Desktop .NET-toepassing (XAML) integreert met Aanmelden met Microsoft , zodat de toepassing web-API's kan opvragen waarvoor een token is vereist.

In de toepassing die u maakt, wordt een knop weergegeven waarmee de Microsoft Graph API, een gebied voor het weergeven van de resultaten en een afmeldingsknop wordt aangeroepen.

Notitie

Wilt u liever het Visual Studio-project uit dit voorbeeld downloaden? Download een project en ga verder met de configuratiestap om het codevoorbeeld te configureren voordat u het uitvoert.

Maak de toepassing met behulp van de volgende stappen:

  1. Open Visual Studio
  2. Selecteer een nieuw project maken in het startvenster.
  3. Selecteer C# in de vervolgkeuzelijst Alle talen.
  4. Zoek en kies de wpf-appsjabloon (.NET Framework) en selecteer vervolgens Volgende.
  5. Voer in het vak Projectnaam een naam in, zoals Win-App-calling-MsGraph.
  6. Kies een locatie voor het project of accepteer de standaardoptie.
  7. Selecteer .NET Framework 4.8 in het framework.
  8. Selecteer Maken.

MSAL toevoegen aan uw project

  1. Selecteer in Visual Studio de optie Extra>NuGet-pakketbeheer>Console voor pakketbeheer.

  2. Plak de volgende Azure PowerShell-opdracht in het venster Pakketbeheerconsole:

    Install-Package Microsoft.Identity.Client -Pre

Uw toepassing registreren

Tip

Stappen in dit artikel kunnen enigszins variëren op basis van de portal waaruit u begint.

Volg deze stappen om uw toepassing te registreren en te configureren:

  1. Meld u als toepassingsontwikkelaar aan bij het Microsoft Entra-beheercentrum.
  2. Als u toegang hebt tot meerdere tenants, gebruikt u het pictogram Instellingen in het bovenste menu om over te schakelen naar de tenant waarin u de toepassing wilt registreren in het menu Mappen en abonnementen.
  3. Blader naar identiteitstoepassingen>> App-registraties.
  4. Selecteer Nieuwe registratie.
  5. Voer een Naam in voor de toepassing, bijvoorbeeld Win-App-calling-MsGraph. Gebruikers van uw app kunnen de naam zien. U kunt deze later wijzigen.
  6. Selecteer in de sectie Ondersteunde accounttypen accounts in een organisatiedirectory (Elke Microsoft Entra-directory - Multitenant) en persoonlijke Microsoft-accounts (bijvoorbeeld Skype, Xbox).
  7. Selecteer Registreren.
  8. Selecteer onder Beheren achtereenvolgens Verificatie>Een platform toevoegen.
  9. Selecteer Mobiele toepassingen en desktoptoepassingen.
  10. Selecteer https://login.microsoftonline.com/common/oauth2/nativeclient in de sectie Omleidings-URI's.
  11. Selecteer Configureren.

De code toevoegen om MSAL te initialiseren

In deze stap maakt u een klasse voor het afhandelen van interactie met MSAL, zoals het afhandelen van tokens.

  1. Open het bestand App.xaml.cs en voeg vervolgens de verwijzing voor MSAL toe aan de klasse:

    using Microsoft.Identity.Client;

  2. Werk de app-klasse bij naar het volgende:

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

De gebruikersinterface van de toepassing maken

In deze sectie wordt uitgelegd hoe een toepassing een query kan uitvoeren op een beveiligde back-endserver, zoals Microsoft Graph.

Er wordt automatisch een MainWindow.xaml-bestand gemaakt als onderdeel van uw projectsjabloon. Open dit bestand en vervang het knooppunt <Grid> (Raster) van uw toepassing door de volgende code:

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

Met behulp van MSAL een token ophalen voor de Microsoft Graph API

In deze sectie gebruikt u MSAL om een token op te halen voor de Microsoft Graph API.

  1. Open het bestand MainWindow.xaml.cs en voeg de verwijzing voor MSAL toe aan de klasse:

    using Microsoft.Identity.Client;

  2. Vervang de MainWindow klassecode door de volgende code:

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

Meer informatie

Een gebruikerstoken interactief ophalen

De methode AcquireTokenInteractive aanroepen, resulteert in een venster waarin de gebruiker wordt gevraagd zich aan te melden. De eerste keer moeten gebruikers zich in toepassingen doorgaans interactief aanmelden om toegang te krijgen tot een beveiligde resource. Ze moeten zich mogelijk ook aanmelden wanneer een stille bewerking om een token te verkrijgen mislukt (bijvoorbeeld wanneer het wachtwoord van een gebruiker is verlopen).

Een gebruikerstoken op de achtergrond ophalen

Met de methode AcquireTokenSilent wordt het verkrijgen en vernieuwen van tokens verwerkt zonder tussenkomst van de gebruiker. Nadat AcquireTokenInteractive voor de eerste keer is uitgevoerd, is AcquireTokenSilent de gebruikelijke methode voor het verkrijgen van tokens die toegang hebben tot beveiligde resources voor volgende aanroepen, omdat aanroepen voor het aanvragen of vernieuwen van tokens op de achtergrond worden uitgevoerd.

Uiteindelijk kan de AcquireTokenSilent methode mislukken. De mislukking kan het gevolg zijn van een gebruiker die zich heeft afgemeld of die het wachtwoord op een ander apparaat heeft gewijzigd. Wanneer MSAL detecteert dat het probleem kan worden opgelost door een interactieve actie te vereisen, wordt een uitzondering MsalUiRequiredException gestart. Uw toepassing kan deze uitzondering op twee manieren afhandelen:

  • De toepassing kan onmiddellijk een aanroep voor AcquireTokenInteractive uitvoeren. Met deze aanroep wordt de gebruiker gevraagd zich aan te melden. Dit patroon wordt gebruikt in onlinetoepassingen waarbij er geen offline inhoud beschikbaar is voor de gebruiker. Het voorbeeld dat door deze installatie wordt gegenereerd, volgt dit patroon, dat de eerste keer dat u het voorbeeld uitvoert, wordt weergegeven in actie.

  • Omdat geen enkele gebruiker de toepassing heeft gebruikt, bevat PublicClientApp.Users.FirstOrDefault() een null-waarde en wordt een uitzondering MsalUiRequiredException gegenereerd.

  • De code in het voorbeeld handelt de uitzondering vervolgens af door AcquireTokenInteractive aan te roepen, waardoor de gebruiker wordt gevraagd zich aan te melden.

  • Er kan in plaats daarvan een visuele indicatie aan gebruikers worden gegeven die aangeeft dat een interactieve aanmelding is vereist, zodat ze het juiste tijdstip kunnen selecteren om zich aan te melden. Of de toepassing kan later opnieuw proberen om AcquireTokenSilent uit te voeren. Dit patroon wordt vaak gebruikt wanneer gebruikers zonder onderbreking andere toepassingsfunctionaliteit kunnen gebruiken. Bijvoorbeeld wanneer offline-inhoud beschikbaar is in de toepassing. In dat geval kan de gebruiker beslissen wanneer hij of zij zich wil aanmelden om toegang te krijgen tot de beveiligde resource, of om de verouderde informatie te vernieuwen. De toepassing kan er ook voor kiezen om AcquireTokenSilent opnieuw uit te voeren wanneer het netwerk wordt hersteld nadat het tijdelijk niet beschikbaar was.

De Microsoft Graph API aanroepen met behulp van het token dat u zojuist hebt verkregen

Voeg de volgende nieuwe methode toe aan uw MainWindow.xaml.cs. De methode wordt gebruikt om een GET-aanvraag uit te voeren voor de Graph API met behulp van een autorisatie-header:

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

Meer informatie over het maken van een REST-aanroep voor een beveiligde API

In deze voorbeeldtoepassing gaat u de methode GetHttpContentWithToken gebruiken om een HTTP GET-aanvraag uit te voeren voor een beveiligde bron waarvoor een token is vereist en de inhoud vervolgens naar de aanvrager wordt geretourneerd. Met deze methode wordt het verkregen token toegevoegd in de HTTP-autorisatie-header. In dit voorbeeld is de resource het Microsoft Graph API-eindpunt me, waarmee de profielgegevens van de gebruiker worden weergegeven.

Een methode voor het afmelden van een gebruiker toevoegen

Als u de gebruiker wilt afmelden, voegt u de volgende methode toe aan het bestand MainWindow.xaml.cs:

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

Meer informatie over het afmelden van gebruikers

De SignOutButton_Click methode verwijdert gebruikers uit de MSAL-gebruikerscache, waardoor MSAL in feite de huidige gebruiker moet vergeten, zodat een toekomstige aanvraag om een token te verkrijgen alleen slaagt als het is gemaakt om interactief te zijn.

Hoewel de toepassing in dit voorbeeld afzonderlijke gebruikers ondersteunt, ondersteunt MSAL scenario's waarbij meerdere accounts tegelijkertijd kunnen worden aangemeld. Een voorbeeld hiervan is een e-mailtoepassing waarbij een gebruiker meerdere accounts heeft.

Basisinformatie over het token weergeven

Voeg de volgende methode toe aan het bestand MainWindow.xaml.cs om basisinformatie over het token weer te geven:

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

Meer informatie

Naast het toegangstoken dat wordt gebruikt om de Microsoft Graph API aan te roepen, wordt met MSAL ook een id-token opgehaald nadat de gebruiker zich heeft aangemeld. Dit token bevat een kleine subset met informatie die relevant is voor gebruikers. Met de methode DisplayBasicTokenInfo wordt de basis informatie weergegeven die in het token is opgenomen. Zo worden bijvoorbeeld de weergavenaam en de id van de gebruiker weergegeven, evenals de vervaldatum van het token en de tekenreeks die het toegangstoken zelf vertegenwoordigt. U kunt de knop Microsoft Graph API aanroepen selecteren, en zien dat hetzelfde token opnieuw is gebruikt voor latere aanvragen. U kunt ook zien dat de vervaldatum wordt verlengd wanneer MSAL beslist dat het tijd is om het token te verlengen.

Uw code testen

Druk op F5 in Visual Studio om uw project uit te voeren. De MainWindow van uw toepassing wordt weergegeven, zoals hier wordt getoond:

Test your application.

De eerste keer dat u de toepassing uitvoert en de knop Microsoft Graph API aanroepen selecteert, wordt u gevraagd om u aan te melden. Gebruik een Microsoft Entra-account (werk- of schoolaccount) of een Microsoft-account (live.com, outlook.com) om het te testen.

Sign in to the application.

De eerste keer dat u zich bij uw toepassing aanmeldt, wordt u ook gevraagd om de toepassing toestemming te geven om uw profiel te openen en u aan te melden, zoals hier wordt weergegeven:

Provide your consent for application access.

Resultaten van de toepassing weergeven

Nadat u zich hebt aangemeld, zouden de gebruikersprofielgegevens die worden geretourneerd door de aanroep aan de Microsoft Graph-API moeten worden weergegeven. De resultaten worden weergegeven in het vak met de resultaten van de API-aanroep. Basisgegevens van het token dat is verkregen via de aanroep aan AcquireTokenInteractive of AcquireTokenSilent, moeten zichtbaar zijn in het vak Tokengegevens. De resultaten bevatten de volgende eigenschappen:

Eigenschappen Indeling Beschrijving
Gebruikersnaam user@domain.com De gebruikersnaam die is gebruikt om de gebruiker te identificeren.
Vervaldatum van token Datum en tijd Het moment waarop het token verloopt. MSAL verlengt de vervaldatum door het token wanneer nodig te vernieuwen.

Meer informatie over bereiken en gedelegeerde machtigingen

De Microsoft Graph API vereist het bereik user.read om het profiel van een gebruiker te lezen. Dit bereik wordt standaard automatisch toegevoegd in elke toepassing die is geregistreerd in de toepassingsregistratieportal. Overige API's voor Microsoft Graph, evenals aangepaste API's voor uw back-endserver, vereisen mogelijk aanvullende bereiken. De Microsoft Graph API vereist het bereik Calendars.Read om de agenda's van de gebruiker weer te geven.

Als u toegang wilt krijgen tot de agenda van de gebruiker in de context van een toepassing, voegt u de gedelegeerde toestemming Calendars.Read toe aan de toepassingsregistratiegegevens. Voeg vervolgens het bereik Calendars.Read toe aan de oproep acquireTokenSilent.

Notitie

De gebruiker wordt mogelijk gevraagd om aanvullende machtigingen te geven naarmate u het aantal bereiken verhoogt.

Help en ondersteuning

Als u hulp nodig hebt, een probleem wilt melden of meer informatie wilt over uw ondersteuningsopties, raadpleegt u Hulp en ondersteuning voor ontwikkelaars.

Volgende stappen

Meer informatie over het bouwen van bureaublad-apps die beveiligde web-API's aanroepen in deze reeks met meerdere scenario's:

Scenario: Desktop-app die web-API's aanroept