Získání tokenů

Existuje mnoho způsobů, jak získat token pomocí msAL Python. Některé vyžadují interakci uživatele, zatímco jiné ne. Přístup použitý k získání tokenu se liší v závislosti na tom, jestli vývojář vytváří veřejného klienta (desktopovou nebo mobilní) nebo důvěrnou klientskou aplikaci (webovou aplikaci, webové rozhraní API nebo démona, jako je služba Windows).

Předpoklady

Než s msAL Python získáte tokeny, přečtěte si o typech klientských aplikací.

Získání uživatelského účtu

Aplikace může získat token jako samotný nebo jménem uživatele. Aby aplikace získala token jménem uživatele, musí znát účet uživatele. MSAL Python poskytuje metodu get_accounts pro získání účtu uživatele. Tato metoda je k dispozici v obou PublicClientApplicationConfidentialClientApplication třídách. Tato metoda vrátí seznam účtů, ke kterým se uživatel dříve přihlásil, tj. existuje v mezipaměti.

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

Účet vybraný uživatelem pro přihlášení lze později použít acquire_token_silent() k vyhledání jeho tokenů.

Procesy udělení tokenů

Existuje několik toků ověřování, které lze použít k získání tokenů pomocí msAL Python. Další informace o těchto tocích najdete v dokumentaci k Microsoft identity platform.

Warning

K získání tokenů zabezpečení a volání chráněných webových rozhraní API ve vašich aplikacích vždy používejte MSAL. Nedoporučujeme implementovat vlastní logiku získání tokenu. Tyto toky vám pomůžou lépe pochopit, jak věci fungují. Pokud zabezpečujete webovou aplikaci, doporučujeme použít knihovnu identit . Tato knihovna není oficiálně udržována Microsoft, ale implementuje většinu logiky, kterou potřebujete získat tokeny ve webových aplikacích.

Interaktivní vs. tiché

PYTHON MSAL podporuje interaktivní i bezobslužné získávání tokenů. Interaktivní získávání tokenů vyžaduje interakci uživatele, zatímco bezobslužné získávání tokenů ne. Veřejné klienty obecně vyžadují interakci uživatelů, zatímco důvěrné klienty spoléhají na předem zřízené přihlašovací údaje, jako jsou certifikáty a tajné kódy.

acquire_token_silent_with_error Pomocí metody můžete bezobslužně získat token. Tato metoda najde platný přístupový token z mezipaměti nebo platný obnovovací token z mezipaměti a pak ho automaticky použije k uplatnění nového přístupového tokenu. Pokud ani jedno není pravdivé, musíte k získání tokenu použít interaktivní metodu.

Pokud vaší aplikaci nezáleží na přesné chybě při obnovení tokenu během vyhledávání v mezipaměti tokenů, doporučuje se metoda acquire_token_silent.

Příklad použití této metody je znázorněný v následujícím fragmentu kódu.

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

Pro získání interaktivního tokenu je k dispozici několik metod. Způsob použití závisí na typu aplikace, kterou vytváříte, a toku udělení tokenu použitelného pro váš scénář.

Interaktivní získávání tokenů pro veřejné klienty

Veřejné klientské aplikace nemůžou bezpečně ukládat tajný kód a můžou ověřovat pouze uživatele, který s produktem komunikuje. MSAL Python zveřejňuje logiku získávání tokenů pro veřejné aplikace prostřednictvím PublicClientApplication. Níže jsou uvedené různé metody, které jsou k dispozici pro veřejné klientské aplikace pro získání tokenů.

Tok kódu zařízení

Tok kódu zařízení slouží k získání tokenů v aplikacích, které běží na zařízeních, která nemají přístup k webovému prohlížeči. Jedná se o aplikace, které se označují jako bezobsadové aplikace. Tento tok poskytuje uživateli adresu URL a kód. Uživatel přejde do webového prohlížeče na jiném zařízení, zadá kód a přihlásí se. Po úspěšném ověření Microsoft Entra vrátí token do zařízení bez prohlížeče.

Nejprve zavoláte metodu 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.")

Poté předáte objekt slovníku toku metodě acquire_token_by_device_flow, abyste získali token. Ve výchozím nastavení tato metoda blokuje aktuální vlákno. Podle těchto pokynů můžete zkrátit dobu blokování nebo dokonce vypnout chování blokování a pak pokračovat v volání acquire_token_by_device_flow ve vlastní přizpůsobené smyčce.

result = app.acquire_token_by_device_flow(flow)

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

Úspěšná odpověď je slovník s klíčem access_token.

Interaktivní získání tokenu

