Tokens verkrijgen

Er zijn veel manieren om een token te verkrijgen met MSAL Python. Sommige vereisen gebruikersinteractie, terwijl anderen dat niet doen. De methode voor het verkrijgen van een token verschilt, afhankelijk van of de ontwikkelaar een openbare client (desktop of mobiel) of een vertrouwelijke clienttoepassing (web-app, web-API of daemon zoals een Windows-service) bouwt).

Prerequisites

Voordat u tokens verkrijgt met MSAL Python, leert u meer over typen clienttoepassingen.

Gebruikersaccount ophalen

Een app kan een token als zichzelf of namens een gebruiker verkrijgen. Als u een token wilt verkrijgen namens een gebruiker, moet de app het account van de gebruiker kennen. MSAL Python biedt de get_accounts methode om het account van de gebruiker op te halen. Deze methode is beschikbaar voor beide PublicClientApplication en ConfidentialClientApplication klassen. De methode retourneert een lijst met accounts waarmee de gebruiker zich eerder heeft aangemeld, dat wil gezegd, bestaat in de cache.

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

De account die door de gebruiker is geselecteerd om aan te melden, kan later in acquire_token_silent() worden gebruikt om de bijbehorende tokens te vinden.

Token-verleningsstromen

Er zijn verschillende verificatiestromen die kunnen worden gebruikt voor het verkrijgen van tokens met MSAL-Python. Meer informatie over deze stromen vindt u in de Microsoft identity platform documentatie.

Warning

Gebruik ALTIJD MSAL om beveiligingstokens op te halen en beveiligde web-API's aan te roepen in uw apps. We raden u niet aan uw eigen logica voor het verkrijgen van tokens te implementeren. Deze stromen zijn om u te helpen een beter inzicht te krijgen in de werking van dingen. Als u een webtoepassing beveiligt, raden we u aan de identiteitsbibliotheek te gebruiken. Deze bibliotheek wordt niet officieel onderhouden door Microsoft, maar implementeert de meeste logica die u nodig hebt om tokens in web-apps te verkrijgen.

Interactief versus stil

MSAL Python ondersteunt zowel interactieve als stille tokenverzameling. Interactieve tokenverwerving vereist gebruikersinteractie, terwijl het verkrijgen van tokens op de achtergrond niet gebeurt. Voor openbare clients is doorgaans gebruikersinteractie vereist, terwijl vertrouwelijke clients afhankelijk zijn van vooraf ingerichte referenties, zoals certificaten en geheimen.

Gebruik de acquire_token_silent_with_error methode om in stilte een token te verkrijgen. Met deze methode wordt een geldig toegangstoken uit de cache gevonden of een geldig vernieuwingstoken uit de cache en wordt het vervolgens automatisch gebruikt om een nieuw toegangstoken in te wisselen. Als geen van beide waar is, moet u een interactieve methode gebruiken om het token te verkrijgen.

Als het uw app niet uitmaakt wat de exacte fout is bij het vernieuwen van het token tijdens het opzoeken in de tokencache, dan wordt de methode acquire_token_silent aanbevolen.

Een voorbeeld van het gebruik van deze methode is zoals weergegeven in het volgende codefragment.

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

Er zijn verschillende methoden beschikbaar voor het verkrijgen van interactieve tokens. De te gebruiken methode is afhankelijk van het type app dat u bouwt en de stroom voor tokentoekentoekenning die van toepassing is op uw scenario.

Interactieve tokenverwerving voor openbare clients

Openbare clienttoepassingen kunnen een geheim niet veilig opslaan en kunnen alleen de gebruiker verifiëren die met het product communiceert. MSAL Python stelt de logica voor het verkrijgen van tokens voor openbare toepassingen beschikbaar via PublicClientApplication. Hier volgen de verschillende methoden die beschikbaar zijn voor openbare clienttoepassingen om tokens te verkrijgen.

Apparaatcodestroomproces

Apparaatcodestroom wordt gebruikt om tokens te verkrijgen in toepassingen die worden uitgevoerd op apparaten die geen toegang hebben tot een webbrowser. Deze toepassingen staan bekend als headless-toepassingen. Deze stroom biedt de gebruiker een URL en een code. De gebruiker gaat naar een webbrowser op een ander apparaat, voert de code in en meldt zich aan. Bij geslaagde verificatie retourneert Microsoft Entra een token naar het apparaat zonder browser.

Eerst roept u de initiate_device_flow methode aan.

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

Vervolgens geeft u het stroomwoordenlijstobject door aan de acquire_token_by_device_flow methode om het token op te halen. Deze methode blokkeert standaard de huidige thread. U kunt deze instructies volgen om de bloktijd te verkorten of u kunt zelfs het blokkeringsgedrag uitschakelen en vervolgens blijven bellen acquire_token_by_device_flow in uw eigen aangepaste lus.

result = app.acquire_token_by_device_flow(flow)

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

Een geslaagd antwoord met een woordenlijst met een access_token sleutel.

Interactief token verkrijgen

