处理 Python 版 MSAL 中的错误和异常

在 msAL for Python 中，大多数错误都作为 API 调用的返回值传达。 该错误以字典形式表示，其中包含来自 Microsoft 标识平台的 JSON 响应。

  • 成功的响应包含 "access_token" 密钥。 响应的格式由 OAuth2 协议定义。 有关详细信息，请参阅 5.1 成功响应
  • 错误响应包含 "error"，并且通常包含 "error_description"。 响应的格式由 OAuth2 协议定义。 有关详细信息，请参阅 5.2 错误响应

返回错误时， "error" 密钥包含计算机可读代码。 例如，如果 "error" 是 "interaction_required"，则可以提示用户提供更多信息以完成身份验证流程。 如果 "error" 是 "invalid_grant"，则可以提示用户重新输入凭据。 以下代码片段是 MSAL 中Python的错误处理示例。


from msal import ConfidentialClientApplication

authority_url = "https://login.microsoftonline.com/your_tenant_id"
client_id = "your_client_id"
client_secret = "your_client_secret"
scopes = ["https://graph.microsoft.com/.default"]

app = ConfidentialClientApplication(client_id, authority=authority_url, client_credential=client_secret)

result = app.acquire_token_silent(scopes=scopes, account=None)

if not result:
    result = app.acquire_token_silent(scopes=scopes)

if "access_token" in result:
    print("Access token: %s" % result["access_token"])
else:
    print("Error: %s" % result.get("error"))

返回错误时，"error_description" 键还会包含一条供人类阅读的消息，并且通常还会有一个 "error_code" 键，其中包含机器可读的 Microsoft 标识平台错误代码。 有关各种Microsoft 标识平台错误代码的详细信息，请参阅身份验证和授权错误代码。

在 msAL for Python 中，异常很少见，因为大多数错误都是通过返回错误值来处理的。 ValueError仅当尝试使用库的方式出现问题（例如 API 参数格式不正确时），才会引发异常。

条件访问和声明质询

以静默方式获取令牌时，如果你尝试访问的 API 需要条件访问声明质询（例如 MFA 策略），则应用程序可能会收到错误。

处理此错误的模式是使用 MSAL 以交互方式获取令牌。 这会提示用户，并使他们能够满足所需的条件访问策略。

在某些情况下调用需要条件访问的 API 时，API 返回的错误中可能会包含声明质询。 例如，如果条件访问策略要求使用托管设备 (Intune)，则错误将类似于 AADSTS53000:需要管理你的设备才能访问此资源。 在这种情况下，可以在获取令牌调用中传递声明，以提示用户满足相应的策略要求。

出现错误和异常后重试

MSAL 会对 Microsoft Entra 服务进行 HTTP 调用，有时会失败。 例如网络崩溃或服务器重载。

MSAL Python 1.11+ 会自动执行一次重试尝试。 可以按照http_client自定义说明自定义此行为。

HTTP 429

如果服务令牌服务器 (STS) 因请求过多而重载，则将返回 HTTP 错误 429，并在 Retry-After 响应字段中提示还要多久才能重试。

你的应用应当对后续请求进行限流，并且仅在指定时间过后才重试。

MSAL Python 1.16+ 使你可以轻松地按需重试身份验证请求（例如，每当最终用户再次单击登录按钮时），MSAL Python 1.16+ 会通过从 HTTP 缓存返回相同的错误响应来自动限制这些重试尝试，并且仅在指定时间段后尝试调用时发送真正的 HTTP 调用。

默认情况下，此限流机制通过将限流信息保存到内置的内存中 HTTP 缓存来工作。 你可以提供自己的 dict类似对象作为 HTTP 缓存，你可以控制如何保留其内容。 有关更多详细信息，请参阅 MSAL Python API 文档。

后续步骤

  • Last updated on