MSAL Python také umožňuje veřejným klientským aplikacím (počítače a mobilní zařízení) získávat tokeny jménem uživatele. Uživatel se přihlásí prostřednictvím adresy URL žádosti o autorizaci přes webový prohlížeč. Nastavte identifikátor URI přesměrování vaší aplikace na http://localhost v centru pro správu Microsoft Entra v registraci vaší aplikace. Pokud se během vytváření PublicClientApplication rozhodnete používat zprostředkovatele, musí vaše aplikace také zaregistrovat ms-appx-web://Microsoft.AAD.BrokerPlugin/YOUR_CLIENT_ID jako identifikátor URI pro přesměrování.

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

Uživatelské jméno a heslo

Warning

Toto rozhraní API bylo pro toky veřejných klientů označeno jako zastaralé kvůli bezpečnostním rizikům; použijte bezpečnější tok. Pokyny k migraci najdete v tomto průvodci .

Tento přístup nedoporučujeme používat. Token je také možné získat pomocí uživatelského jména a hesla. MSAL Python poskytuje metodu acquire_token_by_username_password pro tento případ použití. Nedoporučuje se, protože aplikace požádá uživatele o heslo přímo, což je nezabezpečený vzor.

Existují bezpečnější toky, které můžete použít. Další informace najdete v pokynech k toku ověřování uživatelským jménem a heslem .

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

Interaktivní získání tokenu pro důvěrné klienty

Důvěrné klientské aplikace můžou bezpečně ukládat tajný kód a můžou ověřovat jménem aplikace i jménem daného uživatele. MSAL Python poskytuje vývojářům různé metody získávání tokenů při vývoji ConfidentialClientApplication.

Získání tokenu pro klienta

Získejte token jménem samotné aplikace pomocí přihlašovacích údajů klienta, nikoli pro uživatele. Můžete ho například použít v aplikacích, které zpracovávají uživatele v dávkách, a ne v jednom konkrétním uživateli, například v nástrojích pro synchronizaci. MSAL Python poskytuje metoduacquire_token_for_client, jak to provést. Od verze MSAL Python 1.23 tato metoda automaticky vyhledá token v mezipaměti a požadavek zprostředkovateli identity odešle pouze tehdy, pokud token není v mezipaměti nalezen.

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

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

Získání tokenu jménem uživatele

V případě webových aplikací nebo webových rozhraní API, která jménem uživatele volají jiné navazující webové rozhraní API, použijte tok On-Behalf-Of k získání tokenu na základě uživatelského potvrzení. Například SAML a JWT. Současná aplikace je služba střední úrovně, která byla vyvolána tokenem představujícím koncového uživatele. Aktuální aplikace může použít tento token, označovaný také jako kontrolní výraz uživatele, k vyžádání dalšího tokenu pro přístup k podřízeným webovým rozhraní API jménem tohoto uživatele. Aplikace střední vrstvy nemá žádnou interakci uživatele k získání souhlasu. Informace o získání souhlasu pro aplikaci střední vrstvy najdete v dokumentaci.

Tady je příklad kódu, který pomocí metody získá přístupový token 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")) 

Získání tokenu podle toku autorizačního kódu

U webových aplikací, které se ověřují jménem uživatele, získejte tokeny prostřednictvím autorizačního kódu po povolení přihlášení uživatele prostřednictvím adresy URL žádosti o autorizaci. Obvykle se jedná o mechanismus používaný aplikací, který umožňuje přihlášení uživatele a přístup k webovým rozhraním API pro tohoto konkrétního uživatele.

Nejprve budete muset iniciovat tok ověřovacího kódu pomocí metody initiate_auth_code_flow. Tato metoda mimo jiné přijímá parametry URI pro přesměrování a řetězec state. Hodnota parametru stavu je také zahrnuta v odpovědi tokenu. Pokud tato hodnota chybí, msAL Python automaticky vygeneruje jednu interně. Zadaný identifikátor URI přesměrování se musí shodovat s identifikátorem URI přesměrování zaregistrovaným v Centrum pro správu Microsoft Entra. Tato metoda vrátí tok ověřovacího kódu, který je slovník obsahující auth_uri a state. Jedná se auth_uri o adresu URL, kterou musí uživatel navštívit, aby se přihlásil.

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

Odpověď z volání koncových bodů URI pro ověřování se používá v metodě acquire_token_by_auth_code_flow. Stav je jedinečný identifikátor, který můžete použít k ověření odpovědi z autorizačního serveru. Uživatel by měl během přihlašování udělit souhlas s oprávněními.

# 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

Ukládání tokenů msAL do mezipaměti Python

Veřejné i důvěrné klientské aplikace podporují ukládání tokenů do mezipaměti, které zpracovává Python MSAL. Aplikace by se měly nejprve pokusit získat token z mezipaměti, než se budou spoléhat na jakékoli jiné prostředky. Další informace najdete v doporučeném modelu získávání tokenů.

Aby bylo možné zachovat mezipaměť, musí vývojáři nakonfigurovat logiku serializace mezipaměti tokenů .