ClientApplication 类

在Microsoft Entra 管理中心上注册应用后，应用具有client_id。

对于 PublicClientApplication，请在此处使用 None 。

因此 ConfidentialClientApplication，它支持针对不同方案的许多不同输入格式。

支持使用客户端密码。只需在字符串中馈送，例如 "your client secret"。

支持在 X.509 （.pem） formatDeprecated 中使用证书，因为它使用 SHA-1 指纹，

除非你仍在使用仅支持 SHA-1 指纹的 ADFS。 请使用本页后面介绍的 .pfx 选项。以以下形式以听写形式提供源：

   {
       "private_key": "...-----BEGIN PRIVATE KEY-----... in PEM format",
       "thumbprint": "An SHA-1 thumbprint such as A1B2C3D4E5F6..."
           "Changed in version 1.35.0, if thumbprint is absent"
           "and a public_certificate is present, MSAL will"
           "automatically calculate an SHA-256 thumbprint instead.",
       "passphrase": "Needed if the private_key is encrypted (Added in version 1.6.0)",
       "public_certificate": "...-----BEGIN CERTIFICATE-----...",  # Needed if you use Subject Name/Issuer auth. Added in version 0.5.0.
   }

MSAL Python需要 PEM 格式的“private_key”。 如果证书采用 PKCS12 （.pfx） 格式，则可以按以下方式openssl pkcs12 -in file.pfx -out file.pem -nodes将其转换为 X.509 （.pem） 格式。指纹可在应用的注册Azure 门户中使用。 或者，可以 计算指纹。 public_certificate （可选）是通过“x5c”JWT 标头发送的公钥证书。 如果使用 使用者名称/颁发者身份验证 ，这是一种允许更轻松地轮换证书的方法，这非常有用。 根据 规格，“包含与用于对 JWS 进行数字签名的密钥对应的公钥的证书必须是第一个证书。 这后跟其他证书，每个后续证书都是用于认证上一个证书的证书。但是，证书的颁发者可能会使用不同的顺序。 因此，如果尝试最终出现错误AADSTS700027 - “提供的签名值与预期的签名值不匹配”，则可以尝试仅使用叶证书（以 PEM/str 格式）。

支持从版本 1.13.0 中添加的其他位置获取的原始断言：

它也可以是你自己组装的完全预签名断言。 只需传递仅包含密钥“client_assertion”的容器，如下所示：

   {
       "client_assertion": "...a JWT with claims aud, exp, iss, jti, nbf, and sub..."
   }

支持从 PFX 文件读取客户端证书。在版本 1.29.0 中添加：

包含 PFX 文件路径的字典中的源：

   {
       "private_key_pfx_path": "/path/to/your.pfx",  # Added in version 1.29.0
       "public_certificate": True,  # Only needed if you use Subject Name/Issuer auth. Added in version 1.30.0
       "passphrase": "Passphrase if the private_key is encrypted (Optional)",
   }

以下命令将从.key和 .pem 文件生成 .pfx 文件：

   openssl pkcs12 -export -out certificate.pfx -inkey privateKey.key -in certificate.pem

使用者名称/颁发者身份验证 是一种允许更轻松地轮换证书的方法。 如果 .pfx 文件同时包含私钥和公共证书，则可以通过将“public_certificate”设置为 True“来选择”使用者名称/颁发者身份验证”。

在版本 0.5.0 中添加：它是由此 ConfidentialClientApplication 私钥签名的额外声明字典。 例如，可以使用 {“client_ip”： “x.x.x.x”}。 还可以替代以下任何默认声明：

   {
       "aud": the_token_endpoint,
       "iss": self.client_id,
       "sub": same_as_issuer,
       "exp": now + 10_min,
       "iat": now,
       "jti": a_random_uuid
   }

标识令牌颁发机构的 URL。 它应采用格式 https://login.microsoftonline.com/your_tenant 默认情况下，我们将使用 https://login.microsoftonline.com/common

版本 1.17 中已更改：也可以使用预定义常量和生成器，如下所示：

   from msal.authority import (
       AuthorityBuilder,
       AZURE_US_GOVERNMENT, AZURE_CHINA, AZURE_PUBLIC)
   my_authority = AuthorityBuilder(AZURE_PUBLIC, "contoso.onmicrosoft.com")
   # Now you get an equivalent of
   # "https://login.microsoftonline.com/contoso.onmicrosoft.com"

   # You can feed such an authority to msal's ClientApplication
   from msal import PublicClientApplication
   app = PublicClientApplication("my_client_id", authority=my_authority, ...)

（可选）打开或关闭颁发机构验证。 此参数默认为 true。

设置此 ClientApplication 实例使用的令牌缓存。 默认情况下，将创建和使用内存中缓存。

（可选）抽象类 HttpClient <的实现msal.oauth2cli.http.http_client> 请求会话实例的默认值。 由于 MSAL 1.11.0，因此将默认会话配置为尝试在连接错误时重试一次。 如果提供自己的http_client，则http_client负责决定是否执行重试。

（可选）它将传递给 基础请求库中的 verify 参数 。如果选择传递自己的 Http 客户端，则此参数不适用

（可选）它将传递到 基础请求库中的代理参数 。如果选择传递自己的 Http 客户端，则此参数不适用

（可选）它将传递给 基础请求库中的超时参数 。如果选择传递自己的 Http 客户端，则不适用

