ClientApplication Kelas

Aplikasi Anda memiliki client_id setelah mendaftarkannya di pusat admin Microsoft Entra.

Untuk PublicClientApplication, Anda menggunakan Tidak Ada di sini.

Untuk ConfidentialClientApplication, ini mendukung banyak format input yang berbeda untuk skenario yang berbeda.

Dukungan menggunakan rahasia klien. Cukup umpan dalam string, seperti "your client secret".

Dukungan menggunakan sertifikat dalam format X.509 (.pem)Deprecated karena menggunakan thumbprint SHA-1,

kecuali Anda masih menggunakan ADFS yang hanya mendukung thumbprint SHA-1. Silakan gunakan opsi .pfx yang didokumenkan nanti di halaman ini. Umpan dalam dict dalam formulir ini:

   {
       "private_key": "...-----BEGIN PRIVATE KEY-----... in PEM format",
       "thumbprint": "An SHA-1 thumbprint such as A1B2C3D4E5F6..."
           "Changed in version 1.35.0, if thumbprint is absent"
           "and a public_certificate is present, MSAL will"
           "automatically calculate an SHA-256 thumbprint instead.",
       "passphrase": "Needed if the private_key is encrypted (Added in version 1.6.0)",
       "public_certificate": "...-----BEGIN CERTIFICATE-----...",  # Needed if you use Subject Name/Issuer auth. Added in version 0.5.0.
   }

Python MSAL memerlukan "private_key" dalam format PEM. Jika sertifikasi Anda dalam format PKCS12 (.pfx), Anda dapat mengonversinya ke format X.509 (.pem), dengan openssl pkcs12 -in file.pfx -out file.pem -nodes. Thumbprint tersedia di pendaftaran aplikasi Anda di portal Azure. Atau, Anda dapat menghitung thumbprint. public_certificate (opsional) adalah sertifikat kunci publik yang akan dikirim melalui header JWT 'x5c'. Ini berguna ketika Anda menggunakan Nama Subjek/Autentikasi Penerbit yang merupakan pendekatan untuk memungkinkan rotasi sertifikat yang lebih mudah. Per spesifikasi, "sertifikat yang berisi kunci umum yang sesuai dengan kunci yang digunakan untuk menandatangani JWS secara digital HARUS menjadi sertifikat pertama. Ini MUNGKIN diikuti oleh sertifikat tambahan, dengan setiap sertifikat berikutnya menjadi sertifikat yang digunakan untuk mensertifikasi sertifikat sebelumnya." Namun, penerbit sertifikat Anda dapat menggunakan urutan yang berbeda. Jadi, jika upaya Anda berakhir dengan kesalahan AADSTS700027 - "Nilai tanda tangan yang disediakan tidak cocok dengan nilai tanda tangan yang diharapkan", Anda dapat mencoba hanya menggunakan sertifikasi daun (dalam format PEM/str) sebagai gantinya.

Mendukung pernyataan mentah yang diperoleh dari tempat lainDitambahkan dalam versi 1.13.0:

Ini juga bisa menjadi pernyataan yang sepenuhnya telah ditandatangani sebelumnya bahwa Anda telah menyusun diri Anda sendiri. Cukup teruskan kontainer yang hanya berisi kunci "client_assertion", seperti ini:

   {
       "client_assertion": "...a JWT with claims aud, exp, iss, jti, nbf, and sub..."
   }

Mendukung membaca sertifikat klien dari file PFX Penggunaan ini akan secara otomatis menggunakan thumbprint SHA-256 sertifikat. Ditambahkan dalam versi 1.29.0:

Umpan dalam kamus yang berisi jalur ke file PFX:

   {
       "private_key_pfx_path": "/path/to/your.pfx",  # Added in version 1.29.0
       "public_certificate": True,  # Only needed if you use Subject Name/Issuer auth. Added in version 1.30.0
       "passphrase": "Passphrase if the private_key is encrypted (Optional)",
   }

Perintah berikut akan menghasilkan file .pfx dari file .key dan .pem Anda:

   openssl pkcs12 -export -out certificate.pfx -inkey privateKey.key -in certificate.pem

Nama Subjek/Pengeluar Sertifikat Auth adalah pendekatan untuk memungkinkan rotasi sertifikat yang lebih mudah. Jika file .pfx Anda berisi kunci privat dan sertifikasi publik, Anda dapat ikut serta untuk Nama Subjek/Pengeluar Sertifikat Auth dengan mengatur "public_certificate" ke True.

Ditambahkan dalam versi 0.5.0: Ini adalah kamus klaim tambahan yang akan ditandatangani oleh kunci privat ini ConfidentialClientApplication . Misalnya, Anda dapat menggunakan {"client_ip": "x.x.x.x"}. Anda juga dapat mengambil alih salah satu klaim default berikut:

   {
       "aud": the_token_endpoint,
       "iss": self.client_id,
       "sub": same_as_issuer,
       "exp": now + 10_min,
       "iat": now,
       "jti": a_random_uuid
   }

