PublicClientApplication Kelas

Sama seperti <xref:ClientApplication.__init__>, kecuali parameter tersebut client_credential akan tetap None.

Note

Apa itu broker, dan mengapa menggunakannya?

Broker adalah komponen yang diinstal pada perangkat Anda.

Broker secara implisit memberi perangkat Anda identitas. Dengan menggunakan broker,

perangkat Anda menjadi faktor yang dapat memenuhi MFA (Autentikasi multifaktor).

Faktor ini akan menjadi wajib

jika admin penyewa mengaktifkan kebijakan Akses Bersyarah (CA) yang sesuai.

Kehadiran broker memungkinkan platform identitas Microsoft

untuk memiliki keyakinan yang lebih tinggi bahwa token dikeluarkan ke perangkat Anda,

dan yang lebih aman.

Manfaat tambahan broker adalah,

ini berjalan sebagai proses berumur panjang dengan OS perangkat Anda,

dan memelihara cachenya sendiri,

sehingga aplikasi berkemampuan broker Anda (bahkan CLI)

dapat secara otomatis SSO dari sesi masuk yang dibuat sebelumnya.

Bagaimana cara memilih menggunakan broker?

Anda dapat mengatur kombinasi parameter keikutsertaan berikut ke true:

Bendera keikutsertaan

Jika aplikasi akan berjalan

Aplikasi telah mendaftarkan ini sebagai URI pengalihan platform Desktop di portal Azure

enable_broker_on_windows

Windows 10+

ms-appx-web://Microsoft. AAD. BrokerPlugin/your_client_id

enable_broker_on_wsl

WSL

ms-appx-web://Microsoft. AAD. BrokerPlugin/your_client_id

enable_broker_on_mac

Mac dengan Company Portal terinstal

msauth.com.msauth.unsignedapp://auth

enable_broker_on_linux

Linux dengan Intune terinstal

https://login.microsoftonline.com/common/oauth2/nativeclient (HARUS diaktifkan)

Menginstal dependensi broker,

misalnya pip install msal[broker]>=1.33,2<.

Uji dengan acquire_token_interactive() dan acquire_token_silent().

Perilaku fallback dukungan broker MSAL Python

MSAL akan mengalami kesalahan, atau mundur secara diam-diam ke alur non-broker.

MSAL akan mengabaikan enable_broker_... dan bypass broker

pada alur autentikasi yang diketahui TIDAK didukung oleh broker.

Ini termasuk ADFS, B2C, dll..

Untuk skenario "can-use-broker" lainnya, silakan lihat di bawah ini.

Kesalahan MSAL keluar saat pengembang aplikasi memilih untuk menggunakan broker

tetapi paket "tingkat menengah" dependensi langsung tidak diinstal.

Pesan kesalahan memandu pengembang aplikasi untuk mendeklarasikan dependensi yang benar

msal[broker].

Kami kesalahan di sini karena kesalahan dapat ditindakkan oleh pengembang aplikasi.

MSAL secara diam-diam "menonaktifkan" broker dan mundur ke non-broker,

ketika ikut serta, dependensi yang diinstal namun gagal diinisialisasi.

Kami mengantisipasi hal ini akan terjadi pada perangkat yang OS-nya terlalu tua

atau komponen broker yang mendasar entah bagaimana tidak tersedia.

Tidak banyak pengembang aplikasi atau pengguna akhir yang dapat melakukannya di sini.

Pada akhirnya, kebijakan akses bersyarah harus

memaksa pengguna untuk beralih ke perangkat lain.

Kesalahan MSAL keluar ketika broker memilih masuk, diinstal, diinisialisasi,

tetapi permintaan token berikutnya gagal.

Konstruktor

PublicClientApplication(client_id, client_credential=None, *, enable_broker_on_windows=None, enable_broker_on_mac=None, enable_broker_on_linux=None, enable_broker_on_wsl=None, **kwargs)

Parameter

Nama Deskripsi
enable_broker_on_windows
Diperlukan
<xref:boolean>

Pengaturan ini hanya efektif jika aplikasi Anda berjalan di Windows 10+. Parameter ini default ke Tidak Ada, yang berarti MSAL tidak akan menggunakan broker.

Baru di MSAL Python 1.25.0.
enable_broker_on_mac
Diperlukan
<xref:boolean>

Pengaturan ini hanya efektif jika aplikasi Anda berjalan di Mac. Parameter ini default ke Tidak Ada, yang berarti MSAL tidak akan menggunakan broker.

Baru di MSAL Python 1.31.0.
enable_broker_on_linux
Diperlukan
<xref:boolean>

