Aplikacja klasyczna, która wywołuje internetowe interfejsy API: uzyskiwanie tokenu interaktywnie

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 programu Microsoft Graph, możesz znaleźć wymagane zakresy w dokumentacji interfejsu API każdego interfejsu API programu Microsoft Graph w sekcji "Uprawnienia". Aby na przykład wyświetlić listę kontaktów użytkownika, musisz użyć zarówno User.Read opcji , 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 biblioteka MSAL zgłasza wyjątki.

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

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

Parametry opcjonalne w MSAL.NET

WithParentActivityOrWindow

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. W przypadku korzystania z .WithParentActivityOrWindow aplikacji klasycznej 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 wątek interfejsu użytkownika, aby przeglądarka osadzona pobierała odpowiedni kontekst synchronizacji interfejsu użytkownika. Wywołanie z wątku interfejsu użytkownika może spowodować nieprawidłowe pompowanie komunikatów i spowodować scenariusze zakleszczenia za pomocą interfejsu użytkownika. Jednym ze sposobów wywoływania biblioteki Microsoft Authentication Library (MSAL) z wątku interfejsu użytkownika, jeśli nie jesteś już w wątku interfejsu użytkownika, jest użycie Dispatcher go 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();
  

WithPrompt

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 usługę tokenu zabezpieczającego (STS) w celu przedstawienia okna dialogowego wyboru konta zawierającego konta, dla których użytkownik ma 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 powoduje wysłanie biblioteki prompt=select_account MSAL do dostawcy tożsamości. Zapewnia najlepsze możliwe środowisko na podstawie dostępnych informacji, takich jak konto i obecność sesji dla użytkownika. Nie zmieniaj go, chyba że masz dobry powód.

• Consent Umożliwia wymusinie monitowania użytkownika o zgodę, nawet jeśli aplikacja udzieliła zgody przed. 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 wyświetlenie monitu o podanie poświadczeń przez użytkownika, nawet jeśli ten monit użytkownika 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 do dostawcy prompt=login 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 środowisko 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 Dodawanie przepływu użytkownika rejestracji samoobsługowej do aplikacji.

• Never(tylko dla platformy .NET 4.5 i środowisko wykonawcze systemu 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 zgłasza wyjątek informujący o AcquireTokenInteractive konieczności interakcji interfejsu 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 elementu WebView lub systemowego widoku WebView (jeśli jest dostępna). Aby uzyskać więcej informacji, zobacz Użycie przeglądarek internetowych.

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

WithExtraScopeToConsent

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 Platforma 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ć dedykowaną kontrolką WebBrowser interfejsu użytkownika 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 jawnie, takich jak Blazor, Unity i Mono na komputerach stacjonarnych.
• Chcesz przetestować aplikację i użyć zautomatyzowanej przeglądarki, która może być używana z selenium.
• Przeglądarka i aplikacja z uruchomionym biblioteką MSAL znajdują się w osobnych procesach.

Aby to osiągnąć, należy nadać biblioteki MSAL start Url, która musi być wyświetlana w przeglądarce, aby użytkownicy mogli wprowadzać elementy, 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 Urlelement , wykonaj jedną z następujących czynności:

• Monitoruj przekierowania przeglądarki do momentu redirect Url trafienia.
• 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 zezwolenie im na logowanie się i 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 elektronowe (na przykład Visual Studio Feedback) udostępniały interakcję internetową, ale 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 weryfikacji dla wymiany kodu przez klientów publicznych protokołu OAuth.

using Microsoft.Identity.Client.Extensions;

Używanie zcustomWebUI

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

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. Jeśli masz problemy, implementacja powinna zgłosić wyjątek do współpracy z biblioteką MsalExtensionException 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.

Doskonałe doświadczenie w pracy z elementem 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.
• Identyfikator URI do przejścia do (BrowserRedirectSuccess) lub fragmentu 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 OpenWithChromeEdgeBrowserAsync Microsoft 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 parametrach opcjonalnych dla AcquireTokenInteractiveprogramu , 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

• Dowiedz się więcej, tworząc aplikację jednostronicową React (SPA), która loguje użytkowników w poniższej serii samouczków wieloczęściowych.

• Eksplorowanie przykładów kodu klasycznego Platforma tożsamości Microsoft