PublicClientApplication Klasse

Identisch mit der Ausnahme <xref:ClientApplication.__init__>, dass dieser client_credential Parameter beibehalten Nonewird.

Note

Was ist ein Broker, und warum verwenden Sie ihn?

Ein Broker ist eine Komponente, die auf Ihrem Gerät installiert ist.

Der Broker gibt Ihrem Gerät implizit eine Identität. Mithilfe eines Brokers

Ihr Gerät wird zu einem Faktor, der MFA (mehrstufige Authentifizierung) erfüllen kann.

Dieser Faktor würde obligatorisch werden

wenn der Administrator eines Mandanten eine entsprechende Richtlinie für bedingten Zugriff (Conditional Access, CA) aktiviert.

Die Anwesenheit des Brokers ermöglicht Microsoft Identity Platform

um ein höheres Vertrauen zu haben, dass die Token auf Ihrem Gerät ausgestellt werden,

und das ist sicherer.

Ein zusätzlicher Vorteil des Brokers ist,

es wird als langlebiger Prozess mit dem Betriebssystem Ihres Geräts ausgeführt,

und verwaltet ihren eigenen Cache,

so dass Ihre brokerfähigen Apps (sogar eine CLI)

kann automatisch SSO aus einer zuvor eingerichteten angemeldeten Sitzung verwenden.

Wie kann ich mich für die Verwendung des Brokers anmelden?

Sie können eine beliebige Kombination der folgenden Opt-In-Parameter auf "true" festlegen:

Opt-In-Kennzeichnung

Wenn die App ausgeführt wird

Die App hat dies als Umleitungs-URI der Desktopplattform in Azure-Portal

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 mit installierter Unternehmensportal

msauth.com.msauth.unsignedapp://auth

enable_broker_on_linux

Linux mit Installierter Intune

https://login.microsoftonline.com/common/oauth2/nativeclient (MUSS aktiviert sein)

Installieren der Brokerabhängigkeit,

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

Testen sie mit acquire_token_interactive() und acquire_token_silent().

Das Fallbackverhalten der MSAL-Brokerunterstützung von MSAL Python

MSAL führt entweder einen Fehler aus oder führt im Hintergrund zu Nichtbrokerflüssen aus.

MSAL ignoriert die enable_broker_... und Umgehungsbroker

auf diesen Authentifizierungsflüssen, die bekanntermaßen nicht vom Broker unterstützt werden.

Dazu gehören ADFS, B2C usw.

Weitere Szenarien für "could-use-broker" finden Sie unten.

MSAL-Fehler beim Anmelden des App-Entwicklers für die Verwendung des Brokers

aber ein direktes Abhängigkeitspaket "mid-tier" ist nicht installiert.

Fehlermeldung führt app-Entwickler zum Deklarieren der richtigen Abhängigkeit

msal[broker].

Hier ist ein Fehler aufgetreten, da der Fehler für App-Entwickler umsetzbar ist.

MSAL deaktiviert im Hintergrund den Broker und Fallback auf Nichtbroker,

Bei der Auswahl konnte die Abhängigkeit noch nicht initialisiert werden.

Wir gehen davon aus, dass dies auf einem Gerät geschieht, dessen Betriebssystem zu alt ist

oder die zugrunde liegende Brokerkomponente ist irgendwie nicht verfügbar.

Hier gibt es keinen App-Entwickler, oder der Endbenutzer kann dies tun.

Schließlich muss die Richtlinie für bedingten Zugriff

erzwingen, dass der Benutzer zu einem anderen Gerät wechselt.

MSAL-Fehler beim Anmelden des Brokers, installiert, initialisiert,

aber nachfolgende Tokenanforderungen sind fehlgeschlagen.

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

Name Beschreibung
enable_broker_on_windows
Erforderlich
<xref:boolean>

Diese Einstellung ist nur wirksam, wenn Ihre App auf Windows 10+ ausgeführt wird. Dieser Parameter ist standardmäßig "None" festgelegt, was bedeutet, dass MSAL keinen Broker verwendet.

Neu in MSAL Python 1.25.0.
enable_broker_on_mac
Erforderlich
<xref:boolean>

Diese Einstellung ist nur wirksam, wenn Ihre App auf dem Mac ausgeführt wird. Dieser Parameter ist standardmäßig "None" festgelegt, was bedeutet, dass MSAL keinen Broker verwendet.

Neu in MSAL Python 1.31.0.
enable_broker_on_linux
Erforderlich
<xref:boolean>

Diese Einstellung ist nur wirksam, wenn Ihre App unter Linux ausgeführt wird, einschließlich WSL. Dieser Parameter ist standardmäßig "None" festgelegt, was bedeutet, dass MSAL keinen Broker verwendet.

