PublicClientApplication 类

同样 <xref:ClientApplication.__init__>，除了该 client_credential 参数应保留 None。

注释

什么是中转站，为什么使用它？

代理是在设备上安装的组件。

中转站隐式为设备提供标识。 通过使用中转站，

你的设备将成为满足 MFA（多重身份验证）的因素。

此因素将成为强制性因素

如果租户的管理员启用相应的条件访问（CA）策略，

中转站的存在允许Microsoft 标识平台

若要提高令牌颁发给设备的置信度，请执行以下操作：

这更安全。

中转站的另一个好处是，

它作为设备 OS 的长期进程运行，

并维护自己的缓存，

使支持中转站的应用（甚至 CLI）

可以从以前建立的已登录会话自动 SSO。

如何选择使用中转站？

可以将以下选择加入参数的任意组合设置为 true：

选择加入标志

如果应用将在

应用已在 Azure 门户 中将其注册为桌面平台重定向 URI

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

msauth.com.msauth.unsignedapp：//auth

enable_broker_on_linux

安装了 Intune 的 Linux

https://login.microsoftonline.com/common/oauth2/nativeclient （必须启用）

安装代理依赖项，

例如 pip install msal[broker]>=1.33,2<。

使用 acquire_token_interactive（） 和 acquire_token_silent（） 进行测试。

MSAL Python中转站支持的回退行为

MSAL 会出错或无提示地回退到非代理流。

MSAL 将忽略enable_broker_...和绕过中转站

中转站不支持的身份验证流。

这包括 ADFS、B2C 等。

有关其他“可能使用中转站”方案，请参阅下文。

当应用开发人员选择使用中转站时出现 MSAL 错误

但未安装直接依赖项“中间层”包。

错误消息指导应用开发人员声明正确的依赖项

msal[broker]。

我们在此处出错，因为该错误对于应用开发人员是可操作的。

MSAL 以无提示方式“停用”中转站并回退到非中转站，

选择加入时，安装依赖项但无法初始化。

我们预计，在 OS 太旧的设备上会发生这种情况

或基础中转站组件不知何故不可用。

应用开发人员或最终用户无法在此处执行操作。

最终，条件访问策略应

强制用户切换到其他设备。

选择加入、安装、初始化中转站时出现 MSAL 错误

但后续令牌请求失败。

构造函数

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)

参数

名称 说明
enable_broker_on_windows
必需
<xref:boolean>

仅当应用在 Windows 10+ 上运行时，此设置才有效。 此参数默认为 None，这意味着 MSAL 不会利用中转站。

MSAL Python 1.25.0 中的新增功能。
enable_broker_on_mac
必需
<xref:boolean>

仅当应用在 Mac 上运行时，此设置才有效。 此参数默认为 None，这意味着 MSAL 不会利用中转站。

MSAL Python 1.31.0 中的新增功能。
enable_broker_on_linux
必需
<xref:boolean>

仅当应用在 Linux 上运行（包括 WSL）时，此设置才有效。 此参数默认为 None，这意味着 MSAL 不会利用中转站。

MSAL Python 1.33.0 中的新增功能。
enable_broker_on_wsl
必需
<xref:boolean>

仅当应用在 WSL 上运行时，此设置才有效。 此参数默认为 None，这意味着 MSAL 不会利用中转站。

MSAL Python 1.33.0 中的新增功能。
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

方法

acquire_token_by_device_flow

通过设备流对象获取令牌，并具有可自定义的轮询效果。
acquire_token_interactive

通过本地浏览器以交互方式获取令牌。

先决条件：在Azure 门户中，将“移动和桌面应用程序”的重定向 URI 配置为http://localhost。 如果在创建过程中 PublicClientApplication 选择使用中转站，则应用还需要以下重定向 URI： ms-appx-web://Microsoft.AAD.BrokerPlugin/YOUR_CLIENT_ID
initiate_device_flow

启动将在其中 acquire_token_by_device_flow使用的设备流实例。

acquire_token_by_device_flow

通过设备流对象获取令牌，并具有可自定义的轮询效果。

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

参数

名称 说明
flow
必需
dict

以前由 initiate_device_flow. 默认情况下，此方法的轮询效果将阻止当前线程。 你可以随时中止轮询循环，方法是将流的“expires_at”键的值更改为 0。
claims_challenge

claims_challenge参数请求资源提供程序以 www-authenticate 标头中claims_challenge指令的形式请求的特定声明，这些声明将从 UserInfo 终结点和/或 ID 令牌和/或访问令牌中返回。 它是 JSON 对象的字符串，其中包含从这些位置请求的声明列表。

