Webes API-kat hívó asztali alkalmazás: Jogkivonat interaktív beszerzése

Az alábbi példa minimális kódot mutat be, amellyel interaktívan lekérheti a jogkivonatot a felhasználó profiljának a Microsoft Graphtal való olvasásához.

.NET

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

Kötelező paraméterek

AcquireTokenInteractive csak egy kötelező paramétert, scopes. Sztringek számbavételét tartalmazza, amelyek meghatározzák azokat a hatóköröket, amelyekhez jogkivonat szükséges. Ha a jogkivonat a Microsoft Graphhoz készült, a szükséges hatóköröket az egyes Microsoft Graph API-k API-referenciajában, az "Engedélyek" című szakaszban találja. A felhasználó névjegyeinek listázásához például mindkettőt User.Read és Contacts.Read hatókört is használnia kell. További információ: Microsoft Graph-engedélyek referenciája.

Asztali és mobilalkalmazások esetén is fontos, hogy a szülőt a használatával .WithParentActivityOrWindowadja meg. Ez sok esetben követelmény, és az MSAL kivételeket fog eredményezni.

Asztali alkalmazások esetén lásd : Szülőablak fogópontok.

Mobilalkalmazások esetén adja meg Activity az (Android) vagy UIViewController az (iOS) elemet.

Választható paraméterek a MSAL.NET

WithParentActivityOrWindow

A felhasználói felület azért fontos, mert interaktív. AcquireTokenInteractive egy adott opcionális paramétert tartalmaz, amely megadhatja (az azt támogató platformok esetében) a szülő felhasználói felületet. Ha asztali alkalmazásban használja .WithParentActivityOrWindow , az más típusú, amely a platformtól függ.

Ha nem szeretné szabályozni, hogy a bejelentkezési párbeszédpanel hol jelenik meg a képernyőn, kihagyhatja az opcionális szülőablak paramétert. Ez a beállítás a parancssoron alapuló alkalmazásokra vonatkozik, amelyek hívásokat adnak át bármely más háttérszolgáltatásnak, és nincs szükség windowsra a felhasználói beavatkozáshoz.

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

Megjegyzések:

• A .NET Standard esetében a várt object érték Activity Androidon, UIViewController iOS-en, NSWindow Macen és IWin32WindowIntPr Windowson érhető el.

• Windows rendszeren a felhasználói felületi szálról kell hívást kezdeményeznie AcquireTokenInteractive , hogy a beágyazott böngésző megkapja a megfelelő felhasználói felület szinkronizálási környezetét. Ha a felhasználói felületi szálról nem hív, előfordulhat, hogy az üzenetek nem megfelelően pumpálnak, és holtpontot okoznak a felhasználói felületen. A Microsoft Authentication Library (MSAL) meghívásának egyik módja a felhasználói felületi szálról, ha még Dispatcher nem használja a felhasználói felületi szálat a Windows megjelenítési alaprendszer (WPF) használatával.

• Ha WPF-et használ, az osztályt használhatja WindowInteropHelper.Handle egy WPF-vezérlő ablakának lekéréséhez. Ezután a hívás egy WPF-vezérlőből (this):

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

WithPrompt

WithPrompt() A felhasználóval való interaktivitás szabályozásához adjon meg egy kérést. A pontos viselkedést a Microsoft.Identity.Client.Prompt struktúra segítségével szabályozhatja.

A struktúra a következő állandókat határozza meg:

• SelectAccount kényszeríti a biztonsági jogkivonat-szolgáltatást (STS) a fiókválasztási párbeszédpanel megjelenítésére, amely azokat a fiókokat tartalmazza, amelyekhez a felhasználó munkamenetet használ. Ez az alapértelmezett beállítás. Ez akkor hasznos, ha lehetővé szeretné tenni, hogy a felhasználók különböző identitások közül válasszanak.

  Ez a beállítás az MSAL-t az identitásszolgáltatónak küldi prompt=select_account el. A lehető legjobb élményt nyújtja a rendelkezésre álló információk alapján, például a fiók és a munkamenet jelenléte alapján a felhasználó számára. Ne változtassa meg, hacsak nincs jó oka.

• Consent lehetővé teszi, hogy kényszerítse a felhasználót a hozzájárulás megadására, még akkor is, ha az alkalmazás korábban hozzájárulást adott. Ebben az esetben az MSAL elküldi prompt=consent az identitásszolgáltatónak. Ezt a lehetőséget bizonyos, biztonságra összpontosító alkalmazásokban is használhatja, ahol a szervezet szabályozása megköveteli, hogy a jóváhagyás párbeszédpanel minden alkalommal megjelenjen, amikor a felhasználó megnyitja az alkalmazást.

