Memperoleh token

Ada banyak cara untuk memperoleh token dengan Python MSAL. Beberapa memerlukan interaksi pengguna sementara yang lain tidak. Pendekatan yang digunakan untuk memperoleh token berbeda tergantung pada apakah pengembang membangun klien publik (desktop atau seluler) atau aplikasi klien rahasia (aplikasi web, API web, atau daemon seperti layanan Windows).

Prasyarat

Sebelum Anda memperoleh token dengan Python MSAL, pelajari tentang jenis aplikasi klien.

Mendapatkan akun pengguna

Aplikasi dapat memperoleh token sebagai dirinya sendiri atau atas nama pengguna. Untuk memperoleh token atas nama pengguna, aplikasi perlu mengetahui akun pengguna. Python MSAL menyediakan get_accounts metode untuk mendapatkan akun pengguna. Metode ini tersedia pada kedua PublicClientApplication kelas dan ConfidentialClientApplication . Metode ini mengembalikan daftar akun yang sebelumnya pernah digunakan pengguna untuk masuk, yaitu akun yang tersimpan dalam cache.

accounts = app.get_accounts(username=user.get("preferred_username"))

Akun yang dipilih oleh pengguna untuk masuk nantinya dapat digunakan acquire_token_silent() untuk menemukan tokennya.

Alur pemberian token

Ada beberapa alur autentikasi yang dapat digunakan untuk memperoleh token dengan Python MSAL. Anda dapat menemukan informasi selengkapnya tentang alur ini pada dokumentasi platform identitas Microsoft.

Warning

Selalu gunakan MSAL untuk mendapatkan token keamanan dan memanggil API web yang dilindungi di aplikasi Anda. Kami tidak menyarankan Anda menerapkan logika akuisisi token Anda sendiri. Alur ini untuk membantu Anda memiliki pemahaman yang lebih baik tentang cara kerja hal-hal. Jika Anda mengamankan aplikasi web, sebaiknya gunakan pustaka identitas . Pustaka ini tidak dikelola secara resmi oleh Microsoft tetapi mengimplementasikan sebagian besar logika yang Anda butuhkan untuk memperoleh token di aplikasi web.

Interaktif vs senyap

Python MSAL mendukung akuisisi token interaktif dan senyap. Akuisisi token interaktif memerlukan interaksi pengguna, sementara akuisisi token senyap tidak. Klien publik umumnya memerlukan interaksi pengguna sementara klien rahasia mengandalkan kredensial yang telah disediakan sebelumnya, seperti sertifikat dan rahasia.

acquire_token_silent_with_error Gunakan metode untuk memperoleh token secara diam-diam. Metode ini menemukan token akses yang valid dari cache, atau token refresh yang valid dari cache lalu secara otomatis menggunakannya untuk menukarkan token akses baru. Jika tidak benar, Anda perlu menggunakan metode interaktif untuk memperoleh token.

Jika aplikasi Anda tidak memerlukan detail kesalahan spesifik saat penyegaran token selama pencarian cache token, metode acquire_token_silent direkomendasikan.

Contoh penggunaan metode ini seperti yang ditunjukkan dalam cuplikan kode berikut.

if accounts:
    # If so, you could then somehow display these accounts and let end user choose
    chosen = accounts[0]
    result = app.acquire_token_silent(scopes=["your_scope"], account=chosen)
    
    # At this point, you can save you can update your cache if you are using token caching
    # check result variable, if its None then you should interactively acquire a token
    if not result:
        # So no suitable token exists in cache. Let's get a new one from Microsoft Entra.
        result = app.acquire_token_by_one_of_the_actual_method(..., scopes=["User.Read"])
    
    if "access_token" in result:
        access_token = result["access_token"]
    else:
        print(result.get("error"))  
        print(result.get("error_description"))
        print(result.get("correlation_id"))  # You may need this when reporting a bug

Beberapa metode tersedia untuk akuisisi token interaktif. Metode yang digunakan tergantung pada jenis aplikasi yang Anda bangun dan alur pemberian token yang berlaku untuk skenario Anda.

Perolehan token interaktif untuk klien publik

Aplikasi klien publik tidak dapat menyimpan rahasia dengan aman dan hanya dapat mengautentikasi pengguna yang berinteraksi dengan produk. Python MSAL mengekspos logika akuisisi token untuk aplikasi publik melalui PublicClientApplication. Berikut ini adalah berbagai metode yang tersedia untuk aplikasi klien publik untuk memperoleh token.