URL yang mengidentifikasi otoritas token. Ini harus dari format https://login.microsoftonline.com/your_tenant Secara default, kami akan menggunakan https://login.microsoftonline.com/common

Diubah dalam versi 1.17: Anda juga dapat menggunakan konstanta yang telah ditentukan sebelumnya dan penyusun seperti ini:

   from msal.authority import (
       AuthorityBuilder,
       AZURE_US_GOVERNMENT, AZURE_CHINA, AZURE_PUBLIC)
   my_authority = AuthorityBuilder(AZURE_PUBLIC, "contoso.onmicrosoft.com")
   # Now you get an equivalent of
   # "https://login.microsoftonline.com/contoso.onmicrosoft.com"

   # You can feed such an authority to msal's ClientApplication
   from msal import PublicClientApplication
   app = PublicClientApplication("my_client_id", authority=my_authority, ...)

(opsional) Mengaktifkan atau menonaktifkan validasi otoritas. Parameter ini default ke true.

Mengatur cache token yang digunakan oleh instans ClientApplication ini. Secara default, cache dalam memori akan dibuat dan digunakan.

(opsional) Implementasi kelas abstrak HttpClient <msal.oauth2cli.http.http_client> Default ke instans sesi permintaan. Karena MSAL 1.11.0, sesi default akan dikonfigurasi untuk mencoba kembali satu kesalahan koneksi. Jika Anda menyediakan http_client Anda sendiri, itu akan menjadi tugas http_client Anda untuk memutuskan apakah akan melakukan coba lagi.

(opsional) Ini akan diteruskan ke parameter verifikasi di pustaka permintaan yang mendasar Ini tidak berlaku jika Anda telah memilih untuk meneruskan klien Http Anda sendiri

(opsional) Ini akan diteruskan ke parameter proksi di pustaka permintaan yang mendasar Ini tidak berlaku jika Anda telah memilih untuk meneruskan klien Http Anda sendiri

(opsional) Ini akan diteruskan ke parameter batas waktu di pustaka permintaan yang mendasar Ini tidak berlaku jika Anda telah memilih untuk meneruskan klien Http Anda sendiri

(opsional) Anda dapat memberikan nama aplikasi Anda untuk tujuan telemetri Microsoft. Nilai default adalah Tidak Ada, berarti tidak akan diteruskan ke Microsoft.

(opsional) Anda dapat menyediakan versi aplikasi Anda untuk tujuan telemetri Microsoft. Nilai default adalah Tidak Ada, berarti tidak akan diteruskan ke Microsoft.

(opsional) Memungkinkan konfigurasi satu atau beberapa kemampuan klien, misalnya ["CP1"].

Kemampuan klien dimaksudkan untuk menginformasikan platform identitas Microsoft (STS) kemampuan klien ini, sehingga STS dapat memutuskan untuk mengaktifkan fitur tertentu. Misalnya, jika klien mampu menangani tantangan klaim, STS dapat mengeluarkan token akses Evaluasi Akses Berkelanjutan (CAE) ke sumber daya, mengetahui bahwa ketika sumber daya memancarkan tantangan klaim , klien akan dapat menangani tantangan tersebut.

Detail implementasi: Kemampuan klien diimplementasikan menggunakan parameter "klaim" pada kawat, untuk saat ini. MSAL akan menggabungkannya ke dalam parameter klaim yang nantinya akan Anda berikan melalui salah satu permintaan acquire-token.

(opsional) Menginstruksikan MSAL untuk menggunakan layanan token regional Entra. Fitur warisan ini hanya tersedia untuk aplikasi pihak pertama. Hanya acquire_token_for_client() yang didukung.

Mendukung 4 nilai:

1. azure_region=None - Nilai default ini berarti tidak ada wilayah yang dikonfigurasi. MSAL akan menggunakan wilayah yang ditentukan dalam env var MSAL_FORCE_REGION.

2. azure_region="some_region" - yang berarti wilayah yang ditentukan digunakan.

3. azure_region=True - yang berarti MSAL akan mencoba mendeteksi wilayah secara otomatis. Ini tidak disarankan.

4. azure_region=False - yang berarti MSAL tidak akan menggunakan wilayah.

Baru dalam versi 1.12.0.

(opsional) Secara historis hardcode MSAL offline_access cakupan, yang akan memungkinkan aplikasi Anda memiliki akses yang lama ke data pengguna. Jika itu tidak perlu atau tidak diinginkan untuk aplikasi Anda, sekarang Anda dapat menggunakan parameter ini untuk menyediakan daftar pengecualian cakupan, seperti exclude_scopes = ["offline_access"].

