Aplikacja desktopowa, która wywołuje internetowe interfejsy API: pobieranie tokenu interaktywnie

Dotyczy: Dzierżawcy Workforce Dzierżawcy zewnętrzni (dowiedzieć się więcej)

W poniższym przykładzie pokazano minimalny kod, aby interaktywnie uzyskać token do odczytywania profilu użytkownika za pomocą programu Microsoft Graph.

.NET

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

Parametry obowiązkowe

AcquireTokenInteractive ma tylko jeden parametr obowiązkowy, scopes. Zawiera on wyliczenie ciągów, które definiują zakresy, dla których jest wymagany token. Jeśli token jest przeznaczony dla Microsoft Graph, możesz znaleźć wymagane zakresy w dokumentacji API każdego interfejsu API Microsoft Graph w sekcji "Uprawnienia". Aby na przykład wyświetlić listę kontaktów użytkownika, musisz użyć zarówno User.Read, jak i Contacts.Read jako zakresu. Aby uzyskać więcej informacji, zobacz Informacje o uprawnieniach usługi Microsoft Graph.

W aplikacjach klasycznych i mobilnych ważne jest określenie elementu nadrzędnego przy użyciu polecenia .WithParentActivityOrWindow. W wielu przypadkach jest to wymagane, a w MSAL zostanie rzucony wyjątek.

W przypadku aplikacji desktopowych zobacz Obsługa okien nadrzędnych.

W przypadku aplikacji mobilnych podaj Activity (Android) lub UIViewController (iOS).

Parametry opcjonalne w MSAL.NET

ZRodzicemAktywnościLublOkno

Interfejs użytkownika jest ważny, ponieważ jest interaktywny. AcquireTokenInteractive Ma jeden konkretny opcjonalny parametr, który może określać (dla platform, które ją obsługują) nadrzędny interfejs użytkownika. Kiedy używasz .WithParentActivityOrWindow w aplikacji desktopowej, ma inny typ, który zależy od platformy.

Alternatywnie możesz pominąć opcjonalny parametr okna nadrzędnego, aby utworzyć okno, jeśli nie chcesz kontrolować, gdzie na ekranie pojawi się okno dialogowe logowania. Ta opcja ma zastosowanie w przypadku aplikacji, które są oparte na wierszu polecenia, są używane do przekazywania wywołań do dowolnej innej usługi zaplecza i nie potrzebują żadnych okien do interakcji użytkownika.

// 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).

Uwagi:

• W programie .NET Standard oczekiwana object wartość jest Activity w systemie Android, UIViewController w systemie iOS, NSWindow na komputerach Mac i IWin32Window w IntPr systemie Windows.

• W systemie Windows należy wywołać AcquireTokenInteractive z wątku interfejsu użytkownika, aby osadzona przeglądarka otrzymała odpowiedni kontekst synchronizacji interfejsu użytkownika. Nie wywoływanie z wątku interfejsu użytkownika może prowadzić do nieprawidłowego przetwarzania komunikatów i powodować scenariusze zakleszczenia w interfejsie użytkownika. Jednym ze sposobów wywołania biblioteki Microsoft Authentication Library (MSAL) z wątku interfejsu użytkownika, jeśli obecnie nie jesteś w wątku interfejsu użytkownika, jest użycie Dispatcher w programie Windows Presentation Foundation (WPF).

• Jeśli używasz WPF, aby uzyskać okno z kontrolki WPF, możesz użyć WindowInteropHelper.Handle klasy . Następnie wywołanie pochodzi z kontrolki WPF (this):

  result = await app.AcquireTokenInteractive(scopes)
                    .WithParentActivityOrWindow(new WindowInteropHelper(this).Handle)
                    .ExecuteAsync();
  

Z podpowiedzią

WithPrompt() Służy do kontrolowania interakcyjności z użytkownikiem, określając monit. Dokładne zachowanie można kontrolować przy użyciu struktury Microsoft.Identity.Client.Prompt .

Struktura definiuje następujące stałe:

• SelectAccount Wymusza, aby usługa tokenu zabezpieczeń (STS) wyświetliła okno dialogowe wyboru konta, które zawiera konta, dla których użytkownik ma aktywną sesję. Ta opcja jest domyślnie zaznaczona. Jest to przydatne, gdy chcesz zezwolić użytkownikom na wybór między różnymi tożsamościami.

  Ta opcja nakazuje MSAL wysłać żądanie do dostawcy tożsamości. Zapewnia najlepsze możliwe wrażenia na podstawie dostępnych informacji, takich jak konto i obecność sesji użytkownika. Nie zmieniaj go, chyba że masz dobry powód.

