Поделиться через

Руководство. Вход пользователей в приложение .NET MAUI с помощью внешнего клиента

Применимо: Белый круг с серым символом X. Арендаторы рабочей силы Зеленый круг с символом белой галочки. Внешние арендаторы (узнать больше)

В этом руководстве представлена последняя часть серии, демонстрирующая создание кода входа и выхода в оболочку .NET Multi-platform App UI (.NET MAUI) и запуск приложения на платформе Windows. В Части 1 этой серии вы создали .NET MAUI shell-приложение, добавили поддержку MSAL SDK с помощью вспомогательных классов MSAL, установили необходимые библиотеки и включили ресурс изображения. В этом последнем шаге показано, как добавить код входа и выхода в оболочку .NET MAUI и запустить приложение на платформе Windows.

Изучив это руководство, вы:

  • Добавьте код входа и выхода.
  • Измените оболочку приложения.
  • Добавьте код для конкретной платформы.
  • Добавьте параметры приложения.
  • Запустите и проверьте приложение оболочки .NET MAUI.

Предпосылки

Добавление кода входа и выхода

Пользовательский интерфейс приложения .NET MAUI создается из объектов, которые сопоставляются с собственными элементами управления каждой целевой платформы. Основными группами элементов управления, используемыми для создания пользовательского интерфейса приложения .NET MAUI, являются страницы, макеты и представления.

Добавление главной страницы представления

Следующие шаги организуют наш код так, чтобы main view был определен.

  1. Удалите MainPage.xaml и MainPage.xaml.cs из проекта, они больше не нужны. В области Обозреватель решений найдите запись для MainPage.xaml, щелкните ее правой кнопкой мыши и выберите "Удалить".

  2. Щелкните правой кнопкой мыши проект SignInMaui и выберите "Добавить>новую папку". Назовите папку Views.

  3. Щелкните правой кнопкой мыши на Views.

  4. Выберите "Добавить>новый элемент...".

  5. Выберите .NET MAUI в списке шаблонов.

  6. Выберите шаблон .NET MAUI ContentPage (XAML). Назовите файл MainView.xaml.

  7. Выберите Добавить.

  8. Файл MainView.xaml откроется на новой вкладке документа, отображая всю разметку XAML, представляющую пользовательский интерфейс страницы. Замените разметку XAML следующей разметкой:

    <?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="SignInMaui.Views.MainView"
             Title="Microsoft Entra External ID"
             >
    <Shell.BackButtonBehavior>
        <BackButtonBehavior IsVisible="False" IsEnabled="False" />
    </Shell.BackButtonBehavior>

    <ScrollView>
        <VerticalStackLayout 
            Spacing="25" 
            Padding="30,0" 
            VerticalOptions="Center">

            <Image
                Source="external_id.png"
                SemanticProperties.Description="External ID"
                HeightRequest="200"
                HorizontalOptions="Center" />

            <Label 
                Text="CIAM"
                SemanticProperties.HeadingLevel="Level1"
                FontSize="26"
                HorizontalOptions="Center" />

            <Label 
                Text="MAUI sample"
                SemanticProperties.HeadingLevel="Level1"
                FontSize="26"
                HorizontalOptions="Center" />

            <Button 
                x:Name="SignInButton"
                Text="Sign In"
                SemanticProperties.Hint="Sign In"
                Clicked="OnSignInClicked"
                HorizontalOptions="Center"
                IsEnabled="False"/>

        </VerticalStackLayout>
    </ScrollView>
 
</ContentPage>

  9. Сохраните файл.

    Давайте разберем ключевые части элементов управления XAML, размещенные на странице:

    • <ContentPage> — корневой объект для класса MainView.
    • <VerticalStackLayout> является дочерним объектом ContentPage. Этот контрол управления макетом упорядочивает дочерние элементы по вертикали, один за другим.
    • <Image> отображает изображение, в данном случае используется azureactive_directory.png_, скачанное ранее.
    • <Label> управляет отображением текста.
    • Пользователь может нажать <Button>, чтобы вызвать событие Clicked. Вы можете запустить код в ответ на Clicked событие.
    • Clicked="OnSignInClicked" событие кнопки Clicked назначается обработчику событий OnSignInClicked, который будет определен в файле программного кода. Этот код будет создан на следующем шаге.