MSAL telah lama melakukan penembolokan token di token_cache. Baru-baru ini, MSAL juga memperkenalkan konsep http_cache, dengan secara otomatis menyimpan beberapa respons http non-token dalam jumlah terbatas, sehingga berumurPublicClientApplication panjang dan ConfidentialClientApplication akan lebih berkinerja dan responsif dalam beberapa situasi.

Parameter ini http_cache menerima objek seperti dict. Jika tidak disediakan, MSAL akan menggunakan dict dalam memori.

Jika aplikasi Anda adalah aplikasi baris perintah (CLI), Anda ingin mempertahankan http_cache di berbagai eksekusi CLI. Format file yang bertahan dapat berubah karena, tetapi tidak terbatas pada , protokol yang tidak stabil, sehingga implementasi Anda harus mentolerir kesalahan pemuatan yang tidak terduga. Resep berikut menunjukkan cara untuk melakukannya:

   # Just add the following lines at the beginning of your CLI script
   import sys, atexit, pickle, logging
   http_cache_filename = sys.argv[0] + ".http_cache"
   try:
       with open(http_cache_filename, "rb") as f:
           persisted_http_cache = pickle.load(f)  # Take a snapshot
   except (
           FileNotFoundError,  # Or IOError in Python 2
           pickle.UnpicklingError,  # A corrupted http cache file
           AttributeError,  # Cache created by a different version of MSAL
           ):
       persisted_http_cache = {}  # Recover by starting afresh
   except:  # Unexpected exceptions
       logging.exception("You may want to debug this")
       persisted_http_cache = {}  # Recover by starting afresh
   atexit.register(lambda: pickle.dump(
       # When exit, flush it back to the file.
       # It may occasionally overwrite another process's concurrent write,
       # but that is fine. Subsequent runs will reach eventual consistency.
       persisted_http_cache, open(http_cache_file, "wb")))

   # And then you can implement your app as you normally would
   app = msal.PublicClientApplication(
       "your_client_id",
       ...,
       http_cache=persisted_http_cache,  # Utilize persisted_http_cache
       ...,
       #token_cache=...,  # You may combine the old token_cache trick
           # Please refer to token_cache recipe at
           # https://msal-python.readthedocs.io/en/latest/#msal.SerializableTokenCache
       )
   app.acquire_token_interactive(["your", "scope"], ...)

Konten di dalamnya http_cache murah untuk diperoleh. Tidak perlu membagikannya di antara berbagai aplikasi.

Konten di dalamnya http_cache tidak akan berisi token atau Informasi Identitas Pribadi (PII). Enkripsi tidak perlu.

Baru dalam versi 1.16.0.

Secara historis, MSAL akan terhubung ke titik akhir pusat yang terletak di https://login.microsoftonline.com untuk memperoleh beberapa metadata, terutama ketika menggunakan otoritas yang tidak dikenal. Perilaku ini dikenal sebagai Penemuan Instans.

Parameter ini default ke Tidak Ada, yang memungkinkan Penemuan Instans.

Jika Anda mengetahui beberapa otoritas yang Anda izinkan MSAL untuk beroperasi dengan as-is, tanpa melibatkan Penemuan Instans apa pun, pola yang direkomendasikan adalah:

   known_authorities = frozenset([  # Treat your known authorities as const
       "https://contoso.com/adfs", "https://login.azs/foo"])
   ...
   authority = "https://contoso.com/adfs"  # Assuming your app will use this
   app1 = PublicClientApplication(
       "client_id",
       authority=authority,
       # Conditionally disable Instance Discovery for known authorities
       instance_discovery=authority not in known_authorities,
       )

Jika Anda tidak tahu beberapa otoritas sebelumnya, namun masih ingin MSAL menerima otoritas apa pun yang akan Anda berikan, Anda dapat menggunakan False untuk menonaktifkan Penemuan Instans tanpa syarat.

Baru dalam versi 1.19.0.

Deprecated. Silakan gunakan enable_broker_on_windows sebagai gantinya.

Saat diaktifkan, log dapat mencakup PII (Informasi Identitas Pribadi). Ini dapat berguna dalam memecahkan masalah perilaku broker. Perilaku defaultnya adalah False.

Baru dalam versi 1.24.0.

Ditambahkan dalam versi 1.28.0: Ini adalah URL yang mengidentifikasi otoritas OpenID Connect (OIDC) dari format https://contoso.com/tenant. MSAL akan menambahkan ".well-known/openid-configuration" ke otoritas dan mengambil metadata OIDC dari sana, untuk mencari tahu titik akhir.

Catatan: Broker TIDAK akan digunakan untuk otoritas OIDC.