Alur kode perangkat

Alur kode perangkat digunakan untuk memperoleh token dalam aplikasi yang berjalan pada perangkat yang tidak memiliki akses ke browser web. Ini adalah aplikasi yang dikenal sebagai aplikasi tanpa kepala. Alur ini memberi pengguna URL dan kode. Pengguna masuk ke browser web di perangkat lain, memasukkan kode dan masuk. Pada autentikasi yang berhasil, Microsoft Entra mengembalikan token ke perangkat tanpa browser.

Pertama, Anda memanggil metode .initiate_device_flow

flow = app.initiate_device_flow(scopes=config["scope"])
if "user_code" not in flow:
    raise ValueError(
        "Fail to create device flow. Err: %s" % json.dumps(flow, indent=4))

print(flow["message"])
sys.stdout.flush()  # Some terminal needs this to ensure the message is shown

# Ideally you should wait here, in order to save some unnecessary polling
# input("Press Enter after signing in from another device to proceed, CTRL+C to abort.")

Anda kemudian meneruskan objek kamus flow ke metode acquire_token_by_device_flow untuk mendapatkan token. Secara bawaan, metode ini memblokir utas saat ini. Anda dapat mengikuti instruksi ini untuk mempersingkat waktu pemblokiran, atau Anda bahkan dapat menonaktifkan perilaku pemblokiran lalu terus memanggil acquire_token_by_device_flow dalam loop kustom Anda sendiri.

result = app.acquire_token_by_device_flow(flow)

if "access_token" in result:
    access_token = result["access_token"]
else:
    print(result.get("error"))  

Respons yang berhasil adalah kamus dengan kunci access_token.

Memperoleh token interaktif

MSAL Python juga menawarkan kemampuan untuk aplikasi klien publik (Desktop dan Seluler) untuk memperoleh token sebagai pengguna. Pengguna masuk melalui URL permintaan otorisasi melalui browser web. Atur URI pengalihan aplikasi Anda ke http://localhost di pusat admin Microsoft Entra untuk pendaftaran aplikasi Anda. Jika Anda memilih untuk menggunakan broker selama pembuatan PublicClientApplication, aplikasi Anda juga perlu mendaftarkan ms-appx-web://Microsoft.AAD.BrokerPlugin/YOUR_CLIENT_ID sebagai URI pengalihan.

result = app.acquire_token_interactive(  # It automatically provides PKCE protection
    scopes=config["scope"])

if "access_token" in result:
    access_token = result["access_token"]
else:
    print(result.get("error"))  

Nama pengguna dan kata sandi

Warning

Api ini tidak digunakan lagi untuk alur klien publik karena risiko keamanan, gunakan alur yang lebih aman. Ikuti panduan ini untuk panduan migrasi.

Kami tidak menyarankan untuk menggunakan pendekatan ini. Dimungkinkan juga untuk mendapatkan token dengan nama pengguna dan kata sandi. Python MSAL menyediakan acquire_token_by_username_password metode untuk kasus penggunaan ini. Ini tidak disarankan karena aplikasi akan meminta kata sandi pengguna secara langsung, yang merupakan pola yang tidak aman.

Ada alur yang lebih aman yang dapat Anda gunakan. Pelajari selengkapnya di panduan alur autentikasi nama pengguna dan kata sandi .

result = app.acquire_token_by_username_password(
    username=config["username"], password=config["password"], scopes=config["scope"])

if "access_token" in result:
    access_token = result["access_token"]
else:
    print(result.get("error"))  

Akuisisi token interaktif untuk klien konfidensial

Aplikasi klien rahasia dapat menyimpan rahasia dengan aman dan dapat mengautentikasi baik atas nama aplikasi maupun atas nama pengguna tertentu. Python MSAL memberi pengembang berbagai metode untuk memperoleh token saat mengembangkan ConfidentialClientApplication.

Memperoleh token untuk klien

Dapatkan token atas nama aplikasi itu sendiri menggunakan kredensial klien, bukan atas nama pengguna. Misalnya, ini dapat digunakan dalam aplikasi yang memproses pengguna dalam batch dan bukan satu pengguna tertentu, seperti alat sinkronisasi. Python MSAL menyediakan acquire_token_for_client metode untuk melakukan ini. Karena MSAL Python 1.23, metode ini secara otomatis mencari token dari cache, dan hanya mengirim permintaan ke penyedia identitas ketika cache meleset.

result = app.acquire_token_for_client(scopes=config["scope"])

