Настольное приложение, которое вызывает веб-API: Интерактивное получение токена

Статья
01/15/2024

применяется к: зеленый круг с символом белой флажки. арендаторы рабочей силы Белый круг с серым символом X. внешние клиенты (подробнее)

В следующем примере показан минимальный код для получения токена в интерактивном режиме для чтения профиля пользователя с помощью Microsoft Graph.

Код в MSAL.NET

string[] scopes = new string[] { "user.read" };

var app = PublicClientApplicationBuilder.Create("YOUR_CLIENT_ID")
    .WithDefaultRedirectUri()
    .Build();

var accounts = await app.GetAccountsAsync();

AuthenticationResult result;
try
{
    result = await app.AcquireTokenSilent(scopes, accounts.FirstOrDefault())
      .ExecuteAsync();
}
catch (MsalUiRequiredException)
{
    result = await app.AcquireTokenInteractive(scopes).ExecuteAsync();
}

Обязательные параметры

AcquireTokenInteractive имеет только один обязательный параметр, scopes. Он содержит перечисление строк, определяющих области, для которых требуется маркер. Если маркер предназначен для Microsoft Graph, вы можете найти необходимые области в справочнике по API каждого API Microsoft Graph в разделе "Разрешения". Например, чтобы вывести список контактов пользователя, необходимо использовать оба User.Read и Contacts.Read в качестве области. Для получения дополнительной информации см. справочник по разрешениям Microsoft Graph.

В настольных и мобильных приложениях важно указать родителя с помощью .WithParentActivityOrWindow. Во многих случаях это требование, и MSAL выдает исключения.

Для настольных приложений см. родительские дескрипторы окон.

Для мобильных приложений укажите Activity (Android) или UIViewController (iOS).

Необязательные параметры в MSAL.NET

СРодительскойАктивностьюИлиОкном

Пользовательский интерфейс важен, так как он является интерактивным. AcquireTokenInteractive имеет один конкретный необязательный параметр, который может указывать родительский пользовательский интерфейс (для платформ, поддерживающих эту функцию). При использовании .WithParentActivityOrWindow в классическом приложении он имеет другой тип, который зависит от платформы.

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

// net45
WithParentActivityOrWindow(IntPtr windowPtr)
WithParentActivityOrWindow(IWin32Window window)

// Mac
WithParentActivityOrWindow(NSWindow window)

// .NET Standard (this will be on all platforms at runtime, but only on .NET Standard platforms at build time)
WithParentActivityOrWindow(object parent).

Примечания:

На платформе .NET Standard ожидаемое значение будет object на Android, Activity на iOS, UIViewController на Mac и NSWindow или IWin32Window на Windows.
В Windows необходимо вызвать AcquireTokenInteractive из потока пользовательского интерфейса, чтобы встроенный браузер получил соответствующий контекст синхронизации пользовательского интерфейса. Если не вызывать из потока пользовательского интерфейса, это может привести к неправильной обработке сообщений и сценариям взаимоблокировки с пользовательским интерфейсом. Один из способов вызова библиотеки проверки подлинности Майкрософт (MSAL) из потока пользовательского интерфейса, если вы еще не находитесь в этом потоке, — это использовать Dispatcher в Windows Presentation Foundation (WPF).
Если вы используете WPF для получения окна из элемента управления WPF, можно использовать класс WindowInteropHelper.Handle. Затем вызов осуществляется из элемента управления WPF (this):
```
result = await app.AcquireTokenInteractive(scopes)
                  .WithParentActivityOrWindow(new WindowInteropHelper(this).Handle)
                  .ExecuteAsync();
```

С подсказкой

Вы используете WithPrompt() для управления взаимодействием с пользователем, указав запрос. Точное поведение можно контролировать с помощью структуры Microsoft.Identity.Client.Prompt .

Структура определяет следующие константы:

SelectAccount заставляет службу токенов безопасности (STS) представить диалоговое окно выбора учетной записи, содержащей учетные записи с активной сессией пользователя. Этот параметр в установлен по умолчанию. Это полезно, если вы хотите разрешить пользователям выбирать между разными идентичностями.