（可选）可以为Microsoft遥测目的提供应用程序名称。 默认值为 None，表示不会传递给Microsoft。

（可选）可以为Microsoft遥测目的提供应用程序版本。 默认值为 None，表示不会传递给Microsoft。

（可选）允许配置一个或多个客户端功能，例如 [“CP1”]。

客户端功能旨在通知Microsoft 标识平台（STS）此客户端的功能，以便 STS 可以决定启用某些功能。 例如，如果客户端能够处理 声明质询，STS 可能会向资源发出 持续访问评估（CAE） 访问令牌，知道当资源发出 声明质询 时，客户端将能够处理这些质询。

实现详细信息：客户端功能目前使用网络上的“声明”参数实现。 MSAL 会将它们合并为 声明参数 ，稍后会通过某个获取令牌请求提供这些参数。

（可选）指示 MSAL 使用 Entra 区域令牌服务。 此旧功能仅适用于第一方应用程序。 仅支持 acquire_token_for_client()。

支持 4 个值：

1. azure_region=None - 此默认值表示未配置任何区域。 MSAL 将使用 env var MSAL_FORCE_REGION中定义的区域。

2. azure_region="some_region" - 表示使用指定的区域。

3. azure_region=True - 这意味着 MSAL 将尝试自动检测区域。 不建议这样做。

4. azure_region=False - 这意味着 MSAL 不使用任何区域。

版本 1.12.0 中的新增功能。

（可选）从历史上看，MSAL 硬编码 offline_access 范围，这将使你的应用能够长时间访问用户的数据。 如果应用不必要或不需要，现在可以使用此参数提供范围排除列表，例如 exclude_scopes = ["offline_access"]。

MSAL 长期以来一直在缓存令牌 token_cache。 最近，MSAL 还引入了一种概念http_cache，即自动缓存一些有限数量的非令牌 http 响应，以便在PublicClientApplicationConfidentialClientApplication某些情况下具有更高的性能和响应能力。

此参数 http_cache 接受任何类似于听写的对象。 如果未提供，MSAL 将使用内存中听写。

如果应用是命令行应用（CLI），则希望在不同的 CLI 运行中保留http_cache。 持久化文件格式可能会因 不稳定协议（包括但不限于）而更改，因此实现应容忍意外加载错误。 以下食谱显示了一种执行此操作的方法：

   # Just add the following lines at the beginning of your CLI script
   import sys, atexit, pickle, logging
   http_cache_filename = sys.argv[0] + ".http_cache"
   try:
       with open(http_cache_filename, "rb") as f:
           persisted_http_cache = pickle.load(f)  # Take a snapshot
   except (
           FileNotFoundError,  # Or IOError in Python 2
           pickle.UnpicklingError,  # A corrupted http cache file
           AttributeError,  # Cache created by a different version of MSAL
           ):
       persisted_http_cache = {}  # Recover by starting afresh
   except:  # Unexpected exceptions
       logging.exception("You may want to debug this")
       persisted_http_cache = {}  # Recover by starting afresh
   atexit.register(lambda: pickle.dump(
       # When exit, flush it back to the file.
       # It may occasionally overwrite another process's concurrent write,
       # but that is fine. Subsequent runs will reach eventual consistency.
       persisted_http_cache, open(http_cache_file, "wb")))

   # And then you can implement your app as you normally would
   app = msal.PublicClientApplication(
       "your_client_id",
       ...,
       http_cache=persisted_http_cache,  # Utilize persisted_http_cache
       ...,
       #token_cache=...,  # You may combine the old token_cache trick
           # Please refer to token_cache recipe at
           # https://msal-python.readthedocs.io/en/latest/#msal.SerializableTokenCache
       )
   app.acquire_token_interactive(["your", "scope"], ...)

里面 http_cache 的内容是廉价获得的。 无需在不同的应用之间共享它们。

内部 http_cache 内容不包含令牌或个人身份信息（PII）。 加密是不必要的。

版本 1.16.0 中的新增功能。

从历史上看，MSAL 将连接到位于获取 https://login.microsoftonline.com 某些元数据的中央终结点，尤其是在使用不熟悉的颁发机构时。 此行为称为实例发现。

此参数默认为 None，这将启用实例发现。

如果你知道一些允许 MSAL 使用 as-is操作的颁发机构，而不涉及任何实例发现，建议的模式是：

   known_authorities = frozenset([  # Treat your known authorities as const
       "https://contoso.com/adfs", "https://login.azs/foo"])
   ...
   authority = "https://contoso.com/adfs"  # Assuming your app will use this
   app1 = PublicClientApplication(
       "client_id",
       authority=authority,
       # Conditionally disable Instance Discovery for known authorities
       instance_discovery=authority not in known_authorities,
       )

如果你事先不知道某些颁发机构，但仍希望 MSAL 接受你提供的任何授权，则可以使用 a False 无条件地禁用实例发现。

版本 1.19.0 中的新增功能。

Deprecated. 请改用 enable_broker_on_windows。

启用后，日志可能包括 PII（个人身份信息）。 这在排查代理行为时很有用。 默认行为为 False。

版本 1.24.0 中的新增功能。

在版本 1.28.0 中添加：它是标识格式 https://contoso.com/tenant的 OpenID Connect （OIDC） 颁发机构的 URL。 MSAL 会将“.known/openid-configuration”追加到颁发机构，并从那里检索 OIDC 元数据，以找出终结点。

注意：代理将不用于 OIDC 颁发机构。