• ForceLogin lehetővé teszi, hogy az alkalmazás kérje meg a felhasználót a hitelesítő adatok megadására, még akkor is, ha ez a felhasználói kérés nem feltétlenül szükséges. Ez a beállítás hasznos lehet, ha a felhasználó ismét bejelentkezik, ha a jogkivonatok beszerzése meghiúsul. Ebben az esetben az MSAL elküldi prompt=login az identitásszolgáltatónak. A szervezetek néha használják ezt a lehetőséget a biztonságra összpontosító alkalmazásokban, ahol az irányítás megköveteli, hogy a felhasználók minden alkalommal jelentkezzenek be, amikor egy alkalmazás adott részeihez férnek hozzá.

• Create a külső identitások regisztrációjának aktiválása az identitásszolgáltatónak küldött üzenettel prompt=create . Az Azure Active Directory B2C (Azure AD B2C) alkalmazások nem küldhetik el ezt a kérést. További információ: Önkiszolgáló regisztrációs felhasználói folyamat hozzáadása egy alkalmazáshoz.

• Never(csak .NET 4.5 és Windows-futtatókörnyezet esetén) nem kéri a felhasználót. Ehelyett a rejtett beágyazott webes nézetben tárolt cookie-t próbálja használni.

  Ennek a beállításnak a használata sikertelen lehet. Ebben az esetben kivételt küld, AcquireTokenInteractive amely értesíti Önt arról, hogy felhasználói felületi interakcióra van szüksége. Ezután használjon egy másik Prompt paramétert.

• NoPrompt nem küld kérést az identitásszolgáltatónak. Az identitásszolgáltató dönti el, hogy melyik bejelentkezési élmény a legjobb a felhasználó számára (egyszeri bejelentkezés vagy fiók kiválasztása).

  Ez a beállítás kötelező az Azure AD B2C profilszabályzatainak szerkesztéséhez. További információ: Azure AD B2C-specifikusak.

WithUseEmbeddedWebView

Ez a módszer lehetővé teszi annak megadását, hogy a beágyazott WebView vagy a rendszer WebView használatát kényszerítse-e (ha elérhető). További információ: Webböngészők használata.

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

WithExtraScopeToConsent

Ez a módosító olyan speciális helyzetekhez készült, ahol azt szeretné, hogy a felhasználó több erőforráshoz is hozzájáruljon, és nem szeretne növekményes hozzájárulást használni. A fejlesztők általában növekményes hozzájárulást használnak MSAL.NET és a Microsoft Identitásplatform. További információ: A felhasználó beleegyezése több erőforráshoz.

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

WithCustomWebUi

A webes felhasználói felület egy böngésző meghívására szolgáló mechanizmus. Ez a mechanizmus lehet dedikált felhasználói felületi WebBrowser-vezérlő, vagy a böngésző megnyitásának delegálása. Az MSAL webes felhasználói felületi implementációkat biztosít a legtöbb platformhoz, de az alábbi esetekben érdemes lehet saját maga üzemeltetni a böngészőt:

• Olyan platformokkal rendelkezik, amelyeket az MSAL kifejezetten nem fed le, például a Blazort, a Unityt és a Mono-t asztali gépeken.
• Tesztelni szeretné az alkalmazást, és egy Selenium használatával használható automatizált böngészőt szeretne használni.
• A böngésző és az MSAL-t futtató alkalmazás külön folyamatokban van.

Ennek eléréséhez az MSAL-t start Urlkell megadnia, amelyet meg kell jeleníteni egy böngészőben, hogy a felhasználók olyan elemeket adjanak meg, mint a felhasználónév. A hitelesítés befejezése után az alkalmazásnak vissza kell adnia az MSAL-nak end Url, amely a Microsoft Entra ID által biztosított kódot tartalmazza. A gazdagép end Url mindig redirectUri. A lehallgatáshoz end Urltegye az alábbi műveletek egyikét:

• A böngésző átirányításainak figyelése, amíg el nem redirect Url éri a találatot.
• A böngészőt átirányíthatja egy figyelt URL-címre.