Обработайте событие OnSignInClicked

Следующим шагом является добавление кода для события кнопки Clicked .

  1. В области обозревателя решений Visual Studio разверните файл MainView.xaml, чтобы отобразить его файл кода MainView.xaml.cs. Откройте MainView.xaml.cs и замените содержимое файла следующим кодом:

    // Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License.

using SignInMaui.MSALClient;
using Microsoft.Identity.Client;

namespace SignInMaui.Views
{
    public partial class MainView : ContentPage
    {
        public MainView()
        {
            InitializeComponent();

            IAccount cachedUserAccount = PublicClientSingleton.Instance.MSALClientHelper.FetchSignedInUserFromCache().Result;

            _ = Dispatcher.DispatchAsync(async () =>
            {
                if (cachedUserAccount == null)
                {
                    SignInButton.IsEnabled = true;
                }
                else
                {
                    await Shell.Current.GoToAsync("claimsview");
                }
            });
        }

        private async void OnSignInClicked(object sender, EventArgs e)
        {
            await PublicClientSingleton.Instance.AcquireTokenSilentAsync();
            await Shell.Current.GoToAsync("claimsview");
        }
        protected override bool OnBackButtonPressed() { return true; }

    }
}

Класс MainView — это страница содержимого, отвечающая за отображение основного представления приложения. В конструкторе он извлекает кэшированную учетную запись пользователя с помощью MSALClientHelper из экземпляра PublicClientSingleton и включает кнопку входа, если кэшированная учетная запись пользователя не найдена.

При нажатии кнопки входа вызывается метод AcquireTokenSilentAsync, чтобы автоматически получить маркер, и затем осуществляется переход на страницу claimsview с помощью метода Shell.Current.GoToAsync. Кроме того, метод OnBackButtonPressed переопределяется так, чтобы возвращать значение true, указывая, что кнопка "Назад" отключена для этого просмотра.

Добавление страницы представления утверждений

Следующие шаги упорядочат код таким образом, чтобы была определена страница ClaimsView. На странице будут отображаться утверждения пользователя, найденные в токене идентификации.

  1. В области Обозреватель решений Visual Studio щелкните правой кнопкой мыши по Views.

  2. Выберите "Добавить>новый элемент...".

  3. Выберите .NET MAUI в списке шаблонов.

  4. Выберите шаблон .NET MAUI ContentPage (XAML). Назовите файл ClaimsView.xaml.

  5. Выберите Добавить.

  6. Файл ClaimsView.xaml откроется на новой вкладке документа, отображая всю разметку XAML, представляющую пользовательский интерфейс страницы. Замените разметку XAML следующей разметкой:

    <?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="SignInMaui.Views.ClaimsView"
             Title="ID Token View">
    <Shell.BackButtonBehavior>
        <BackButtonBehavior IsVisible="False" IsEnabled="False" />
    </Shell.BackButtonBehavior>
    <VerticalStackLayout>
        <Label 
            Text="CIAM"
            FontSize="26"
            HorizontalOptions="Center" />
        <Label 
            Text="MAUI sample"
            FontSize="26"
            Padding="0,0,0,20"
            HorizontalOptions="Center" />

        <Label 
            Padding="0,20,0,0"
            VerticalOptions="Center" 
            HorizontalOptions="Center"
            FontSize="18"
            Text="Claims found in ID token"
            />
        <ListView ItemsSource="{Binding IdTokenClaims}"
                  x:Name="Claims">
            <ListView.ItemTemplate>
                <DataTemplate>
                    <ViewCell>
                        <Grid Padding="0, 0, 0, 0">
                            <Label Grid.Column="1" 
                                   Text="{Binding}" 
                                   HorizontalOptions="Center" />
                        </Grid>
                    </ViewCell>
                </DataTemplate>
            </ListView.ItemTemplate>
        </ListView>
        <Button
            x:Name="SignOutButton"
            Text="Sign Out"
            HorizontalOptions="Center"
            Clicked="SignOutButton_Clicked" />
    </VerticalStackLayout>