Этот параметр позволяет MSAL отправлять prompt=select_account поставщику удостоверений. Он обеспечивает оптимальный интерфейс на основе доступных сведений, таких как учетная запись и наличие сеанса для пользователя. Не изменяйте его, если у вас нет хорошей причины.
Consent позволяет принудительно запрашивать согласие пользователя, даже если приложение предоставило согласие. В этом случае MSAL отправляет prompt=consent поставщику удостоверений. Этот параметр можно использовать в некоторых приложениях, ориентированных на безопасность, где управление организации требует, чтобы диалоговое окно согласия отображалось каждый раз, когда пользователь открывает приложение.
ForceLogin позволяет приложению запрашивать у пользователя учетные данные, даже если этот запрос пользователя может быть не нужен. Этот параметр может быть полезен, чтобы пользователь вновь вошёл в систему, если получение токена завершается ошибкой. В этом случае MSAL отправляет prompt=login поставщику удостоверений. Организации иногда используют этот параметр в приложениях, ориентированных на безопасность, где управление требует, чтобы пользователи входить каждый раз, когда они обращаются к определенным частям приложения.
Create активирует процесс регистрации для внешних идентификаторов, отправляя prompt=create поставщику удостоверений. Приложения Azure Active Directory B2C (Azure AD B2C) не должны отправлять этот запрос. Дополнительные сведения см. в разделе Добавление потока регистрации для пользователя самообслуживания.
Never (только для .NET 4.5 и Windows Runtime) не запрашивает пользователя. Вместо этого он пытается использовать файл cookie, хранящийся во встроенном скрытом веб-обозревателе.

Использование этого параметра может завершиться ошибкой. В этом случае AcquireTokenInteractive выбрасывает исключение, чтобы уведомить вас о необходимости взаимодействия с пользовательским интерфейсом. Затем используйте другой Prompt параметр.
NoPrompt не отправляет сигнал поставщику удостоверений. Поставщик удостоверений решает, какой интерфейс входа лучше всего подходит для пользователя (единый вход или выбор учетной записи).

Этот параметр является обязательным для редактирования политик профилей в Azure AD B2C. Дополнительные сведения см. в разделе об особенностях Azure AD B2C.

С использованием встроенного WebView

Этот метод позволяет указать, следует ли принудительно использовать внедренный WebView или системный WebView (при наличии). Дополнительные сведения см. в разделе Использование веб-браузеров.

var result = await app.AcquireTokenInteractive(scopes)
                    .WithUseEmbeddedWebView(true)
                    .ExecuteAsync();

С дополнительной областью для согласия

Этот модификатор предназначен для расширенных сценариев, в которых пользователь может предоставить согласие на несколько ресурсов заранее, и вы не хотите использовать добавочное согласие. Разработчики обычно используют инкрементальное согласие с MSAL.NET и платформой удостоверений Microsoft.

var result = await app.AcquireTokenInteractive(scopesForCustomerApi)
                     .WithExtraScopeToConsent(scopesForVendorApi)
                     .ExecuteAsync();

WithCustomWebUi

Веб-интерфейс — это механизм для вызова браузера. Этот механизм может быть выделенным элементом управления WebBrowser пользовательского интерфейса или способом делегирования открытия браузера. MSAL предоставляет реализации веб-интерфейса для большинства платформ, но в таких случаях может потребоваться разместить браузер самостоятельно:

У вас есть платформы, которые MSAL не охватывает явно, например Blazor, Unity и Mono на ПК.
Необходимо протестировать пользовательский интерфейс приложения и использовать автоматизированный браузер, который можно использовать с Selenium.
Браузер и приложение, в котором выполняется MSAL, находятся в отдельных процессах.

Для этого необходимо предоставить MSAL start Url, который должен отображаться в браузере, чтобы пользователи могли вводить такие элементы, как их имя пользователя. После завершения проверки подлинности приложение должно вернуться в MSAL end Url, который содержит код, который предоставляет идентификатор Microsoft Entra. Хост end Url всегда redirectUri. Чтобы перехватить end Url, выполните одно из следующих действий.

Отслеживайте перенаправления браузера, пока не достигнут redirect Url.
Перенаправьте браузер на url-адрес, который вы отслеживаете.