默认值: None

返回

类型 说明

表示来自Microsoft Entra的 json 响应的听写：

  • 成功的响应将包含“access_token”密钥，

  • 错误响应将包含“error”和通常为“error_description”。

acquire_token_interactive

通过本地浏览器以交互方式获取令牌。

先决条件：在Azure 门户中，将“移动和桌面应用程序”的重定向 URI 配置为http://localhost。 如果在创建过程中 PublicClientApplication 选择使用中转站，则应用还需要以下重定向 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)

参数

名称 说明
scopes
必需
list

它是区分大小写的字符串列表。
prompt
str

默认情况下，不会发送任何提示值，甚至不会发送字符串 "none"。 必须显式指定值。 其有效值为在 . 中 <xref:msal.Prompt>定义的常量。

默认值: None
login_hint
str

Optional. 用户的标识符。 通常为用户主体名称（UPN）。

默认值: None
domain_hint

可以是“使用者”或“组织”之一，也可以是租户域“contoso.com”。 如果包含，它将跳过用户在登录页面上经历的基于电子邮件的发现过程，从而导致略微简化的用户体验。 有关 Auth Code Flow 文档 和 domain_hint 文档中可用的可能值的详细信息。

默认值: None
claims_challenge

claims_challenge参数请求资源提供程序以 www-authenticate 标头中claims_challenge指令的形式请求的特定声明，这些声明将从 UserInfo 终结点和/或 ID 令牌和/或访问令牌中返回。 它是 JSON 对象的字符串，其中包含从这些位置请求的声明列表。

默认值: None
timeout
int

此方法将阻止当前线程。 此参数指定超时值（以秒为单位）。 默认值 None 表示无限期等待。

默认值: None
port
int

用于侦听传入身份验证响应的端口。 默认情况下，我们将使用系统分配的端口。 （redirect_uri的其余部分被硬编码为 http://localhost.）

默认值: None
extra_scopes_to_consent
list

“同意的额外范围”是仅在Microsoft Entra中提供的概念。 它指的是你可能希望在同一交互中提示同意的其他资源，但在此特定操作中，你不会为其返回令牌。

默认值: None
max_age
int

可选。 最大身份验证期限。 指定自上次对 End-User 主动进行身份验证以来允许的运行时间（以秒为单位）。 如果已用时间大于此值，Microsoft 标识平台将主动重新对最终用户进行身份验证。

MSAL Python还会自动验证 ID 令牌中的auth_time。

版本 1.15 中的新增功能。

默认值: None
parent_window_handle
int

可选。

  • 如果你的应用未选择使用中转站，则无需在此处提供 parent_window_handle 。

  • 如果你的应用选择使用中转站， parent_window_handle 则需要。

    • 如果你的应用是在 Windows 或 Mac 系统上运行的 GUI 应用，则还需要提供其窗口句柄，以便登录窗口在窗口顶部弹出。

    • 如果你的应用是在 Windows 或 Mac 系统上运行的控制台应用，则可以使用占位符PublicClientApplication.CONSOLE_WINDOW_HANDLE。

大多数Python脚本都是控制台应用。

版本 1.20.0 中的新增功能。

默认值: None
on_before_launching_ui
<xref:function>

一个回调， lambda ui="xyz", **kwargs: print("A {} will be launched".format(ui))其 ui 形式为“browser”或“broker”。 可以使用它通知最终用户期待弹出窗口。

版本 1.20.0 中的新增功能。

默认值: None
auth_scheme
object

你可以提供一个 msal.auth_scheme.PopAuthScheme 对象，以便 MSAL 将为你获取所有权证明（POP）令牌。

版本 1.26.0 中的新增功能。

默认值: None

返回

类型 说明

  • 不包含“error”键的听写，通常包含“access_token”键。

  • 令牌刷新失败时，包含“error”密钥的听写。

initiate_device_flow

启动将在其中 acquire_token_by_device_flow使用的设备流实例。

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

参数

名称 说明
scopes
list[str]

请求访问受保护 API 的范围（资源）。

默认值: None

仅限关键字的参数

名称 说明
claims_challenge
默认值: None

返回

类型 说明

表示新创建的 Device Flow 对象的听写。

  • 成功的响应将包含“user_code”密钥等

  • 错误响应将包含一些其他可读键/值对。

属性

CONSOLE_WINDOW_HANDLE 

CONSOLE_WINDOW_HANDLE = <object object>

DEVICE_FLOW_CORRELATION_ID 

DEVICE_FLOW_CORRELATION_ID = '_correlation_id'