</ContentPage>

    Этот код разметки XAML представляет макет пользовательского интерфейса для представления утверждений в приложении .NET MAUI. Она начинается с определения ContentPage с использованием заголовка и отключения функции кнопки "Назад".

    Внутри VerticalStackLayout находится несколько элементов Label, которые отображают статический текст, за ними следует элемент ListView, названный Claims, который привязывается к коллекции, названной IdTokenClaims, для отображения утверждений, найденных в токене идентификатора. Каждый элемент отображается в ViewCell с использованием DataTemplate и показывается как центрированный Label внутри Grid.

    Наконец, в нижней части макета есть кнопка Sign Out, которая активирует обработчик событий SignOutButton_Clicked при щелчке.

Обработка данных ClaimsView

Следующий шаг — добавить код для обработки ClaimsView данных.

  1. В области обозревателя решений Visual Studio разверните файл ClaimsView.xaml, чтобы отобразить связанный файл кода ClaimsView.xaml.cs. Откройте ClaimsView.xaml.cs и замените содержимое файла следующим кодом:

    using SignInMaui.MSALClient;
using Microsoft.Identity.Client;

namespace SignInMaui.Views;

public partial class ClaimsView : ContentPage
{
    public IEnumerable<string> IdTokenClaims { get; set; } = new string[] {"No claims found in ID token"};
    public ClaimsView()
    {
        BindingContext = this;
        InitializeComponent();

        _ = SetViewDataAsync();
    }

    private async Task SetViewDataAsync()
    {
        try
        {
            _ = await PublicClientSingleton.Instance.AcquireTokenSilentAsync();

            IdTokenClaims = PublicClientSingleton.Instance.MSALClientHelper.AuthResult.ClaimsPrincipal.Claims.Select(c => c.Value);

            Claims.ItemsSource = IdTokenClaims;
        }

        catch (MsalUiRequiredException)
        {
            await Shell.Current.GoToAsync("claimsview");
        }
    }

    protected override bool OnBackButtonPressed() { return true; }

    private async void SignOutButton_Clicked(object sender, EventArgs e)
    {
        await PublicClientSingleton.Instance.SignOutAsync().ContinueWith((t) =>
        {
            return Task.CompletedTask;
        });

        await Shell.Current.GoToAsync("mainview");
    }
}

    Код ClaimsView.xaml.cs представляет собой код-бекэнд для представления требований в приложении .NET MAUI. Он начинается с импорта необходимых пространств имен и определения класса ClaimsView, который расширяет ContentPage. Свойство IdTokenClaims представляет собой перечисление строк, изначально задающее одну строку, указывающую, что утверждения не найдены.

    Конструктор ClaimsView задает контекст привязки текущему экземпляру, инициализирует компоненты представления и вызывает SetViewDataAsync метод асинхронно. Метод SetViewDataAsync пытается незаметно получить токен, извлекает утверждения из результата проверки подлинности и устанавливает свойство IdTokenClaims для их отображения в ListView под именем Claims. Если возникает MsalUiRequiredException, указывающий на необходимость взаимодействия с пользователем для аутентификации, приложение переходит к экрану утверждений.

    Метод OnBackButtonPressed переопределяет поведение кнопки "Назад", чтобы всегда возвращать значение true, предотвращая возвращение пользователя из этого представления. Обработчик событий SignOutButton_Clicked выполняет выход пользователя из системы с помощью экземпляра PublicClientSingleton и после завершения перенаправляет на main view.

Изменение оболочки приложения

Класс AppShell определяет визуальную иерархию приложения, разметку XAML, используемую при создании пользовательского интерфейса приложения. Обновите AppShell, чтобы учесть Views.

  1. Дважды щелкните файл AppShell.xaml в Обозревателе решений, чтобы открыть редактор XAML. Замените разметку XAML следующим кодом:

    <?xml version="1.0" encoding="UTF-8" ?>