WithCustomWebUi — это точка расширяемости, которую можно использовать для предоставления собственного пользовательского интерфейса в общедоступных клиентских приложениях. Вы также можете разрешить пользователям пройти через /Authorize конечную точку поставщика удостоверений, позволив им войти и дать согласие. MSAL.NET может затем активировать код проверки подлинности и получить маркер.

Например, вы можете использовать WithCustomWebUi в Visual Studio для приложений Electron, таких как обратная связь Visual Studio, чтобы обеспечить веб-взаимодействие, но большую часть работы оставьте MSAL.NET. Кроме того, можно использовать WithCustomWebUi , если требуется обеспечить автоматизацию пользовательского интерфейса.

В общедоступных клиентских приложениях MSAL.NET использует стандарт ключа проверки для обмена кодом (PKCE), чтобы обеспечить соблюдение безопасности. Только MSAL.NET может активировать код. Дополнительные сведения см. в разделе RFC 7636 — ключ проверки для обмена кодом с помощью общедоступных клиентов OAuth.

using Microsoft.Identity.Client.Extensions;

Использование WithCustomWebUI

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

Реализуйте интерфейс ICustomWebUi. Для получения дополнительной информации см. эту страницу проекта GitHub.
Реализуйте один AcquireAuthorizationCodeAsyncметод и примите URL-адрес кода авторизации, который вычисляет MSAL.NET.
Разрешите пользователю пройти взаимодействие с поставщиком удостоверений и получить URL-адрес, который данный поставщик использовал для обратного вызова вашей реализации, а также код авторизации. Если у вас возникли проблемы, ваша реализация должна выбросить MsalExtensionException исключение для взаимодействия с MSAL.
В вашем вызове AcquireTokenInteractive используйте модификатор .WithCustomUI(), передав экземпляр вашего кастомного веб-интерфейса.
```
result = await app.AcquireTokenInteractive(scopes)
                  .WithCustomWebUi(yourCustomWebUI)
                  .ExecuteAsync();
```

Команда MSAL.NET переписала тесты пользовательского интерфейса для использования этого механизма расширяемости. Если вы хотите, просмотрите класс SeleniumWebUI в исходном коде MSAL.NET.

Обеспечьте отличный опыт с помощью SystemWebViewOptions

В MSAL.NET 4.1 SystemWebViewOptions можно указать:

Универсальный код ресурса (URI), на который нужно перейти (BrowserRedirectError), или фрагмент HTML для отображения (HtmlMessageError), если в системном веб-браузере возникают ошибки входа или согласия.
URI для перехода (BrowserRedirectSuccess) или фрагмент HTML для отображения (HtmlMessageSuccess) в случае успешного входа или согласия.
Действие, выполняемое для запуска системного браузера. Вы можете предоставить собственную реализацию, установив делегат OpenBrowserAsync. Класс также предоставляет реализацию по умолчанию для двух браузеров: OpenWithEdgeBrowserAsync для Microsoft Edge и OpenWithChromeEdgeBrowserAsync Microsoft Edge в Chromium.

Чтобы использовать эту структуру, напишите примерно следующий код:

IPublicClientApplication app;
...

options = new SystemWebViewOptions
{
 HtmlMessageError = "<b>Sign-in failed. You can close this tab ...</b>",
 BrowserRedirectSuccess = "https://contoso.com/help-for-my-awesome-commandline-tool.html"
};

var result = app.AcquireTokenInteractive(scopes)
                .WithEmbeddedWebView(false)       // The default in .NET
                .WithSystemWebViewOptions(options)
                .Build();

Другие необязательные параметры

Дополнительные сведения о других необязательных параметрах AcquireTokenInteractiveсм. в статье AcquireTokenInteractiveParameterBuilder.