WithCustomWebUi egy bővíthetőségi pont, amellyel saját felhasználói felületet biztosíthat a nyilvános ügyfélalkalmazásokban. Azt is engedélyezheti, hogy a felhasználók végighaladjanak az /Authorize identitásszolgáltató végpontja mellett, és beengedjék őket a bejelentkezésbe és a hozzájárulásba. MSAL.NET ezután beválthatja a hitelesítési kódot, és lekérheti a jogkivonatot.

Használhatja például a Visual Studióban, WithCustomWebUi hogy az Electron-alkalmazások (például a Visual Studio Feedback) biztosítják a webes interakciót, de a legtöbb munka elvégzésére hagyja MSAL.NET. Akkor is használhatja WithCustomWebUi , ha felhasználói felület automatizálását szeretné biztosítani.

Nyilvános ügyfélalkalmazásokban MSAL.NET a Code Exchange (PKCE) proof key for Code Exchange (PKCE) szabványt használja a biztonság tiszteletben tartásának biztosítása érdekében. A kódot csak MSAL.NET válthatja be. További információ: RFC 7636 – Proof Key for Code Exchange by OAuth Public Clients.

using Microsoft.Identity.Client.Extensions;

A WithCustomWebUI használata

A használathoz WithCustomWebUIkövesse az alábbi lépéseket:

1. Implementálja az ICustomWebUi felületet. További információkért tekintse meg ezt a GitHub-oldalt.

2. Implementálhat egy metódust AcquireAuthorizationCodeAsync, és elfogadhatja a számítási MSAL.NET engedélyezési kód URL-címét.

3. Hagyja, hogy a felhasználó végighaladjon az identitásszolgáltatóval folytatott interakción, és adja vissza az identitásszolgáltató által a megvalósítás visszahívásához használt URL-címet, valamint az engedélyezési kódot. Ha problémák merülnek fel, a megvalósítás kivételt MsalExtensionException képez az MSAL-jal való együttműködés alól.

4. A hívásban AcquireTokenInteractive használja a .WithCustomUI() módosítót az egyéni webes felhasználói felület példányának átadásával:

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

A MSAL.NET csapat újraírta a felhasználói felületi teszteket ennek a bővíthetőségi mechanizmusnak a használatához. Ha érdekli, tekintse meg a SeleniumWebUI osztályt a MSAL.NET forráskódban.

Nagyszerű élmény a SystemWebViewOptions használatával

A MSAL.NET 4.1-ben SystemWebViewOptionsmegadhatja a következőket:

• A megjelenítendő URI (BrowserRedirectError) vagy a megjelenítendő HTML-töredék (HtmlMessageError), ha bejelentkezési vagy hozzájárulási hibák jelennek meg a rendszer webböngészőjében.
• A bejelentkezés vagy a hozzájárulás sikeressége esetén a megjelenítendőHtmlMessageSuccess (BrowserRedirectSuccess) HTML-töredékre () URI.
• A rendszerböngésző elindításához futtatandó művelet. A meghatalmazott beállításával saját megvalósítást OpenBrowserAsync biztosíthat. Az osztály két böngészőhöz is biztosít alapértelmezett implementációt: OpenWithEdgeBrowserAsync a Microsoft Edge-hez és OpenWithChromeEdgeBrowserAsync a Microsoft Edge-hez a Chromiumon.

A struktúra használatához írjon az alábbi példához hasonlót:

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

Egyéb választható paraméterek

A további választható paraméterekkel AcquireTokenInteractivekapcsolatban lásd : 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 iOS és macOS MSAL rendszerben

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

Az MSAL-csomópontban jogkivonatokat szerezhet be az engedélyezési kódfolyamaton keresztül a Code Exchange-hez (PKCE) készült Proof Key használatával. A folyamat két lépésből áll:

1. Az alkalmazás beszerez egy URL-címet, amely egy engedélyezési kód létrehozásához használható. A felhasználók megnyithatják az URL-címet egy böngészőben, és megadhatja a hitelesítő adataikat. Ezután vissza redirectUri lesznek irányítva (az alkalmazásregisztráció során regisztrálva) egy engedélyezési kóddal.
2. Az alkalmazás átadja a kapott engedélyezési kódot a acquireTokenByCode() metódusnak, amely egy hozzáférési jogkivonatra cseréli azt.

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

Az MSAL Python 1.7+ egy interaktív módszert biztosít egy jogkivonat beszerzéséhez:

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

Következő lépések

Lépjen tovább a következő cikkre ebben a forgatókönyvben: Webes API meghívása az asztali alkalmazásból.