MSAL Python biedt ook de mogelijkheid voor openbare client-apps (desktops en mobiel) om tokens als gebruiker te verkrijgen. De gebruiker meldt zich aan via de autorisatieaanvraag-URL via een webbrowser. Stel de omleidings-URI van uw app in op http://localhost in het Microsoft Entra-beheercentrum voor uw app-registratie. Als u tijdens het maken van PublicClientApplication kiest voor het gebruik van de broker, moet uw app ook ms-appx-web://Microsoft.AAD.BrokerPlugin/YOUR_CLIENT_ID registreren als omleidings-URI.

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

Gebruikersnaam en wachtwoord

Warning

Deze API is afgeschaft voor openbare clientstromen vanwege beveiligingsrisico's en gebruik een veiligere stroom. Volg deze handleiding voor migratierichtlijnen.

We raden u niet aan deze methode te gebruiken. Het is ook mogelijk om een token met een gebruikersnaam en wachtwoord op te halen. MSAL Python biedt de acquire_token_by_username_password methode voor deze use case. Het wordt niet aanbevolen omdat de toepassing een gebruiker rechtstreeks om zijn wachtwoord vraagt. Dit is een onveilig patroon.

Er zijn veiligere stromen die u kunt gebruiken. Meer informatie vindt u in de richtlijnen voor de stroom voor gebruikersnaam en wachtwoordverificatie .

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

Interactieve tokenverwerving van vertrouwelijke clients

Vertrouwelijke clienttoepassingen kunnen veilig een geheim opslaan en kunnen zowel namens een toepassing als namens een bepaalde gebruiker worden geverifieerd. MSAL Python biedt ontwikkelaars verschillende methoden om tokens te verkrijgen bij het ontwikkelenConfidentialClientApplication.

Token verkrijgen voor client

Verkrijg een token als de toepassing zelf met clientreferenties, en niet voor een gebruiker. Dit kan bijvoorbeeld worden gebruikt in toepassingen die gebruikers verwerken in batches en niet één bepaalde gebruiker, zoals het synchroniseren van hulpprogramma's. MSAL Python biedt de acquire_token_for_client methode om dit te doen. Sinds MSAL Python 1.23 zoekt deze methode automatisch naar een token in de cache en stuurt deze alleen een aanvraag naar de identiteitsprovider wanneer er niets in de cache wordt gevonden.

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

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

Token verkrijgen namens

In het geval van web-apps of web-API's die namens de gebruiker een andere downstream-web-API aanroepen, gebruiken ze de On Behalf Of-flow om een token te verkrijgen op basis van een gebruikersassertie. Bijvoorbeeld SAML en JWT. De huidige app is een service in de middelste laag die is aangeroepen met een token dat een eindgebruiker vertegenwoordigt. De huidige app kan een dergelijk token, ook wel een gebruikersverklaring genoemd, gebruiken om een ander token aan te vragen om namens die gebruiker toegang te krijgen tot downstream-web-API. De app in de middelste laag heeft geen gebruikersinteractie om toestemming te krijgen. Raadpleeg de documentatie voor informatie over het vooraf verkrijgen van toestemming voor uw app in de middelste laag.

Hier volgt een voorbeeld van code waarmee een toegangstoken wordt verkregen met behulp van de acquire_token_on_behalf_of methode.

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

Token verkrijgen door autorisatiecodestroom

Voor web-apps die worden geverifieerd in de naam van een gebruiker, verkrijgt u tokens via autorisatiecode nadat de gebruiker zich heeft aangemeld via de AUTORISATIEaanvraag-URL. Dit is doorgaans het mechanisme dat wordt gebruikt door een toepassing waarmee de gebruiker zich kan aanmelden en toegang heeft tot web-API's voor deze specifieke gebruiker.

U moet eerst de verificatiecodestroom initiëren met behulp van de initiate_auth_code_flow. Deze methode neemt onder andere parameters een omleidings-URI en statustekenreeks in beslag. De waarde van de statusparameter wordt ook opgenomen in het tokenantwoord. Als deze waarde afwezig is, genereert MSAL-Python automatisch één intern. De opgegeven omleidings-URI moet overeenkomen met de omleidings-URI die is geregistreerd in de Microsoft Entra-beheercentrum. Deze methode retourneert de verificatiecodestroom die een woordenlijst bevat auth_uri en state. Dit auth_uri is de URL die de gebruiker moet bezoeken om zich aan te melden.

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

Het antwoord van het bezoeken van de verificatie-URI-eindpunten wordt gebruikt in de acquire_token_by_auth_code_flow methode. De status is een unieke id die u kunt gebruiken om het antwoord van de autorisatieserver te controleren. De gebruiker moet toestemming geven voor machtigingen bij het aanmelden.

# 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

MSAL Python-tokenopslag

Zowel openbare als vertrouwelijke clienttoepassingen ondersteunen tokencaching, direct afgehandeld door MSAL Python. Toepassingen moeten eerst proberen een token op te halen uit de cache voordat ze op een andere manier vertrouwen. Zie het aanbevolen patroon voor het verkrijgen van tokens voor meer informatie.

Om de cache te kunnen behouden, moeten de ontwikkelaars de serialisatielogica van de tokencache configureren.