• Consent Umożliwia wymuszenie wyświetlenia monitu o zgodę od użytkownika, nawet jeśli aplikacja udzieliła zgody wcześniej. W takim przypadku biblioteka MSAL wysyła do dostawcy prompt=consent tożsamości. Tej opcji można użyć w niektórych aplikacjach skoncentrowanych na zabezpieczeniach, w których nadzór organizacji wymaga wyświetlenia okna dialogowego zgody za każdym razem, gdy użytkownik otworzy aplikację.

• ForceLogin umożliwia monitowanie użytkownika o podanie poświadczeń, nawet jeśli ten monit może nie być potrzebny. Ta opcja może być przydatna, aby umożliwić użytkownikowi ponowne zalogowanie się w przypadku niepowodzenia pozyskiwania tokenu. W takim przypadku biblioteka MSAL wysyła prompt=login do dostawcy tożsamości. Organizacje czasami używają tej opcji w aplikacjach skoncentrowanych na zabezpieczeniach, w których nadzór wymaga, aby użytkownicy logowali się za każdym razem, gdy uzyskują dostęp do określonych części aplikacji.

• Create wyzwala doświadczenie rejestracji dla tożsamości zewnętrznych, wysyłając prompt=create do dostawcy tożsamości. Aplikacje usługi Azure Active Directory B2C (Azure AD B2C) nie powinny wysyłać tego monitu. Aby uzyskać więcej informacji, zobacz Dodaj przepływ samoobsługowej rejestracji użytkownika do aplikacji.

• Never (tylko dla platformy .NET 4.5 i środowiska uruchomieniowego Windows) nie wyświetla monitu użytkownika. Zamiast tego próbuje użyć pliku cookie przechowywanego w ukrytym osadzonym widoku internetowym.

  Użycie tej opcji może zakończyć się niepowodzeniem. W takim przypadku AcquireTokenInteractive zgłasza wyjątek, aby poinformować cię o konieczności interakcji z interfejsem użytkownika. Następnie użyj innego Prompt parametru.

• NoPrompt nie wysyła żadnych monitów do dostawcy tożsamości. Dostawca tożsamości decyduje, które środowisko logowania jest najlepsze dla użytkownika (logowanie jednokrotne lub wybierz konto).

  Ta opcja jest obowiązkowa w przypadku edytowania zasad profilu w usłudze Azure AD B2C. Aby uzyskać więcej informacji, zobacz Azure AD B2C specifics (Szczegóły usługi Azure AD B2C).

WithUseEmbeddedWebView

Ta metoda umożliwia określenie, czy chcesz wymusić użycie osadzonego WebView lub systemowego WebView (jeśli jest dostępny). Aby uzyskać więcej informacji, zobacz Użycie przeglądarek internetowych.

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

Z Dodatkowym Zakresem na Zgody

Ten modyfikator jest przeznaczony dla zaawansowanych scenariuszy, w których użytkownik chce wyrazić zgodę na kilka zasobów z góry i nie chcesz używać zgody przyrostowej. Deweloperzy zwykle używają zgody przyrostowej z MSAL.NET i platformą tożsamości Microsoft.

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

WithCustomWebUi

Internetowy interfejs użytkownika to mechanizm wywoływania przeglądarki. Ten mechanizm może być specjalną kontrolką interfejsu użytkownika WebBrowser lub sposobem delegowania otwierania przeglądarki. Biblioteka MSAL udostępnia implementacje internetowego interfejsu użytkownika dla większości platform, ale możesz chcieć hostować przeglądarkę samodzielnie w następujących przypadkach:

• Masz platformy, które biblioteka MSAL nie obejmuje wprost, takie jak Blazor, Unity i Mono na komputerach stacjonarnych.
• Chcesz przetestować interfejs użytkownika swojej aplikacji i użyć zautomatyzowanej przeglądarki, która może być używana z Selenium.
• Przeglądarka i aplikacja, które uruchamiają MSAL, działają w osobnych procesach.

Aby to osiągnąć, należy przekazać do MSAL start Url, które musi być wyświetlane w przeglądarce, aby użytkownicy mogli wprowadzać dane, takie jak ich nazwa użytkownika. Po zakończeniu uwierzytelniania aplikacja musi wrócić do biblioteki MSAL end Url, która zawiera kod zapewniany przez firmę Microsoft Entra ID. Host obiektu end Url to zawsze redirectUri. Aby przechwycić end Url, wykonaj jedną z następujących czynności:

• Monitoruj przekierowania przeglądarki do momentu, gdy redirect Url zostanie osiągnięty.
• Przekieruj przeglądarkę do monitorowanego adresu URL.

WithCustomWebUi to punkt rozszerzalności, którego można użyć do udostępnienia własnego interfejsu użytkownika w publicznych aplikacjach klienckich. Możesz również zezwolić użytkownikom na przejście przez /Authorize punkt końcowy dostawcy tożsamości i umożliwić im logowanie się oraz wyrażanie zgody. MSAL.NET następnie może zrealizować kod uwierzytelniania i uzyskać token.

