Desktopová aplikace, která volá webová rozhraní API: Interaktivní získání tokenu

Následující příklad ukazuje minimální kód, který interaktivně získá token pro čtení profilu uživatele pomocí Microsoft Graphu.

.NET

Kód v 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();
}

Povinné parametry

AcquireTokenInteractive má pouze jeden povinný parametr, scopes. Obsahuje výčet řetězců, které definují obory, pro které je token povinný. Pokud je token pro Microsoft Graph, najdete požadované obory v referenčních informacích k rozhraní API každého rozhraní Microsoft Graph API v části s názvem Oprávnění. Pokud například chcete zobrazit seznam kontaktů uživatele, musíte jako obor použít obojí User.Read i Contacts.Read jako obor. Další informace najdete v tématu Referenční informace o oprávněních Microsoft Graphu.

V desktopových i mobilních aplikacích je důležité určit nadřazenou položku pomocí .WithParentActivityOrWindow. V mnoha případech se jedná o požadavek a knihovna MSAL vyvolá výjimky.

U desktopových aplikací naleznete v tématu Nadřazené popisovače oken.

Pro mobilní aplikace zadejte Activity (Android) nebo UIViewController (iOS).

Volitelné parametry v MSAL.NET

WithParentActivityOrWindow

Uživatelské rozhraní je důležité, protože je interaktivní. AcquireTokenInteractive má jeden konkrétní volitelný parametr, který může určit nadřazené uživatelské rozhraní (pro platformy, které ho podporují). Pokud používáte .WithParentActivityOrWindow v desktopové aplikaci, má jiný typ, který závisí na platformě.

Případně můžete vynechat volitelný parametr nadřazeného okna a vytvořit okno, pokud nechcete určovat, kde se na obrazovce zobrazí dialogové okno pro přihlášení. Tato možnost je použitelná pro aplikace založené na příkazovém řádku, slouží k předávání volání do jakékoli jiné back-endové služby a nepotřebují žádná okna pro interakci uživatele.

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

Poznámky:

• V .NET Standard je Activity očekávaná object hodnota v Androidu, UIViewController v iOSu, NSWindow na Macu a IWin32Window ve IntPr Windows.

• Ve Windows musíte volat AcquireTokenInteractive z vlákna uživatelského rozhraní, aby vložený prohlížeč získal příslušný kontext synchronizace uživatelského rozhraní. Volání z vlákna uživatelského rozhraní může způsobit, že zprávy nebudou správně pumpovat a způsobit scénáře vzájemného zablokování s uživatelským rozhraním. Jedním ze způsobů volání knihovny MSAL (Microsoft Authentication Library) z vlákna uživatelského rozhraní, pokud ještě nejste ve vlákně uživatelského rozhraní, je použít Dispatcher ve Windows Presentation Foundation (WPF).

• Pokud používáte WPF, abyste získali okno z ovládacího prvku WPF, můžete použít WindowInteropHelper.Handle třídu. Volání je pak z ovládacího prvku WPF (this):

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

WithPrompt

Používá WithPrompt() se k řízení interaktivity s uživatelem zadáním výzvy. Přesné chování můžete řídit pomocí struktury Microsoft.Identity.Client.Prompt .

Struktura definuje následující konstanty:

• SelectAccount vynutí službu tokenů zabezpečení (STS) k zobrazení dialogového okna pro výběr účtu, který obsahuje účty, pro které má uživatel relaci. Tato možnost je výchozí. Je užitečné, když chcete uživatelům umožnit výběr mezi různými identitami.

  Tato možnost řídí knihovnu MSAL k odeslání prompt=select_account zprostředkovateli identity. Poskytuje nejlepší možné prostředí na základě dostupných informací, jako je účet a přítomnost relace pro uživatele. Neměňte ho, pokud nemáte dobrý důvod.

• Consent umožňuje vynutit, aby se uživateli zobrazila výzva k vyjádření souhlasu, a to i v případě, že aplikace udělila souhlas. V tomto případě msAL odešle prompt=consent zprostředkovateli identity. Tuto možnost můžete použít v některých aplikacích zaměřených na zabezpečení, kde organizace vyžaduje, aby se při každém otevření aplikace zobrazilo dialogové okno souhlasu.