Pengaturan ini hanya efektif jika aplikasi Anda berjalan di Linux, termasuk WSL. Parameter ini default ke Tidak Ada, yang berarti MSAL tidak akan menggunakan broker.

Baru di MSAL Python 1.33.0.
enable_broker_on_wsl
Diperlukan
<xref:boolean>

Pengaturan ini hanya efektif jika aplikasi Anda berjalan di WSL. Parameter ini default ke Tidak Ada, yang berarti MSAL tidak akan menggunakan broker.

Baru di MSAL Python 1.33.0.
client_id
Diperlukan
client_credential
Nilai default: None

Parameter Kata Kunci-Saja

Nama Deskripsi
enable_broker_on_windows
Nilai default: None
enable_broker_on_mac
Nilai default: None
enable_broker_on_linux
Nilai default: None
enable_broker_on_wsl
Nilai default: None

Metode

acquire_token_by_device_flow

Dapatkan token oleh objek aliran perangkat, dengan efek polling yang dapat disesuaikan.
acquire_token_interactive

Memperoleh token secara interaktif yaitu melalui browser lokal.

Prasyarat: Dalam portal Azure, konfigurasikan URI Pengalihan "Aplikasi Seluler dan Desktop" Anda sebagai http://localhost. Jika Anda memilih untuk menggunakan broker selama PublicClientApplication pembuatan, aplikasi Anda juga memerlukan URI Pengalihan ini: ms-appx-web://Microsoft.AAD.BrokerPlugin/YOUR_CLIENT_ID
initiate_device_flow

Mulai instans Aliran Perangkat, yang akan digunakan di acquire_token_by_device_flow.

acquire_token_by_device_flow

Dapatkan token oleh objek aliran perangkat, dengan efek polling yang dapat disesuaikan.

acquire_token_by_device_flow(flow, claims_challenge=None, **kwargs)

Parameter

Nama Deskripsi
flow
Diperlukan
dict

Dict yang sebelumnya dihasilkan oleh initiate_device_flow. Secara default, efek polling metode ini akan memblokir utas saat ini. Anda dapat membatalkan perulangan polling kapan saja, dengan mengubah nilai kunci "expires_at" alur menjadi 0.
claims_challenge

Parameter claims_challenge meminta klaim tertentu yang diminta oleh penyedia sumber daya dalam bentuk arahan claims_challenge di header www-authenticate untuk dikembalikan dari Titik Akhir UserInfo dan/atau di Token ID dan/atau Token Akses. Ini adalah string objek JSON yang berisi daftar klaim yang diminta dari lokasi ini.

Nilai default: None

Mengembalikan

Jenis Deskripsi

Dict yang mewakili respons json dari Microsoft Entra:

  • Respons yang berhasil akan berisi kunci "access_token",

  • respons kesalahan akan berisi "kesalahan" dan biasanya "error_description".

acquire_token_interactive

Memperoleh token secara interaktif yaitu melalui browser lokal.

Prasyarat: Dalam portal Azure, konfigurasikan URI Pengalihan "Aplikasi Seluler dan Desktop" Anda sebagai http://localhost. Jika Anda memilih untuk menggunakan broker selama PublicClientApplication pembuatan, aplikasi Anda juga memerlukan URI Pengalihan ini: ms-appx-web://Microsoft.AAD.BrokerPlugin/YOUR_CLIENT_ID

acquire_token_interactive(scopes, prompt=None, login_hint=None, domain_hint=None, claims_challenge=None, timeout=None, port=None, extra_scopes_to_consent=None, max_age=None, parent_window_handle=None, on_before_launching_ui=None, auth_scheme=None, **kwargs)

Parameter

Nama Deskripsi
scopes
Diperlukan
list

Ini adalah daftar string peka huruf besar/kecil.
prompt
str

Secara default, tidak ada nilai prompt yang akan dikirim, bahkan string "none". Anda harus menentukan nilai secara eksplisit. Nilai yang valid adalah konstanta yang ditentukan dalam <xref:msal.Prompt>.

Nilai default: None
login_hint
str

Optional. Pengidentifikasi pengguna. Umumnya Nama Prinsipal Pengguna (UPN).

Nilai default: None
domain_hint

Dapat menjadi salah satu "konsumen" atau "organisasi" atau domain penyewa Anda "contoso.com". Jika disertakan, ini akan melewati proses penemuan berbasis email yang dilalui pengguna di halaman masuk, yang mengarah ke pengalaman pengguna yang sedikit lebih efisien. Informasi selengkapnya tentang kemungkinan nilai yang tersedia di dokumen Auth Code Flow dan dokumen domain_hint.