<Shell
    x:Class="SignInMaui.AppShell"
    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    xmlns:local="clr-namespace:SignInMaui.Views"
    Shell.FlyoutBehavior="Disabled">

    <ShellContent
        Title="Home"
        ContentTemplate="{DataTemplate local:MainView}"
        Route="MainPage" />
</Shell>

    Код XAML определяет класс AppShell, который отключает поведение всплывающего элемента и задает основное содержимое элементу ShellContent с заголовком Home и шаблоном контента, указывающим на класс MainView.

  2. В области Обозреватель решений Visual Studio разверните файл AppShell.xaml, чтобы отобразить его файл кода AppShell.xaml.cs. Откройте AppShell.xaml.cs и замените содержимое файла следующим кодом:

    // Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License.
using SignInMaui.Views;

namespace SignInMaui;

public partial class AppShell : Shell
{
    public AppShell()
    {
        InitializeComponent();
        Routing.RegisterRoute("mainview", typeof(MainView));
        Routing.RegisterRoute("claimsview", typeof(ClaimsView));
    }
}

    Вы обновляете AppShell.xaml.cs файл, чтобы включить необходимые регистрации маршрутов для MainView и ClaimsView. Вызывая InitializeComponent() метод, необходимо обеспечить инициализацию AppShell класса. Метод RegisterRoute() связывает маршруты mainview и claimsview с их соответствующими типами представлений MainView и ClaimsView.

Добавление кода для конкретной платформы

Проект приложения .NET MAUI содержит папку "Платформы" с каждой дочерней папкой, представляющей платформу, предназначенную для .NET MAUI. Чтобы обеспечить поведение конкретного приложения для дополнения класса приложений по умолчанию, необходимо изменить Platforms/Windows/App.xaml.cs.

Замените содержимое файла следующим кодом:

using SignInMaui.MSALClient;
using Microsoft.Identity.Client;
using Microsoft.UI.Xaml;

// To learn more about WinUI, the WinUI project structure,
// and more about our project templates, see: http://aka.ms/winui-project-info.

namespace SignInMaui.WinUI;

/// <summary>
/// Provides application-specific behavior to supplement the default Application class.
/// </summary>
public partial class App : MauiWinUIApplication
{
    /// <summary>
    /// Initializes the singleton application object.  This is the first line of authored code
    /// executed, and as such is the logical equivalent of main() or WinMain().
    /// </summary>
    public App()
    {
        this.InitializeComponent();

        // configure redirect URI for your application
        PlatformConfig.Instance.RedirectUri = $"msal{PublicClientSingleton.Instance.MSALClientHelper.AzureAdConfig.ClientId}://auth";

        // Initialize MSAL
        IAccount existinguser = Task.Run(async () => await PublicClientSingleton.Instance.MSALClientHelper.InitializePublicClientAppAsync()).Result;

    }

    protected override MauiApp CreateMauiApp() => MauiProgram.CreateMauiApp();

    protected override void OnLaunched(LaunchActivatedEventArgs args)
    {
        base.OnLaunched(args);

        var app = SignInMaui.App.Current;
        PlatformConfig.Instance.ParentWindow = ((MauiWinUIWindow)app.Windows[0].Handler.PlatformView).WindowHandle;
    }
}

В коде необходимо настроить URI перенаправления для приложения и инициализировать MSAL, а затем задать родительское окно для приложения. Кроме того, вы переопределяете метод OnLaunched, чтобы обрабатывать событие запуска и получить дескриптор родительского окна.

Добавление параметров приложения

Параметры позволяют разделить данные, которые настраивают поведение приложения из кода, позволяя изменять поведение без перестроения приложения. MauiAppBuilder предоставляет ConfigurationManager для настройки параметров в нашем приложении .NET MAUI. Добавим файл appsettings.json в виде EmbeddedResource.