• ForceLogin umožňuje aplikaci vyzvat uživatele k zadání přihlašovacích údajů, a to i v případě, že tato výzva uživatele nemusí být nutná. Tato možnost může být užitečná, aby se uživatel mohl znovu přihlásit, pokud se získání tokenu nezdaří. V tomto případě msAL odešle prompt=login zprostředkovateli identity. Organizace někdy tuto možnost používají v aplikacích zaměřených na zabezpečení, kde uživatelé vyžadují, aby se uživatelé přihlašovali pokaždé, když přistupují ke konkrétním částem aplikace.

• Create aktivuje prostředí registrace pro externí identity odesláním prompt=create zprostředkovateli identity. Aplikace Azure Active Directory B2C (Azure AD B2C) by neměly tuto výzvu odesílat. Další informace najdete v tématu Přidání toku uživatele samoobslužné registrace do aplikace.

• Never(jenom pro .NET 4.5 a prostředí Windows Runtime) se uživateli nezobrazí výzva. Místo toho se pokusí použít soubor cookie uložený ve skrytém vloženém webovém zobrazení.

  Použití této možnosti může selhat. V takovém případě vyvolá výjimku, která vás upozorní, AcquireTokenInteractive že potřebujete interakci s uživatelským rozhraním. Pak použijte jiný Prompt parametr.

• NoPrompt neodesílá žádné výzvy zprostředkovateli identity. Zprostředkovatel identity rozhodne, které prostředí přihlašování je pro uživatele nejvhodnější (jednotné přihlašování nebo výběr účtu).

  Tato možnost je povinná pro úpravy zásad profilu v Azure AD B2C. Další informace najdete v tématu Specifické informace o Azure AD B2C.

WithUseEmbeddedWebView

Tato metoda umožňuje určit, zda chcete vynutit použití vloženého webového zobrazení nebo system WebView (pokud je k dispozici). Další informace najdete v tématu Použití webových prohlížečů.

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

WithExtraScopeToConsent

Tento modifikátor je určený pro pokročilé scénáře, kdy chcete, aby uživatel souhlasil s několika prostředky předem a nechcete používat přírůstkový souhlas. Vývojáři obvykle používají přírůstkový souhlas s MSAL.NET a platformou Microsoft Identity Platform. Další informace najdete v tématu Souhlas uživatele předem pro několik prostředků.

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

WithCustomWebUi

Webové uživatelské rozhraní je mechanismus pro vyvolání prohlížeče. Tento mechanismus může být vyhrazený ovládací prvek WebBrowser uživatelského rozhraní nebo způsob, jak delegovat otevření prohlížeče. MSAL poskytuje implementace webového uživatelského rozhraní pro většinu platforem, ale v těchto případech můžete chtít hostovat prohlížeč sami:

• Máte platformy, které MSAL explicitně nepokrývá, jako je Blazor, Unity a Mono na stolních počítačích.
• Chcete otestovat aplikaci pomocí uživatelského rozhraní a použít automatizovaný prohlížeč, který se dá použít s Selenium.
• Prohlížeč a aplikace, na kterých běží knihovna MSAL, jsou v samostatných procesech.

Abyste toho dosáhli, poskytnete knihovně MSAL start Url, která se musí zobrazit v prohlížeči, aby uživatelé mohli zadávat položky, jako je jejich uživatelské jméno. Po dokončení ověřování musí vaše aplikace předat zpět do knihovny MSAL end Url, která obsahuje kód, který poskytuje Microsoft Entra ID. Hostitel end Url je vždy redirectUri. Pokud chcete zachytit end Url, udělejte jednu z následujících věcí:

• Sledujte přesměrování prohlížeče, dokud redirect Url se nenasadí.
• Přesměrujte prohlížeč na adresu URL, kterou monitorujete.

