Partager via

PublicClientApplication Class

  • Reference

Same as <xref:ClientApplication.__init__>, except that client_credential parameter shall remain None.

Note

You may set enable_broker_on_windows and/or enable_broker_on_mac 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+

msauth.com.msauth.unsignedapp://auth

if your app is expected to run on Mac

installed broker dependency,

e.g. pip install msal[broker]>=1.31,<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
ClientApplication
PublicClientApplication

Constructor

PublicClientApplication(client_id, client_credential=None, **kwargs)

Parameters

Name Description
enable_broker_on_windows
Required
<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.
enable_broker_on_mac
Required
<xref:boolean>

This setting is only effective if your app is running on Mac. This parameter defaults to None, which means MSAL will not utilize a broker.

New in MSAL Python 1.31.0.
client_id
Required
client_credential
Default value: None

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

Name Description
flow
Required
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.

Default value: None

Returns

Type Description

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

Name Description
scopes
Required
list

It is a list of case-sensitive strings.
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>.

Default value: None
login_hint
str

Optional. Identifier of the user. Generally a User Principal Name (UPN).

Default value: None
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.

Default value: None
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.

Default value: None
timeout
int

This method will block the current thread. This parameter specifies the timeout value in seconds. Default value None means wait indefinitely.

Default value: None
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.)

Default value: None
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.

Default value: None
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.

Default value: None
parent_window_handle
int

OPTIONAL.

  • If your app does not opt in to use broker, you do not need to provide a parent_window_handle here.

  • If your app opts in to use broker, parent_window_handle is required.

    • If your app is a GUI app running on Windows or Mac system, you are required to also provide its window handle, so that the sign-in window will pop up on top of your window.

    • If your app is a console app running on Windows or Mac system, you can use a placeholder PublicClientApplication.CONSOLE_WINDOW_HANDLE.

Most Python scripts are console apps.

New in version 1.20.0.

Default value: None
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.

Default value: None
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.

Default value: None

Returns

Type Description

  • 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

Name Description
scopes
list[str]

Scopes requested to access a protected API (a resource).

Default value: None

Returns

Type Description

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'