Чтобы создать appsettings.json, выполните следующие действия.

  1. В панели Обозреватель решений Visual Studio щелкните правой кнопкой мыши на проекте SignInMaui>Добавить>Новый элемент....

  2. Выберите Web>JavaScript JSON Файл конфигурации. Назовите файл appsettings.json.

  3. Выберите Добавить.

  4. Выберите appsettings.json

  5. В области Свойства установите Действие сборки на внедренный ресурс.

  6. В области "Свойства", установите "Копировать в выходной каталог" на "Копировать всегда".

  7. Замените содержимое appsettings.json файла следующим кодом:

    {
  "AzureAd": {
    "Authority": "https://Enter_the_Tenant_Subdomain_Here.ciamlogin.com/",
    "ClientId": "Enter_the_Application_Id_Here",
    "CacheFileName": "msal_cache.txt",
    "CacheDir": "C:/temp"
  },
  "DownstreamApi": {
    "Scopes": "openid offline_access"
  }
}

  8. В appsettings.jsonнайдите заполнитель:

    1. Enter_the_Tenant_Subdomain_Here и замените его на поддомен каталога (домен клиента). Например, если основной домен клиента — это contoso.onmicrosoft.com, используйте contoso. Если у вас нет названия арендатора, узнайте, как посмотреть сведения об арендаторе.
    2. Enter_the_Application_Id_Here и замените его идентификатором приложения (client ID) вашего ранее зарегистрированного приложения.

Использование личного домена URL-адреса (необязательно)

Используйте настраиваемый домен для полного брендирования URL-адреса аутентификации. С точки зрения пользователя, во время проверки подлинности пользователи остаются на вашем домене, а не перенаправляются на доменное имя ciamlogin.com.

Выполните следующие действия, чтобы использовать личный домен:

  1. Выполните действия, описанные в разделе "Включение пользовательских доменов URL для приложений во внешних клиентах", чтобы включить пользовательский домен URL во внешнем клиенте.

  2. Откройте файл appsettings.json:

    1. Измените значение свойства Authority на https://Enter_the_Custom_Domain_Here/Enter_the_Tenant_ID_Here. Замените Enter_the_Custom_Domain_Here доменом личного URL-адреса и Enter_the_Tenant_ID_Here идентификатором клиента. Если у вас нет идентификатора клиента, узнайте, как прочитать сведения о клиенте.
    2. Добавьте свойство knownAuthorities со значением [Введите_произвольный_домен_здесь].

После внесения изменений в файл appsettings.json, если ваш пользовательский домен URL — это login.contoso.com, а идентификатор арендатора — aaaabbbb-0000-cccc-1111-dddd2222eeee, то файл должен выглядеть примерно так, как показано в следующем фрагменте:

{
  "AzureAd": {
    "Authority": "https://login.contoso.com/aaaabbbb-0000-cccc-1111-dddd2222eeee",
    "ClientId": "Enter_the_Application_Id_Here",
    "CacheFileName": "msal_cache.txt",
    "CacheDir": "C:/temp",
    "KnownAuthorities": ["login.contoso.com"]
  },
  "DownstreamApi": {
    "Scopes": "openid offline_access"
  }
}

Запуск и тестирование настольного приложения .NET MAUI

Приложения .NET MAUI предназначены для работы на нескольких операционных системах и устройствах. Вам потребуется выбрать целевой объект, с помощью которого вы хотите протестировать и отладить приложение.

Установите целевой объект отладки на панели инструментов Visual Studio на устройство, с которым требуется выполнить отладку и тестирование. Ниже показано, как задать целевой объект отладки для Windows:

  1. Выберите выпадающий список "Цель отладки".
  2. Выбор платформы
  3. Выберите net7.0-windows...

Запустите приложение, нажав клавишу F5 или нажав кнопку воспроизведения в верхней части Visual Studio.

  1. Теперь можно протестировать пример настольного приложения .NET MAUI. После запуска приложения окно настольного приложения появится автоматически.

    Снимок экрана кнопки входа в настольном приложении

  2. В появившемся окне рабочего стола нажмите кнопку "Войти ". Откроется окно браузера, и вам будет предложено войти.

    снимок экрана запроса пользователя на ввод учетных данных в настольном приложении.

    Во время входа вам будет предложено предоставить различные разрешения (разрешить приложению доступ к данным). После успешного входа и согласия на экране приложения отображается главная страница.

    Снимок экрана главной страницы в настольном приложении после входа.

Следующий шаг

Руководство: добавление ролей приложения в приложение .NET MAUI и получение их в идентификационном токене