Neu in MSAL Python 1.33.0.
enable_broker_on_wsl
Erforderlich
<xref:boolean>

Diese Einstellung ist nur wirksam, wenn Ihre App auf WSL ausgeführt wird. Dieser Parameter ist standardmäßig "None" festgelegt, was bedeutet, dass MSAL keinen Broker verwendet.

Neu in MSAL Python 1.33.0.
client_id
Erforderlich
client_credential
Standardwert: None

Nur Schlüsselwortparameter

Name Beschreibung
enable_broker_on_windows
Standardwert: None
enable_broker_on_mac
Standardwert: None
enable_broker_on_linux
Standardwert: None
enable_broker_on_wsl
Standardwert: None

Methoden

acquire_token_by_device_flow

Abrufen eines Tokens durch ein Geräteflussobjekt mit anpassbarem Abrufeffekt.
acquire_token_interactive

Erwerben Sie token interaktiv, d. h. über einen lokalen Browser.

Voraussetzung: Konfigurieren Sie in Azure-Portal den Umleitungs-URI Ihrer "Mobilen und Desktopanwendung" als http://localhost. Wenn Sie sich für die Verwendung des Brokers während der PublicClientApplication Erstellung entscheiden, benötigen Ihre App auch diesen Umleitungs-URI: ms-appx-web://Microsoft.AAD.BrokerPlugin/YOUR_CLIENT_ID
initiate_device_flow

Initiieren Sie eine Device Flow-Instanz, die in acquire_token_by_device_flow.

acquire_token_by_device_flow

Abrufen eines Tokens durch ein Geräteflussobjekt mit anpassbarem Abrufeffekt.

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

Parameter

Name Beschreibung
flow
Erforderlich
dict

Ein zuvor generiertes Diktat von initiate_device_flow. Standardmäßig blockiert der Abrufeffekt dieser Methode den aktuellen Thread. Sie können die Abrufschleife jederzeit abbrechen, indem Sie den Wert des "expires_at"-Schlüssels des Flusses auf 0 ändern.
claims_challenge

Der claims_challenge Parameter fordert spezifische Ansprüche an, die vom Ressourcenanbieter in Form einer claims_challenge Direktive im www-authenticate-Header vom UserInfo-Endpunkt und/oder im ID-Token und/oder Zugriffstoken zurückgegeben werden. Es handelt sich um eine Zeichenfolge eines JSON-Objekts, das Listen von Ansprüchen enthält, die von diesen Speicherorten angefordert werden.

Standardwert: None

Gibt zurück

Typ Beschreibung

Ein Diktat, das die JSON-Antwort von Microsoft Entra darstellt:

  • Eine erfolgreiche Antwort würde den Schlüssel "access_token" enthalten,

  • eine Fehlerantwort würde "error" und in der Regel "error_description" enthalten.

acquire_token_interactive

Erwerben Sie token interaktiv, d. h. über einen lokalen Browser.

Voraussetzung: Konfigurieren Sie in Azure-Portal den Umleitungs-URI Ihrer "Mobilen und Desktopanwendung" als http://localhost. Wenn Sie sich für die Verwendung des Brokers während der PublicClientApplication Erstellung entscheiden, benötigen Ihre App auch diesen Umleitungs-URI: 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

Name Beschreibung
scopes
Erforderlich
list

Es handelt sich um eine Liste mit Zeichenfolgen mit Groß-/Kleinschreibung.
prompt
str

Standardmäßig wird kein Eingabeaufforderungswert gesendet, nicht einmal eine Zeichenfolge "none". Sie müssen einen Wert explizit angeben. Die gültigen Werte sind die konstanten, die in <xref:msal.Prompt>.

Standardwert: None
login_hint
str

Dies ist optional. Bezeichner des Benutzers. Im Allgemeinen ein Benutzerprinzipalname (User Principal Name, UPN).

Standardwert: None
domain_hint

Kann einer von "Consumern" oder "Organisationen" oder Ihrer Mandantendomäne "contoso.com" sein. Wenn sie enthalten ist, wird der E-Mail-basierte Ermittlungsprozess übersprungen, den der Benutzer auf der Anmeldeseite durchläuft, was zu einer etwas optimierteren Benutzererfahrung führt. Weitere Informationen zu möglichen Werten, die in Auth Code Flow-Dokument und domain_hint Dokument verfügbar sind.

Standardwert: None
claims_challenge