if "access_token" in result:
    access_token = result["access_token"]
else:
    print(result.get("error"))    

Dapatkan token atas nama

Dalam kasus aplikasi web atau API web yang memanggil API web downstream lain atas nama pengguna, gunakan On Behalf Of flow untuk mendapatkan token berdasarkan assertion pengguna. Misalnya, SAML dan JWT. Aplikasi saat ini adalah layanan tingkat menengah yang dipanggil dengan token yang mewakili pengguna akhir. Aplikasi saat ini dapat menggunakan token tersebut, juga dikenal sebagai pernyataan pengguna, untuk meminta token lain untuk mengakses API web hilir atas nama pengguna tersebut. Aplikasi tingkat menengah tidak memiliki interaksi pengguna untuk mendapatkan persetujuan. Untuk informasi tentang mendapatkan persetujuan di muka untuk aplikasi tingkat menengah Anda, lihat dokumentasi.

Berikut adalah contoh kode yang memperoleh token akses menggunakan metode .acquire_token_on_behalf_of

def get(self, request): # a web service endpoint receiving a request
    
    scopes = ["your-scopes"]
    downstream_api = "https://your-downstreamapi.com/resource" #your downstream API resource endpoint
    current_access_token = request.headers.get("Authorization", None)
    
    # initialize the app
    app = msal.ConfidentialClientApplication(...) # refer to initialization of the app documentation

    #acquire token on behalf of the user that called this API
    downstream_api_access_token = app.acquire_token_on_behalf_of(
        user_assertion=current_app_access_token.split(' ')[1],
        scopes=_scopes
    )

    if "access_token" in result:
        access_token = result["access_token"]
        # use access_token to call dowstream API e.g
        requests.get(downstream_api, headers={'Authorization': f'Bearer {downstream_api_access_token}'})
    else:
        print(result.get("error")) 

Memperoleh token menurut alur kode otorisasi

Untuk aplikasi web yang mengautentikasi atas nama pengguna, dapatkan token melalui kode otorisasi setelah mengizinkan pengguna masuk melalui URL permintaan otorisasi. Ini biasanya mekanisme yang digunakan oleh aplikasi yang memungkinkan pengguna masuk dan mengakses API web untuk pengguna khusus ini.

Pertama-tama Anda harus memulai alur kode autentikasi menggunakan initiate_auth_code_flow. Metode ini mengambil di antara parameter lain URI pengalihan dan string status. Nilai parameter status juga disertakan dalam respons token. Jika nilai ini tidak ada, Python MSAL akan secara otomatis menghasilkan satu secara internal. URI pengalihan yang disediakan harus sesuai dengan URI pengalihan yang terdaftar di pusat admin Microsoft Entra. Metode ini mengembalikan alur kode autentikasi yang merupakan kamus yang berisi auth_uri dan state. auth_uri adalah URL yang perlu dikunjungi pengguna untuk masuk.

flow = app.initiate_auth_code_flow(
    scopes=config["scope"], redirect_uri=config["redirect_uri"], state="your-state-value")

if "error" in flow:
    print(flow.get("error"))

# Save the response somewhere e.g in session
session["auth_flow"] = flow

# At this point, the app should guide the user to visit the auth ur (session["auth_flow"]["auth_uri"])

Respons yang diperoleh dari mengakses endpoint URI autentikasi digunakan dalam metode acquire_token_by_auth_code_flow. Status adalah pengidentifikasi unik yang dapat Anda gunakan untuk memverifikasi respons dari server otorisasi. Pengguna harus menyetujui cakupan izin saat login.

# The uth_response value from visiting the auth_uri endpoint is passed as a query string
# You can change this by passing a value to the response_mode in the initiate_auth_code_flow method
try:
    result = app.acquire_token_by_auth_code_flow(session.get("flow", {}), auth_response)
    
    if "access_token" in result:
        access_token = result["access_token"]
    else:
        print(result.get("error"))
except ValueError:  # Usually caused by CSRF
    pass  # Simply ignore them

Penembolokan token Python MSAL

Aplikasi klien publik dan konfidensial mendukung penyimpanan token dalam cache, yang ditangani langsung oleh MSAL Python. Aplikasi harus mencoba mendapatkan token dari cache terlebih dahulu sebelum mengandalkan cara lain. Untuk informasi selengkapnya, lihat pola akuisisi token yang direkomendasikan.

Agar dapat mempertahankan cache, pengembang perlu mengonfigurasi logika serialisasi cache token .