请求用户同意
重要
2022 年 6 月，我们引入了 多重身份验证 作为必应广告的要求。 可能需要更改代码才能符合此要求。 Microsoft广告公司正在 10 月初进行技术强制检查。
此博客文章 概述了确保合规性应采取的步骤。
有关详细信息，请参阅 多重身份验证要求 指南。
注册应用程序后，需要获得用户同意，以便管理其Microsoft广告帐户。
提示
有关故障排除帮助，请参阅 常见 OAuth 错误 指南。
重要
必须至少提示每个用户并通过 Web 浏览器控件提供一次同意，以便应用程序管理其Microsoft广告帐户。 这是一个标准的 OAuth 2.0 流，在 OAuth 2.0 规范的授权代码授予部分中进行了详细定义。
授权代码流从客户端将用户定向到 /authorize 终结点开始。 在此请求中，客户端指示它需要从用户获取的权限：
注意
将下面的 your_client_id 替换为 Azure 门户 - 应用注册门户 分配应用的应用程序 (客户端) ID。
// Line breaks for legibility only
https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=your_client_id
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=openid%20offline_access%20https%3A%2F%2Fads.microsoft.com%2Fmsads.manage
&state=12345
- 复制以下 URL 并将其粘贴到浏览器中，以执行此示例请求用户同意。
注意
将以下 URL 中的 your_client_id 替换为 Azure 门户 - 应用注册门户 分配应用的应用程序 (客户端) ID。
<https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=your_client_id&response_type=code&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F&response_mode=query&scope=openid%20offline_access%20https%3A%2F%2Fads.microsoft.com%2Fmsads.manage&state=12345>
- 使用Microsoft帐户凭据登录，并授予 应用 管理Microsoft广告帐户的许可。
- 登录后，浏览器应重定向到
https://localhost/myapp/地址栏中的 。code可以忽略页面上的错误消息。 - 接下来，你将使用代码 获取访问令牌和刷新令牌。
Microsoft标识平台终结点还将确保用户已同意查询参数中 scope 指示的权限。 如果用户未同意任何这些权限，它将要求用户同意所需的权限。 尽管本指南主要侧重于通过 scope=https://ads.microsoft.com/msads.manage管理Microsoft广告帐户， 但此处提供了有关Microsoft标识平台中权限和同意的更多详细信息。
用户进行身份验证并授予同意后，Microsoft标识平台终结点将使用 参数中指定的response_mode方法在指定的 redirect_uri处返回对应用的响应。 例如，如果用户授予应用程序管理其Microsoft广告帐户的权限，则回调 URI 包含如下授权代码： http://localhost/myapp/?code=CodeGoesHere&state=12345。
如果用户授予应用程序管理其Microsoft广告帐户的权限，则应在下一步中立即使用该代码。 授权代码的短时间（大约 5 分钟）可能会更改。 如果用户拒绝了应用程序管理其Microsoft广告帐户的权限，则回调 URI 包括错误和错误说明字段，如下所示： http://localhost/myapp/?error=access_denied&error_description=ERROR_DESCRIPTION&state=ClientStateGoesHere。 有关 OAuth 错误的更多详细信息，请参阅 常见 OAuth 错误 和 身份验证和授权错误代码。
下表包含必应广告 API 客户端可以包含在同意请求中的参数。 有关可选参数的其他详细信息，请参阅Microsoft标识平台 OAuth 2.0 授权代码流 文档。
| 参数 | 必需/可选 | 说明 |
|---|---|---|
client_id |
必需 | 应用程序 (客户端) Azure 门户 - 应用注册 门户分配应用的 ID。 |
code_challenge |
建议 | 用于通过代码交换 (PKCE) 的证明密钥来保护授权代码授权。 如果 code_challenge_method 包含 ，则为 必需。 有关详细信息，请参阅 PKCE RFC。 现在建议对所有应用程序类型（本机应用、SPA 和机密客户端（如 Web 应用）使用此方法。 |
code_challenge_method |
建议 | 用于为 code_challenge 参数编码 code_verifier 的方法。 可以是下列值之一：- plain - S256如果排除， code_challenge 则假定为纯文本（如果 code_challenge 包含 ）。 Microsoft标识平台支持 plain 和 S256。 有关详细信息，请参阅 PKCE RFC。 |
prompt |
可选 | 指示应用程序所需的用户交互类型。 支持的值包括： - prompt=login 将强制用户在该请求上输入其凭据，并取消单一登录。- prompt=none 与“登录”相反，即它将确保用户不会显示任何交互式提示。 如果无法通过单一登录以无提示方式完成请求，Microsoft标识平台终结点将返回interaction_required错误。- prompt=consent 将在用户登录后触发 OAuth 同意对话框，要求用户向应用授予权限。- prompt=select_account 将中断单一登录并提供帐户选择体验，列出会话中的所有帐户或任何已记住的帐户，或者选择完全使用其他帐户的选项。 |
redirect_uri |
必需 | 应用的redirect_uri，应用可在其中发送和接收身份验证响应。 它必须与在门户中注册的某个redirect_uris完全匹配，除非它必须经过 URL 编码。 对于本机 & 移动应用，应使用默认值 https://login.microsoftonline.com/common/oauth2/nativeclient。 |
response_mode |
建议 | 指定用于将生成的令牌发送回应用的方法。 可以是下列类型之一： - query- fragment- form_postquery 将代码作为重定向 URI 上的查询字符串参数提供。 如果使用隐式流请求 ID 令牌，则不能按 OpenID 规范中的指定使用query。如果只请求代码，则可以使用 query、 fragment或 form_post。
form_post 执行包含重定向 URI 的代码的 POST。 有关详细信息，请参阅 OpenID Connect 协议。 |
response_type |
必需 | 必须包括授权代码流的 code。 |
scope |
必需 | 希望用户同意的范围的空格分隔列表。 请务必包含 https://ads.microsoft.com/msads.manage 以提示用户进行Microsoft广告访问。 Include offline_access 可确保响应中包含刷新令牌。 |
state |
建议 | 请求中包含的一个值，该值也将在令牌响应中返回。 它可以是所需的任何内容的字符串。 随机生成的唯一值通常用于 防止跨站点请求伪造攻击。 该值还可以在身份验证请求发生前对应用中用户的状态信息进行编码，例如用户所访问的页面或视图。 |
tenant |
必需 | 请求路径中的 {tenant} 值可用于控制登录应用程序的用户。 为了确保应用程序同时支持 MSA 个人帐户和 Azure AD 工作或学校帐户，建议使用 common 作为必应广告 API 身份验证的租户。如果应用程序需要另一个租户，请参阅 Microsoft标识平台终结点 了解详细信息。 |