PublicClientApplication Class
Same as <xref:ClientApplication.__init__>,
except that client_credential parameter shall remain None.
Note
You may set enable_broker_on_windows to True.
What is a broker, and why use it?
A broker is a component installed on your device.
Broker implicitly gives your device an identity. By using a broker,
your device becomes a factor that can satisfy MFA (Multi-factor authentication).
This factor would become mandatory
if a tenant's admin enables a corresponding Conditional Access (CA) policy.
The broker's presence allows Microsoft identity platform
to have higher confidence that the tokens are being issued to your device,
and that is more secure.
An additional benefit of broker is,
it runs as a long-lived process with your device's OS,
and maintains its own cache,
so that your broker-enabled apps (even a CLI)
could automatically SSO from a previously established signed-in session.
You shall only enable broker when your app:
is running on supported platforms,
and already registered their corresponding redirect_uri
ms-appx-web://Microsoft.AAD.BrokerPlugin/your_client_id
if your app is expected to run on Windows 10+
installed broker dependency,
e.g. pip install msal[broker]>=1.25,<2.
tested with acquire_token_interactive() and acquire_token_silent().
The fallback behaviors of MSAL Python's broker support
MSAL will either error out, or silently fallback to non-broker flows.
MSAL will ignore the enable_broker_... and bypass broker
on those auth flows that are known to be NOT supported by broker.
This includes ADFS, B2C, etc..
For other "could-use-broker" scenarios, please see below.
MSAL errors out when app developer opted-in to use broker
but a direct dependency "mid-tier" package is not installed.
Error message guides app developer to declare the correct dependency
msal[broker].
We error out here because the error is actionable to app developers.
MSAL silently "deactivates" the broker and fallback to non-broker,
when opted-in, dependency installed yet failed to initialize.
We anticipate this would happen on a device whose OS is too old
or the underlying broker component is somehow unavailable.
There is not much an app developer or the end user can do here.
Eventually, the conditional access policy shall
force the user to switch to a different device.
MSAL errors out when broker is opted in, installed, initialized,
but subsequent token request(s) failed.
- Inheritance
-
PublicClientApplication
Constructor
PublicClientApplication(client_id, client_credential=None, **kwargs)Parameters
- enable_broker_on_windows
- <xref:boolean>
This setting is only effective if your app is running on Windows 10+. This parameter defaults to None, which means MSAL will not utilize a broker.
New in MSAL Python 1.25.0.
- client_id
- client_credential
Methods
| acquire_token_by_device_flow |
Obtain token by a device flow object, with customizable polling effect. |
| acquire_token_interactive |
Acquire token interactively i.e. via a local browser. Prerequisite: In Azure Portal, configure the Redirect URI of your
"Mobile and Desktop application" as |
| initiate_device_flow |
Initiate a Device Flow instance, which will be used in acquire_token_by_device_flow. |
acquire_token_by_device_flow
Obtain token by a device flow object, with customizable polling effect.
acquire_token_by_device_flow(flow, claims_challenge=None, **kwargs)Parameters
- flow
- dict
A dict previously generated by initiate_device_flow. By default, this method's polling effect will block current thread. You can abort the polling loop at any time, by changing the value of the flow's "expires_at" key to 0.
- claims_challenge
The claims_challenge parameter requests specific claims requested by the resource provider in the form of a claims_challenge directive in the www-authenticate header to be returned from the UserInfo Endpoint and/or in the ID Token and/or Access Token. It is a string of a JSON object which contains lists of claims being requested from these locations.
Returns
A dict representing the json response from Microsoft Entra:
A successful response would contain "access_token" key,
an error response would contain "error" and usually "error_description".
acquire_token_interactive
Acquire token interactively i.e. via a local browser.
Prerequisite: In Azure Portal, configure the Redirect URI of your
"Mobile and Desktop application" as http://localhost.
If you opts in to use broker during PublicClientApplication creation,
your app also need this Redirect 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)Parameters
- prompt
- str
By default, no prompt value will be sent, not even string "none".
You will have to specify a value explicitly.
Its valid values are the constants defined in
<xref:msal.Prompt>.
- login_hint
- str
Optional. Identifier of the user. Generally a User Principal Name (UPN).
- domain_hint
Can be one of "consumers" or "organizations" or your tenant domain "contoso.com". If included, it will skip the email-based discovery process that user goes through on the sign-in page, leading to a slightly more streamlined user experience. More information on possible values available in Auth Code Flow doc and domain_hint doc.
- claims_challenge
The claims_challenge parameter requests specific claims requested by the resource provider in the form of a claims_challenge directive in the www-authenticate header to be returned from the UserInfo Endpoint and/or in the ID Token and/or Access Token. It is a string of a JSON object which contains lists of claims being requested from these locations.
- timeout
- int
This method will block the current thread.
This parameter specifies the timeout value in seconds.
Default value None means wait indefinitely.
- port
- int
The port to be used to listen to an incoming auth response.
By default we will use a system-allocated port.
(The rest of the redirect_uri is hard coded as http://localhost.)
- extra_scopes_to_consent
- list
"Extra scopes to consent" is a concept only available in Microsoft Entra. It refers to other resources you might want to prompt to consent for, in the same interaction, but for which you won't get back a token for in this particular operation.
- max_age
- int
OPTIONAL. Maximum Authentication Age. Specifies the allowable elapsed time in seconds since the last time the End-User was actively authenticated. If the elapsed time is greater than this value, Microsoft identity platform will actively re-authenticate the End-User.
MSAL Python will also automatically validate the auth_time in ID token.
New in version 1.15.
- parent_window_handle
- int
Required if your app is running on Windows and opted in to use broker.
If your app is a GUI app, you are recommended to also provide its window handle, so that the sign in UI window will properly pop up on top of your window.
If your app is a console app (most Python scripts are console apps),
you can use a placeholder value msal.PublicClientApplication.CONSOLE_WINDOW_HANDLE.
New in version 1.20.0.
- on_before_launching_ui
- <xref:function>
A callback with the form of
lambda ui="xyz", **kwargs: print("A {} will be launched".format(ui)),
where ui will be either "browser" or "broker".
You can use it to inform your end user to expect a pop-up window.
New in version 1.20.0.
- auth_scheme
- object
You can provide an msal.auth_scheme.PopAuthScheme object
so that MSAL will get a Proof-of-Possession (POP) token for you.
New in version 1.26.0.
Returns
A dict containing no "error" key, and typically contains an "access_token" key.
A dict containing an "error" key, when token refresh failed.
initiate_device_flow
Initiate a Device Flow instance, which will be used in acquire_token_by_device_flow.
initiate_device_flow(scopes=None, **kwargs)Parameters
Returns
A dict representing a newly created Device Flow object.
A successful response would contain "user_code" key, among others
an error response would contain some other readable key/value pairs.
Attributes
CONSOLE_WINDOW_HANDLE
CONSOLE_WINDOW_HANDLE = <object object>DEVICE_FLOW_CORRELATION_ID
DEVICE_FLOW_CORRELATION_ID = '_correlation_id'Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für