Aplikasi desktop yang memanggil API web: Mendapatkan token secara interaktif

Contoh berikut ini memperlihatkan kode minimal untuk mendapatkan token secara interaktif untuk membaca profil pengguna dengan Microsoft Graph.

.NET

Kode dalam 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();
}

Parameter wajib

AcquireTokenInteractive hanya memiliki satu parameter wajib, scopes. Ini berisi enumerasi string yang menentukan cakupan yang diperlukan token. Jika token adalah untuk Microsoft Graph, Anda dapat menemukan cakupan yang diperlukan dalam referensi API dari setiap Microsoft Graph API di bagian bernama "Izin." Misalnya, untuk mencantumkan kontak pengguna, Anda harus menggunakan dan User.ReadContacts.Read sebagai cakupan. Untuk informasi selengkapnya, lihat Referensi izin Microsoft Graph.

Pada aplikasi desktop dan seluler, penting untuk menentukan induk dengan menggunakan .WithParentActivityOrWindow. Dalam banyak kasus, itu adalah persyaratan dan MSAL akan melemparkan pengecualian.

Untuk aplikasi desktop, lihat Handel jendela induk.

Untuk aplikasi seluler, sediakan Activity (Android) atau UIViewController (iOS).

Parameter opsional dalam MSAL.NET

WithParentActivityOrWindow

UI penting karena interaktif. AcquireTokenInteractive memiliki satu parameter opsional tertentu yang dapat menentukan (untuk platform yang mendukungnya) UI induk. Saat Anda menggunakan .WithParentActivityOrWindow dalam aplikasi desktop, aplikasi ini memiliki jenis berbeda yang bergantung pada platform.

Atau, Anda dapat menghilangkan parameter jendela induk opsional untuk membuat jendela, jika Anda tidak ingin mengontrol tempat dialog masuk muncul di layar. Opsi ini berlaku untuk aplikasi yang didasarkan pada baris perintah, digunakan untuk meneruskan panggilan ke layanan back-end lainnya, dan tidak memerlukan jendela apa pun untuk interaksi pengguna.

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

Keterangan:

• Pada .NET Standard, nilai yang diharapkan object ada Activity di Android, UIViewController di iOS, NSWindow di Mac, dan IWin32Window atau IntPr di Windows.

• Pada Windows, Anda harus AcquireTokenInteractive menelepon dari utas UI sehingga browser yang disematkan mendapatkan konteks sinkronisasi UI yang sesuai. Tidak memanggil dari utas UI dapat menyebabkan pesan tidak dipompa dengan benar dan menyebabkan skenario kebuntuan dengan UI. Salah satu cara memanggil Microsoft Authentication Library (MSAL) dari utas UI jika Anda belum menggunakan utas UI adalah dengan menggunakan Dispatcher Windows Presentation Foundation (WPF).

• Jika Anda menggunakan WPF, untuk mendapatkan jendela dari kontrol WPF, Anda dapat menggunakan kelas WindowInteropHelper.Handle. Kemudian panggilan berasal dari kontrol WPF ( this ):

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

WithPrompt

Anda menggunakan WithPrompt() untuk mengontrol interaktivitas dengan pengguna dengan menentukan perintah. Anda dapat mengontrol perilaku yang tepat dengan menggunakan struktur Microsoft.Identity.Client.Prompt .

Struktur mendefinisikan konstanta berikut:

• SelectAccount memaksa layanan token keamanan (STS) untuk menyajikan dialog pemilihan akun yang berisi akun tempat pengguna memiliki sesi. Ini adalah opsi default. Ini berguna ketika Anda ingin membiarkan pengguna memilih di antara identitas yang berbeda.

  Opsi ini mendorong MSAL untuk mengirim prompt=select_account ke penyedia identitas. Ini memberikan pengalaman terbaik berdasarkan informasi yang tersedia, seperti akun dan kehadiran sesi untuk pengguna. Jangan mengubahnya kecuali Anda memiliki alasan yang baik.

• Consent memungkinkan Anda memaksa pengguna untuk dimintai persetujuan, bahkan jika aplikasi memberikan persetujuan sebelumnya. Dalam hal ini, MSAL mengirim prompt=consent ke penyedia identitas. Anda dapat menggunakan opsi ini di beberapa aplikasi yang berfokus pada keamanan di mana tata kelola organisasi menuntut kotak dialog persetujuan muncul setiap kali pengguna membuka aplikasi.