private static IAuthenticationResult acquireTokenInteractive() throws Exception {

    // Load the token cache from the file and initialize the token cache aspect. The token cache will have
    // dummy data, so the acquireTokenSilently call will fail.
    TokenCacheAspect tokenCacheAspect = new TokenCacheAspect("sample_cache.json");

    PublicClientApplication pca = PublicClientApplication.builder(CLIENT_ID)
            .authority(AUTHORITY)
            .setTokenCacheAccessAspect(tokenCacheAspect)
            .build();

    Set<IAccount> accountsInCache = pca.getAccounts().join();
    // Take the first account in the cache. In a production application, you would filter
    // accountsInCache to get the right account for the user who is authenticating.
    IAccount account = accountsInCache.iterator().next();

    IAuthenticationResult result;
    try {
        SilentParameters silentParameters =
                SilentParameters
                        .builder(SCOPE, account)
                        .build();

        // try to acquire the token silently. This call will fail because the token cache
        // does not have any data for the user you're trying to acquire a token for
        result = pca.acquireTokenSilently(silentParameters).join();
    } catch (Exception ex) {
        if (ex.getCause() instanceof MsalException) {

            InteractiveRequestParameters parameters = InteractiveRequestParameters
                    .builder(new URI("http://localhost"))
                    .scopes(SCOPE)
                    .build();

            // Try to acquire a token interactively with the system browser. If successful, you should see
            // the token and account information printed out to the console
            result = pca.acquireToken(parameters).join();
        } else {
            // Handle other exceptions accordingly
            throw ex;
        }
    }
    return result;
}

Код в MSAL для iOS и macOS

MSALInteractiveTokenParameters *interactiveParams = [[MSALInteractiveTokenParameters alloc] initWithScopes:scopes webviewParameters:[MSALWebviewParameters new]];
[application acquireTokenWithParameters:interactiveParams completionBlock:^(MSALResult *result, NSError *error) {
    if (!error)
    {
        // You'll want to get the account identifier to retrieve and reuse the account
        // for later acquireToken calls
        NSString *accountIdentifier = result.account.identifier;

        NSString *accessToken = result.accessToken;
    }
}];

let interactiveParameters = MSALInteractiveTokenParameters(scopes: scopes, webviewParameters: MSALWebviewParameters())
application.acquireToken(with: interactiveParameters, completionBlock: { (result, error) in

    guard let authResult = result, error == nil else {
        print(error!.localizedDescription)
        return
    }

    // Get the access token from the result
    let accessToken = authResult.accessToken
})

На узле MSAL вы приобретаете токены с помощью потока кода авторизации с ключом проверки для обмена кодом (PKCE). Процесс состоит из двух этапов:

Приложение получает URL-адрес, который можно использовать для создания кода авторизации. Пользователи могут открыть URL-адрес в браузере и ввести свои учетные данные. Затем они перенаправляются обратно redirectUri (зарегистрированы во время регистрации приложения) с кодом авторизации.
Приложение передает полученный код acquireTokenByCode() авторизации методу, который обменивается им на маркер доступа.

const msal = require("@azure/msal-node");

const msalConfig = {
    auth: {
        clientId: "your_client_id_here",
        authority: "your_authority_here",
    }
};

const pca = new msal.PublicClientApplication(msalConfig);

const {verifier, challenge} = await msal.cryptoProvider.generatePkceCodes();

const authCodeUrlParameters = {
    scopes: ["User.Read"],
    redirectUri: "your_redirect_uri",
    codeChallenge: challenge, // PKCE code challenge
    codeChallengeMethod: "S256" // PKCE code challenge method 
};

// Get the URL to sign in the user and consent to scopes needed for the application
pca.getAuthCodeUrl(authCodeUrlParameters).then((response) => {
    console.log(response);

    const tokenRequest = {
        code: response["authorization_code"],
        codeVerifier: verifier // PKCE code verifier 
        redirectUri: "your_redirect_uri",
        scopes: ["User.Read"],
    };

    // Acquire a token by exchanging the code
    pca.acquireTokenByCode(tokenRequest).then((response) => {
        console.log("\nResponse: \n:", response);
    }).catch((error) => {
        console.log(error);
    });
}).catch((error) => console.log(JSON.stringify(error)));

MSAL Python 1.7+ предлагает интерактивный метод получения токена.

result = None

# Check the cache to see if this user has signed in before
accounts = app.get_accounts(username=config["username"])
if accounts:
    result = app.acquire_token_silent(config["scope"], account=accounts[0])

if not result:
    result = app.acquire_token_interactive(  # It automatically provides PKCE protection
         scopes=config["scope"])

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

Дополнительные сведения см. в статье о создании одностраничного приложения на React, выполняющего вход пользователей, в серии многочастного руководства.
Изучите платформу идентификации Microsoft настольные примеры кода

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