WithCustomWebUi je bod rozšiřitelnosti, který můžete použít k poskytování vlastního uživatelského rozhraní ve veřejných klientských aplikacích. Můžete také umožnit uživatelům, aby prošli /Authorize koncovým bodem zprostředkovatele identity a nechali je přihlásit a odsouhlasit. MSAL.NET pak může uplatnit ověřovací kód a získat token.

Například v sadě Visual Studio můžete použít WithCustomWebUi k tomu, aby aplikace Elektron (například Visual Studio Feedback) poskytovaly webovou interakci, ale ponechte ji tak, aby MSAL.NET většinu práce. Můžete také použít WithCustomWebUi , pokud chcete poskytnout automatizaci uživatelského rozhraní.

Ve veřejných klientských aplikacích MSAL.NET používá ověřovací klíč pro standard PKCE (Code Exchange) k zajištění dodržování zabezpečení. Kód může uplatnit pouze MSAL.NET. Další informace najdete v dokumentu RFC 7636 – ověřovací klíč pro výměnu kódu veřejnými klienty OAuth.

using Microsoft.Identity.Client.Extensions;

Použití withCustomWebui

Chcete-li použít WithCustomWebUI, postupujte takto:

1. Implementujte rozhraní ICustomWebUi. Další informace najdete na této stránce GitHubu.

2. Implementujte jednu AcquireAuthorizationCodeAsyncmetodu a přijměte adresu URL autorizačního kódu, která MSAL.NET výpočty.

3. Nechte uživatele procházet interakcí s zprostředkovatelem identity a vrátit adresu URL, kterou zprostředkovatel identity použil k volání vaší implementace spolu s autorizačním kódem. Pokud máte problémy, vaše implementace by měla vyvolat MsalExtensionException výjimku pro spolupráci s MSAL.

4. Ve volání AcquireTokenInteractive použijte .WithCustomUI() modifikátor předáním instance vlastního webového uživatelského rozhraní:

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

Tým MSAL.NET přepsal testy uživatelského rozhraní tak, aby používal tento mechanismus rozšiřitelnosti. Pokud vás zajímá, podívejte se na třídu SeleniumWebUI ve zdrojovém kódu MSAL.NET.

Zajištění skvělého prostředí s nástrojem SystemWebViewOptions

V MSAL.NET 4.1 SystemWebViewOptionsmůžete zadat:

• Identifikátor URI, který se má zobrazit (BrowserRedirectError) nebo fragment HTML, pokud se ve webovém prohlížeči systému zobrazíHtmlMessageError chyby přihlášení nebo souhlasu.
• Identifikátor URI, který se má zobrazitHtmlMessageSuccess (BrowserRedirectSuccess) nebo fragment HTML, pokud je přihlášení nebo souhlas úspěšné.
• Akce, která se má spustit, aby se spustil systémový prohlížeč. Vlastní implementaci můžete zadat nastavením delegáta OpenBrowserAsync . Třída také poskytuje výchozí implementaci pro dva prohlížeče: OpenWithEdgeBrowserAsync Pro Microsoft Edge a OpenWithChromeEdgeBrowserAsyncMicrosoft Edge v Chromiu.

Pokud chcete použít tuto strukturu, napište něco jako v následujícím příkladu:

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

Další volitelné parametry

Další volitelné parametry najdete AcquireTokenInteractivev tématu 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

Kód v MSAL pro iOS a 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

V uzlu MSAL získáte tokeny prostřednictvím toku autorizačního kódu s ověřovacím klíčem pro exchange kódu (PKCE). Proces má dva kroky:

1. Aplikace získá adresu URL, kterou lze použít k vygenerování autorizačního kódu. Uživatelé mohou otevřít adresu URL v prohlížeči a zadat své přihlašovací údaje. Pak se přesměrují zpět ( redirectUri zaregistrované během registrace aplikace) s autorizačním kódem.
2. Aplikace předá přijatý autorizační kód acquireTokenByCode() metodě, která ji vyměňuje za přístupový token.

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

MSAL Python 1.7+ poskytuje interaktivní metodu pro získání 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"])

Další kroky

Přejděte k dalšímu článku v tomto scénáři volání webového rozhraní API z desktopové aplikace.