Nilai default: None
claims_challenge

Parameter claims_challenge meminta klaim tertentu yang diminta oleh penyedia sumber daya dalam bentuk arahan claims_challenge di header www-authenticate untuk dikembalikan dari Titik Akhir UserInfo dan/atau di Token ID dan/atau Token Akses. Ini adalah string objek JSON yang berisi daftar klaim yang diminta dari lokasi ini.

Nilai default: None
timeout
int

Metode ini akan memblokir utas saat ini. Parameter ini menentukan nilai batas waktu dalam detik. Nilai None default berarti menunggu tanpa batas waktu.

Nilai default: None
port
int

Port yang akan digunakan untuk mendengarkan respons autentikasi masuk. Secara default, kita akan menggunakan port yang dialokasikan sistem. (Sisa redirect_uri dikodekan secara permanen sebagai http://localhost.)

Nilai default: None
extra_scopes_to_consent
list

"Cakupan ekstra untuk disepakat" adalah konsep yang hanya tersedia dalam Microsoft Entra. Ini mengacu pada sumber daya lain yang mungkin ingin Anda minta untuk disetujui, dalam interaksi yang sama, tetapi untuk itu Anda tidak akan mendapatkan kembali token untuk dalam operasi khusus ini.

Nilai default: None
max_age
int

OPSIONAL. Usia Autentikasi Maksimum. Menentukan waktu yang diperbolehkan berlalu dalam detik sejak terakhir kali End-User secara aktif diautentikasi. Jika waktu yang berlalu lebih besar dari nilai ini, platform identitas Microsoft akan secara aktif mengautentikasi ulang Pengguna Akhir.

Python MSAL juga akan secara otomatis memvalidasi auth_time dalam token ID.

Baru dalam versi 1.15.

Nilai default: None
parent_window_handle
int

OPSIONAL.

  • Jika aplikasi Anda tidak memilih untuk menggunakan broker, Anda tidak perlu menyediakan parent_window_handle di sini.

  • Jika aplikasi Anda memilih untuk menggunakan broker, parent_window_handle diperlukan.

    • Jika aplikasi Anda adalah aplikasi GUI yang berjalan di sistem Windows atau Mac, Anda juga diharuskan untuk menyediakan handel jendelanya, sehingga jendela masuk akan muncul di atas jendela Anda.

    • Jika aplikasi Anda adalah aplikasi konsol yang berjalan di sistem Windows atau Mac, Anda dapat menggunakan tempat penampung PublicClientApplication.CONSOLE_WINDOW_HANDLE.

Sebagian besar skrip Python adalah aplikasi konsol.

Baru dalam versi 1.20.0.

Nilai default: None
on_before_launching_ui
<xref:function>

Panggilan balik dengan bentuk lambda ui="xyz", **kwargs: print("A {} will be launched".format(ui)), di mana ui akan menjadi "browser" atau "broker". Anda dapat menggunakannya untuk memberi tahu pengguna akhir Anda untuk mengharapkan jendela pop-up.

Baru dalam versi 1.20.0.

Nilai default: None
auth_scheme
object

Anda dapat memberikan msal.auth_scheme.PopAuthScheme objek sehingga MSAL akan mendapatkan token Proof-of-Possession (POP) untuk Anda.

Baru dalam versi 1.26.0.

Nilai default: None

Mengembalikan

Jenis Deskripsi

  • Dict yang tidak berisi kunci "kesalahan", dan biasanya berisi kunci "access_token".

  • Dict yang berisi kunci "kesalahan", ketika refresh token gagal.

initiate_device_flow

Mulai instans Aliran Perangkat, yang akan digunakan di acquire_token_by_device_flow.

initiate_device_flow(scopes=None, *, claims_challenge=None, **kwargs)

Parameter

Nama Deskripsi
scopes
list[str]

Cakupan yang diminta untuk mengakses API yang dilindungi (sumber daya).

Nilai default: None

Parameter Kata Kunci-Saja

Nama Deskripsi
claims_challenge
Nilai default: None

Mengembalikan

Jenis Deskripsi

Dict yang mewakili objek Aliran Perangkat yang baru dibuat.

  • Respons yang berhasil akan berisi kunci "user_code", antara lain

  • respons kesalahan akan berisi beberapa pasangan kunci/nilai lain yang dapat dibaca.

Atribut

CONSOLE_WINDOW_HANDLE 

CONSOLE_WINDOW_HANDLE = <object object>

DEVICE_FLOW_CORRELATION_ID 

DEVICE_FLOW_CORRELATION_ID = '_correlation_id'