• ForceLogin memungkinkan Anda meminta aplikasi meminta kredensial kepada pengguna, meskipun permintaan pengguna ini mungkin tidak diperlukan. Opsi ini dapat berguna untuk membiarkan pengguna masuk lagi jika akuisisi token gagal. Dalam hal ini, MSAL mengirim prompt=login ke penyedia identitas. Organisasi terkadang menggunakan opsi ini dalam aplikasi yang berfokus pada keamanan di mana tata kelola menuntut pengguna untuk masuk setiap kali mereka mengakses bagian tertentu dari aplikasi.

• Create memicu pengalaman pendaftaran untuk identitas eksternal dengan mengirim prompt=create ke IdP. Aplikasi Azure Active Directory B2C (Azure AD B2C) tidak boleh mengirim perintah ini. Untuk informasi selengkapnya tentang pengaturan ini, lihat Menambahkan alur pengguna pendaftaran layanan mandiri ke aplikasi.

• Never (hanya untuk .NET 4.5 dan Windows Runtime) tidak meminta pengguna. Sebagai gantinya, ia mencoba menggunakan cookie yang disimpan dalam tampilan web tersembunyi yang disematkan.

  Penggunaan opsi ini mungkin gagal. Dalam hal ini, AcquireTokenInteractive melemparkan pengecualian untuk memberi tahu Anda bahwa Anda memerlukan interaksi UI. Kemudian, gunakan parameter lain Prompt .

• NoPrompt tidak mengirim permintaan apa pun ke penyedia identitas. IdP memutuskan pengalaman masuk mana yang terbaik untuk pengguna (akses menyeluruh atau memilih akun).

  Opsi ini wajib untuk mengedit kebijakan profil di Azure AD B2C. Untuk informasi selengkapnya, lihat Sesi Microsoft Azure AD B2C.

WithUseEmbeddedWebView

Metode ini memungkinkan Anda untuk menentukan apakah Anda ingin memaksa penggunaan WebView yang disematkan atau WebView sistem (bila tersedia). Untuk informasi selengkapnya, lihat Penggunaan browser web.

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

WithExtraScopeToConsent

Pengubah ini untuk skenario tingkat lanjut di mana Anda ingin pengguna menyetujui beberapa sumber daya di muka dan Anda tidak ingin menggunakan persetujuan inkremental. Pengembang biasanya menggunakan persetujuan inkremental dengan MSAL.NET dan platform identitas Microsoft. Untuk informasi selengkapnya, lihat Meminta persetujuan pengguna di muka untuk beberapa sumber daya.

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

WithCustomWebUi

UI web adalah mekanisme untuk memanggil browser. Mekanisme ini dapat menjadi kontrol UI WebBrowser khusus atau cara untuk mendelegasikan membuka browser. MSAL menyediakan implementasi UI web untuk sebagian besar platform, tetapi Anda mungkin ingin menghosting browser sendiri dalam kasus ini:

• Anda memiliki platform yang tidak dicakup MSAL secara eksplisit, seperti Blazor, Unity, dan Mono di desktop.
• Anda ingin UI menguji aplikasi Anda dan menggunakan browser otomatis yang dapat digunakan dengan Selenium.
• Browser dan aplikasi yang menjalankan MSAL berada dalam proses terpisah.

Untuk mencapai hal ini, Anda memberikan kepada MSAL start Url, yang perlu ditampilkan di browser sehingga pengguna dapat memasukkan item seperti nama pengguna mereka. Setelah autentikasi selesai, aplikasi Anda perlu meneruskan kembali ke MSAL end Url, yang berisi kode yang disediakan MICROSOFT Entra ID. Tuan rumah end Url selalu redirectUri. Untuk mencegat end Url, lakukan salah satu hal berikut:

• Pantau pengalihan browser redirect Url hingga tertabrak.
• Minta browser mengalihkan ke URL yang Anda pantau.

WithCustomWebUi adalah titik ekstensifikasi yang dapat Anda gunakan untuk menyediakan UI Anda sendiri di aplikasi klien publik. Anda juga dapat membiarkan pengguna melalui /Authorize titik akhir penyedia identitas dan membiarkan mereka masuk dan menyetujui. MSAL.NET kemudian dapat menukarkan kode autentikasi dan mendapatkan token.