Der claims_challenge Parameter fordert spezifische Ansprüche an, die vom Ressourcenanbieter in Form einer claims_challenge-Direktive im www-authenticate-Header vom UserInfo-Endpunkt und/oder im ID-Token und/oder Zugriffstoken zurückgegeben werden sollen. Es handelt sich um eine Zeichenfolge eines JSON-Objekts, das Listen von Ansprüchen enthält, die von diesen Speicherorten angefordert werden.

Standardwert: None
timeout
int

Diese Methode blockiert den aktuellen Thread. Dieser Parameter gibt den Timeoutwert in Sekunden an. None Standardwert bedeutet, dass auf unbestimmte Zeit gewartet wird.

Standardwert: None
port
int

Der Port, der zum Überwachen einer eingehenden Authentifizierungsantwort verwendet werden soll. Standardmäßig verwenden wir einen vom System zugewiesenen Port. (Der Rest der redirect_uri ist hartcodiert als http://localhost.)

Standardwert: None
extra_scopes_to_consent
list

"Zusätzliche Zustimmungsbereiche" ist ein Konzept, das nur in Microsoft Entra zur Verfügung steht. Es bezieht sich auf andere Ressourcen, für die Sie möglicherweise zur Zustimmung auffordern möchten, in derselben Interaktion, aber für die Sie kein Token für diesen bestimmten Vorgang erhalten.

Standardwert: None
max_age
int

Optional. Maximales Authentifizierungsalter. Gibt die zulässige verstrichene Zeit seit der letzten Authentifizierung des End-User in Sekunden an. Wenn die verstrichene Zeit größer als dieser Wert ist, wird Microsoft Identity Platform den Endbenutzer aktiv erneut authentifizieren.

MSAL-Python überprüft auch automatisch den auth_time im ID-Token.

Neu in Version 1.15.

Standardwert: None
parent_window_handle
int

Optional.

  • Wenn Ihre App sich nicht für die Verwendung des Brokers entscheidet, müssen Sie hier keine Informationen bereitstellen parent_window_handle .

  • Wenn Ihre App sich für die Verwendung des Brokers entscheidet, parent_window_handle ist dies erforderlich.

    • Wenn Es sich bei Ihrer App um eine GUI-App handelt, die auf Windows- oder Mac-System ausgeführt wird, müssen Sie auch das Fensterhandle bereitstellen, damit das Anmeldefenster über dem Fenster angezeigt wird.

    • Wenn Es sich bei Ihrer App um eine Konsolen-App handelt, die auf Windows- oder Mac-System ausgeführt wird, können Sie einen Platzhalter PublicClientApplication.CONSOLE_WINDOW_HANDLEverwenden.

Die meisten Python Skripts sind Konsolen-Apps.

Neu in Version 1.20.0.

Standardwert: None
on_before_launching_ui
<xref:function>

Ein Rückruf mit der Form von lambda ui="xyz", **kwargs: print("A {} will be launched".format(ui)), wo ui entweder "Browser" oder "Broker" sein wird. Sie können es verwenden, um Ihren Endbenutzer darüber zu informieren, dass ein Popupfenster erwartet wird.

Neu in Version 1.20.0.

Standardwert: None
auth_scheme
object

Sie können ein msal.auth_scheme.PopAuthScheme Objekt bereitstellen, damit MSAL ein POP-Token (Proof-of-Possession) für Sie erhält.

Neu in Version 1.26.0.

Standardwert: None

Gibt zurück

Typ Beschreibung

  • Ein Diktat ohne "Error"-Taste und enthält in der Regel einen "access_token"-Schlüssel.

  • Ein Diktat mit einem Fehlerschlüssel, wenn die Tokenaktualisierung fehlgeschlagen ist.

initiate_device_flow

Initiieren Sie eine Device Flow-Instanz, die in acquire_token_by_device_flow.

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

Parameter

Name Beschreibung
scopes
list[str]

Bereiche, die für den Zugriff auf eine geschützte API (eine Ressource) angefordert wurden.

Standardwert: None

Nur Schlüsselwortparameter

Name Beschreibung
claims_challenge
Standardwert: None

Gibt zurück

Typ Beschreibung

Ein Diktat, das ein neu erstelltes Device Flow -Objekt darstellt.

  • Eine erfolgreiche Antwort würde unter anderem den Schlüssel "user_code" enthalten.

  • eine Fehlerantwort würde einige andere lesbare Schlüssel-/Wertpaare enthalten.

Attribute

CONSOLE_WINDOW_HANDLE 

CONSOLE_WINDOW_HANDLE = <object object>

DEVICE_FLOW_CORRELATION_ID 

DEVICE_FLOW_CORRELATION_ID = '_correlation_id'