Możesz na przykład użyć WithCustomWebUi w programie Visual Studio, aby aplikacje Electron (na przykład Visual Studio Feedback) umożliwiały interakcję internetową, a pozostaw ją MSAL.NET, aby wykonać większość pracy. Możesz również użyć WithCustomWebUi polecenia , jeśli chcesz zapewnić automatyzację interfejsu użytkownika.

W publicznych aplikacjach klienckich MSAL.NET używa standardu Proof Key for Code Exchange (PKCE) w celu zapewnienia przestrzegania zabezpieczeń. Tylko MSAL.NET może zrealizować kod. Aby uzyskać więcej informacji, zobacz RFC 7636 — klucz weryfikacyjny dla wymiany kodu przez klientów publicznych OAuth.

using Microsoft.Identity.Client.Extensions;

Użycie WithCustomWebUI

Aby użyć metody WithCustomWebUI, wykonaj następujące kroki:

1. Zaimplementuj interfejs ICustomWebUi. Aby uzyskać więcej informacji, zobacz tę stronę usługi GitHub.

2. Zaimplementuj jedną AcquireAuthorizationCodeAsyncmetodę i zaakceptuj adres URL kodu autoryzacji, który MSAL.NET tworzy.

3. Pozwól użytkownikowi przejść przez interakcję z dostawcą tożsamości i zwrócić adres URL używany przez dostawcę tożsamości do wywołania implementacji wraz z kodem autoryzacji. W przypadku problemów, Twoja implementacja powinna zgłosić wyjątek, aby współpracować z biblioteką MSAL.

4. W wywołaniu AcquireTokenInteractive użyj .WithCustomUI() modyfikatora, przekazując wystąpienie niestandardowego internetowego interfejsu użytkownika:

   result = await app.AcquireTokenInteractive(scopes)
                     .WithCustomWebUi(yourCustomWebUI)
                     .ExecuteAsync();
   

Zespół MSAL.NET przepisał testy interfejsu użytkownika w celu korzystania z tego mechanizmu rozszerzalności. Jeśli cię interesuje, wyświetl klasę SeleniumWebUI w kodzie źródłowym MSAL.NET.

Zapewnij doskonałe doświadczenie dzięki elementowi SystemWebViewOptions

W MSAL.NET 4.1 SystemWebViewOptionsmożna określić:

• Identyfikator URI do przejścia do (BrowserRedirectError) lub fragmentu HTML do wyświetlenia (HtmlMessageError), jeśli w przeglądarce internetowej pojawią się błędy logowania lub zgody.
• URI przejścia do (BrowserRedirectSuccess) lub fragment HTML do wyświetlenia (HtmlMessageSuccess), jeśli logowanie lub zgoda zakończy się pomyślnie.
• Akcja do uruchomienia w celu uruchomienia przeglądarki systemowej. Możesz zapewnić własną implementację, ustawiając delegata OpenBrowserAsync . Klasa udostępnia również domyślną implementację dla dwóch przeglądarek: OpenWithEdgeBrowserAsync dla przeglądarki Microsoft Edge i OpenWithChromeEdgeBrowserAsyncMicrosoft Edge w przeglądarce Chromium.

Aby użyć tej struktury, napisz coś podobnego do następującego przykładu:

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

Inne parametry opcjonalne

Aby dowiedzieć się więcej o innych opcjonalnych parametrach AcquireTokenInteractive, zobacz AcquireTokenInteractiveParameterBuilder.

Java

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

macOS

Kod w usłudze MSAL dla systemów iOS i 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
})

Node.js

W węźle biblioteki MSAL uzyskujesz tokeny za pośrednictwem przepływu kodu autoryzacji za pomocą klucza dowodowego dla programu Code Exchange (PKCE). Proces obejmuje dwa kroki:

1. Aplikacja uzyskuje adres URL, który może służyć do generowania kodu autoryzacji. Użytkownicy mogą otworzyć adres URL w przeglądarce i wprowadzić swoje poświadczenia. Następnie są one przekierowywane z powrotem do redirectUri (zarejestrowane podczas rejestracji aplikacji) przy użyciu kodu autoryzacji.
2. Aplikacja przekazuje odebrany kod autoryzacji do acquireTokenByCode() metody, która wymienia ją na token dostępu.

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

Python

Biblioteka MSAL Python 1.7+ udostępnia interaktywną metodę uzyskiwania tokenu:

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"])

Następne kroki

• Poprzez budowanie aplikacji jednostronicowej React (SPA), która loguje użytkowników, dowiedz się więcej w poniższej wieloczęściowej serii samouczków.

• Odkrywanie przykładów kodu aplikacji desktopowych na Platformie tożsamości Microsoft