Misalnya, Anda dapat menggunakan WithCustomWebUi di Visual Studio untuk memiliki aplikasi Electron (misalnya, Umpan Balik Visual Studio) menyediakan interaksi web, tetapi membiarkannya MSAL.NET untuk melakukan sebagian besar pekerjaan. Anda juga dapat menggunakan WithCustomWebUi jika Anda ingin menyediakan otomatisasi UI.

Dalam aplikasi klien publik, MSAL.NET menggunakan standar Proof Key for Code Exchange (PKCE) untuk memastikan bahwa keamanan dihormati. Hanya MSAL.NET yang dapat menukarkan kode. Untuk informasi selengkapnya, lihat RFC 7636 - Kunci Bukti untuk Pertukaran Kode oleh Klien Publik OAuth.

using Microsoft.Identity.Client.Extensions;

Gunakan WithCustomWebUI

Untuk menggunakan WithCustomWebUI, ikuti langkah-langkah berikut:

1. Implementasikan ICustomWebUi antarmuka. Untuk informasi selengkapnya, lihat halaman GitHub ini.

2. Terapkan satu AcquireAuthorizationCodeAsyncmetode dan terima URL kode otorisasi yang MSAL.NET komputasi.

3. Biarkan pengguna melalui interaksi dengan penyedia identitas dan mengembalikan URL yang digunakan penyedia identitas untuk memanggil kembali implementasi Anda, bersama dengan kode otorisasi. Jika Anda memiliki masalah, implementasi Anda harus melemparkan MsalExtensionException pengecualian untuk bekerja sama dengan MSAL.

4. Dalam panggilan Anda AcquireTokenInteractive , gunakan pengubah .WithCustomUI() dengan meneruskan instans UI web kustom Anda:

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

Tim MSAL.NET telah menulis ulang tes UI untuk menggunakan mekanisme ekstensifikasi ini. Jika Anda tertarik, lihat kelas SeleniumWebUI di kode sumber MSAL.NET.

Memberikan pengalaman hebat dengan SystemWebViewOptions

Dari MSAL.NET 4.1, SystemWebViewOptions Anda dapat menentukan:

• URI untuk masuk ke (BrowserRedirectError) atau fragmen HTML untuk ditampilkan (HtmlMessageError) jika kesalahan masuk atau persetujuan muncul di browser web sistem.
• URI untuk masuk ke (BrowserRedirectSuccess) atau fragmen HTML untuk ditampilkan (HtmlMessageSuccess) jika masuk atau persetujuan berhasil.
• Aksi yang dijalankan untuk memulai penjelajah sistem. Anda dapat menyediakan implementasi Anda sendiri dengan menetapkan delegasi OpenBrowserAsync. Kelas ini juga menyediakan implementasi default untuk dua browser: OpenWithEdgeBrowserAsync untuk Microsoft Edge dan OpenWithChromeEdgeBrowserAsync untuk Microsoft Edge di Chromium.

Untuk menggunakan struktur ini, tulislah sesuatu seperti contoh berikut:

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

Parameter opsional lainnya

Untuk mempelajari parameter opsional lainnya untuk AcquireTokenInteractive, lihat 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

Kode di MSAL untuk iOS dan 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

Dalam MSAL Node, Anda memperoleh token melalui aliran kode otorisasi dengan Proof Key for Code Exchange (PKCE). Proses ini memiliki dua langkah:

1. Aplikasi ini mendapatkan URL yang dapat digunakan untuk menghasilkan kode otorisasi. Pengguna dapat membuka URL di browser dan memasukkan kredensial mereka. Mereka kemudian dialihkan kembali ke redirectUri (terdaftar selama pendaftaran aplikasi) dengan kode otorisasi.
2. Aplikasi meneruskan kode otorisasi yang diterima ke acquireTokenByCode() metode , yang menukarnya dengan token akses.

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+ menyediakan metode interaktif untuk memperoleh token:

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

Langkah berikutnya

Lanjutkan ke artikel berikutnya dalam skenario ini, yaitu Panggil API web dari aplikasi desktop.