OAuth 2.0 混合 Web 服务器流
使用 OAuth 2.0 混合 Web 服务器流，让混合应用程序直接管理 Web 会话。当授权服务器授予访问标记时，它会在其响应中包含所请求域的会话 ID (SID)。然后，混合应用程序可以设置 Lightning、Visualforce 和内容域 Cookie，并将访问令牌连接到 Web 会话，从而提供不间断的服务。
所需的 Edition
| 适用于：Salesforce Classic（并非在所有组织中可用）和 Lightning Experience |
| 适用于：所有版本 |
混合 Web 服务器流遵循适用于桌面或移动应用程序集成的 OAuth 2.0 用户代理流中使用的相同授权步骤，不同的是混合 Web 服务器流使用hybrid_auth_code作为其授权类型。例如，您为销售部门构建了一个混合应用程序来随时访问信息，包括一个跟踪热门潜在客户的仪表板。该应用程序实施混合用户-客服人员令牌流，它遵循以下步骤。
- 要将混合应用程序与 Salesforce API 集成，请创建外部客户端应用程序。启用 OAuth 设置，并将这些 OAuth 范围分配给外部客户端应用程序。
-
-
lightning -
content -
refresh_token -
visualforce -
web
-
- 最终用户打开该应用程序，并被引导至 Salesforce 对该应用程序进行验证和授权。
- 用户批准访问此授权流后，应用程序会收到来自 Salesforce 的对重定向 URL 的回调，重定向 URL 会提取访问和刷新令牌。相应域的 Visualforce、Lightning 和内容 SID 也包含在内，以及允许应用程序直接桥接 Web 会话的会话 Cookie。
备注 仅当外部客户端应用程序未启用刷新标记轮换时，此流才支持基于 JWT 的访问标记。如果启用刷新令牌轮换，令牌请求会返回invalid_grant错误。 - 该应用程序设置 Lightning、Visualforce 和内容域的会话 Cookie，并将访问标记桥接到网络会话中。
- 用户可以在不中断会话的情况下访问热门销售潜在客户仪表板。
请求授权代码
为了启动 OAuth 2.0 混合 Web 服务器流，外部 Web 服务通过外部客户端应用程序，使用授权代码授权类型向 Salesforce 授权端点发布授权代码请求。通过授权代码，外部客户端应用程序可以证明它已被授权为站点的安全访问者，并且它有权请求访问令牌。
授权代码以 HTTP 重定向的形式生成，例如此示例。
https://MyDomainName.my.salesforce.com/services/oauth2/authorize?
client_id=3MVG9IHf89I1t8hrvswazsWedXWY0i1qK20PSFaInvUgLFB6vrcb9bbWFTSIHpO8G2jxBLJA6uZGyPFC5Aejq&
redirect_uri=https://www.mycustomerorderstatus.com/oauth2/callback&
response_type=code将这些参数包含在授权代码请求中。
| 参数 | 描述 |
|---|---|
Request Header
|
Salesforce OAuth 2.0 授权端点。外部客户端应用程序向该端点发送 OAuth 授权请求。 |
client_id
|
外部客户端应用程序的使用者密钥。要访问使用者密钥，请从外部客户端应用程序管理器中找到外部客户端应用程序，并从下拉列表中选择编辑设置。然后，展开 Oauth 设置部分，并单击消费者密钥和密码。在查看消费者密钥之前，有时会提示您验证您的身份。 |
redirect_uri
|
成功身份验证后用户重定向的 URL。重定向 URI 必须匹配外部客户端应用程序的回调 URL 字段中的一个值。否则，批准失败。您可以在外部客户端应用程序的 OAuth 设置页面上找到重定向 URI。该值必须是编码 URL。 |
response_type
|
外部客户端应用程序请求的 OAuth 2.0 授权类型。此流的值必须是 code，以表示外部客户端应用程序正在请求授权代码。 |
您也可以在授权代码请求中包含这些参数。
| 参数 | 描述 |
|---|---|
scope
|
定义外部客户端应用程序可以访问的受保护资源类型的权限。在构建外部客户端应用程序时，您可为其分配范围，并在授权流期间包含在 OAuth 令牌中。 如果您不包含此参数，则会请求分配给外部客户端应用程序的所有范围。此参数中传递的范围必须是已注册范围的子集。有关有效参数，请参阅OAuth 令牌和范围。 |
state
|
外部 Web 服务请求发送到回调 URL 的任何状态。该值必须是编码 URL。 |
immediate
|
布尔值，用于确定是否提示用户登录和批准。默认值是
|
code_challenge
|
指定令牌请求中 如果在令牌请求中指定了
|
display
|
更改登录和授权页面的显示类型。Salesforce 支持这些值。
|
login_hint
|
提供有效的用户名值，以使用用户名预填充登录页面，例如 要为 Experience Cloud 站点传递 |
nonce
|
与openid范围一起使用，以请求用户 ID 令牌。响应中将返回用户 ID 标记。此参数是可选的，但它有助于检测重放攻击。
|
prompt
|
指定验证服务器如何提示用户再验证和再批准。Salesforce 支持这些值。
您可以传递 |
Uvid-Hint标题 |
或者，要将此流连接到无头来宾流，您可以包含带有基于 JWT 的访问令牌的 如果您在应用程序中实施来宾用户流，您可以选择使用此标题来传入基于 JSON Web 令牌 (JWT) 的访问令牌，其中包含一个与来宾用户身份相关联的惟一访问者 ID (UVID)。通过将 UVID 传递给命名用户流，您可以将来自来宾用户会话的上下文信息（例如用户的 Cookie 首选项）传递给命名用户会话。 |
uvid_hint正文参数 |
普通 您还可以通过 |
用户验证和授权访问
在 Salesforce 向外部客户端应用程序提供授权代码之前，身份验证用户需要登录到 Salesforce。
成功登录后，Salesforce 会将用户重定向到批准页面，以授予对应用程序的访问权限。
如果用户先前批准了访问，他们就不必再次批准访问。
Salesforce 授予授权代码
用户批准访问外部客户端应用程序后，Salesforce 会将用户重定向到回调 URL，用户可在其中使用授权代码查看回调。
https://www.mycustomerorderstatus.com/oauth2/callback?
code=aPrx4sgoM2Nd1zWeFVlOWveD0HhYmiDiLmlLnXEBgX01tpVOQMWVSUuafFPHu3kCSjzk4CUTZg==- 回调的第一部分是外部客户端应用程序的回调 URL：
https://www.mycustomerorderstatus.com/oauth2/callback. - 第二部分是外部客户端应用程序用于获取访问令牌的授权代码：
code=aPrx4sgoM2Nd1zWeFVlOWveD0HhYmiDiLmlLnXEBgX01tpVOQMWVSUuafFPHu3kCSjzk4CUTZg==。授权代码会在 15 分钟后过期。
如果原始查询字符串中包含 state 参数，则指定的状态会传递到批准步骤。
请求访问标记
要请求访问令牌，外部客户端应用程序会将授权代码作为 HTTP POST 传输到 Salesforce 令牌端点。
POST /services/oauth2/token HTTP/1.1
Host: mycompany.my.salesforce.com
Content-length: 307
Content-type: application/x-www-form-urlencoded
grant_type=hybrid_auth_code&
code=aPrxhgZ2MIpkSy0aOdn07LjKFvsFOis6RGcWXz7p8JQCjcqfed5NQLe7sxWwMY_JQFuLwHRaRA==&
client_id=3MVG9IHf89I1t8hrvswazsWedXWY0iqK20PSFaInvUgLFB6vrcb9bbWFTSIHpO8G2jxBLJA6uZGyPFC5Aejq&
client_secret=*******************&
redirect_uri=https://www.mycustomerorderstatus.com/oauth2/callback
示例中的 POST 包含以下参数。
| 参数 | 描述 |
|---|---|
Request Header
|
请求页眉可以包含以下参数。
请求页眉还支持以下参数。
|
grant_type
|
外部客户端应用程序可以提供的验证类型，以证明它是安全的访问者。对于混合 Web 服务器流，值必须是 hybrid_auth_code。 |
code
|
从授权服务器接收的临时授权代码。外部客户端应用程序使用此代码交换访问令牌。这种 OAuth 2.0 流是将访问标记传递回应用程序的安全方式。 |
client_id
|
外部客户端应用程序的使用者密钥。要访问使用者密钥，请从外部客户端应用程序管理器中找到外部客户端应用程序，并从下拉列表中选择编辑设置。然后，展开 Oauth 设置部分，并单击消费者密钥和密码。在查看消费者密钥之前，有时会提示您验证您的身份。 |
client_secret
|
外部客户端应用程序的使用者密码。要访问使用者密码，请从外部客户端应用程序管理器中找到外部客户端应用程序，并从下拉列表中选择编辑设置。然后，展开 Oauth 设置部分，并单击消费者密钥和密码。在查看使用者密码之前，有时会提示您验证您的身份。 此参数是必填项，除非外部客户端应用程序未启用需要 Web 服务器流的密码。如果不需要 |
redirect_uri
|
成功身份验证后用户重定向的 URL。重定向 URI 必须匹配外部客户端应用程序的回调 URL 字段中的一个值。否则，批准失败。您可以在外部客户端应用程序的 OAuth 设置页面或外部客户端应用程序的定义中找到重定向 URI。该值必须是编码 URL。 |
您也可以包含这些参数。
| 参数 | 描述 |
|---|---|
client_assertion
|
您可以提供client_assertion和client_assertion_type，而不是传递client_secret。如果未提供 client_secret 参数，Salesforce 会检查client_assertion和client_assertion_type。请参阅使用client_assertion而不是client_secret。 |
client_assertion_type
|
使用
|
code_verifier
|
仅当授权请求中指定了 code_challenge 参数时才需要。指定 128 字节的高熵随机数据，使猜测
|
format
|
如果没有包含在请求的标题中，您可以指定预期的返回格式。
|
client_assertion而不是client_secret如果您提供client_assertion而不是client_secret，client_assertion 的值必须包含这些参数。
iss— 来自外部客户端应用程序定义的client_id。sub— 来自外部客户端应用程序定义的client_id。aud— 令牌 servlet URL：https://hostname/services/oauth2/token。exp— 声明在 5 分钟内的到期时间，用 UTC 测量的从 1970-01-01T0:0:0Z 开始的秒数表示。
client_assertion还必须使用与 OAuth 使用者上传的证书相关联的私钥进行签名。仅支持 RS256 算法。有关 private_key_jwt 客户端身份验证方法，请参阅 OpenID Connect 规范。
Salesforce 支持 HTTPS 基础身份验证方案，而不是在 POST 的正文中将客户端凭据作为参数发送。此方案的格式需要在帖子的授权标题中进行如下client_id和client_secret。
Authorization:
Basic64Encode(client_id:secret)
client_id 和 client_secret 使用冒号 (:) 分隔。有关更多信息，请查看 OAuth 2.0 授权框架文档。
此示例显示使用 HTTPS 基础身份验证方案的访问令牌 POST 请求，而不是在 POST 请求正文中发送的客户端凭据。
POST /services/oauth2/token HTTP/1.1
Host: mycompany.my.salesforce.com
Authorization: Basic client_id=3MVG9IHf89I1t8hrvswazsWedXWY0iqK20PSFaInvUgLFB6vrcb9bbWFTSIHpO8G2jxBLJA6uZGyPFC5Aejq&
client_secret=*******************&
grant_type=hybrid_auth_code&code=aPrxsmIEeqM9PiQroGEWx1UiMQd95_5JUZ
VEhsOFhS8EVvbfYBBJli2W5fn3zbo.8hojaNW_1g%3D%3D&
redirect_uri=https%3A%2F%2Fwww.mysite.com%2Fcode_callback.jspclient_id和client_secret在 POST 的正文中发送，授权标题将被忽略。Salesforce 授予访问标记
Salesforce 验证应用程序的凭据后，它会发回带有访问令牌的响应。
在本示例中，响应为 JSON 格式。
{
"access_token": "00DB0000000TfcR!AQQAQFhoK8vTMg_rKA.esrJ2bCs.OOIjJgl.9Cx6O7KqjZmHMLOyVb.U61BU9tm4xRusf7d3fD1P9oefzqS6i9sJMPWj48IK",
"signature": "d/SxeYBxH0GSVko0HMgcUxuZy0PA2cDDz1u7g7JtDHw=",
"scope": "web openid",
"id_token": "eyJraWQiOiIyMjAiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdF9oYXNoIjoiSVBRNkJOTjlvUnUyazdaYnYwbkZrUSIsInN1YiI6Imh0dHBzOi8vbG9...",
"instance_url": "https://mycompany.my.salesforce.com",
"id": "https://login.salesforce.com/id/00DB0000000TfcRMAS/005B0000005Bk90IAC",
"token_type": "Bearer",
"issued_at": "1558553873237"
}
令牌响应包含这些参数。
| 参数 | 描述 |
|---|---|
access_token
|
外部客户端应用程序用于代表客户端应用程序请求访问受保护资源的 OAuth 令牌。访问标记可以附带范围形式的附加权限。 |
signature
|
使用 client_secret 签名的 Base64 编码 HMAC-SHA256 签名。签名可以包括连接 ID 和issued_at value，您可以使用它们来验证身份 URL 在服务器发送后没有更改。 |
scope
|
与访问标记关联的范围。 范围进一步定义了客户端可以访问的受保护资源的类型。在构建外部客户端应用程序时，您可为其分配范围，并在授权流期间包含在 OAuth 令牌中。 有关有效参数，请参阅OAuth 令牌和范围。 |
content_domain
|
内容会话的域，映射到内容 SID：MyDomainName.file.force.com →
content_sid.
|
content_sid
|
与内容会话的域相关联的 SID。Salesforce 返回一个混合应用程序直接在域的会话 Cookie 中设置的唯一 SID。 |
lightning_domain
|
Lightning 会话的域，映射到 Lightning SID：<MyDomainName or
instance>.lightning.force.com → lightning_sid.
|
lightning_sid
|
与 Lightning 会话的域相关联的 SID。Salesforce 返回一个混合应用程序直接在域的会话 Cookie 中设置的唯一 SID。 |
visualforce_domain
|
Visualforce 会话的域，映射到 Visualforce SID：MyDomainName.vf.force.com →
visualforce_sid.
|
visualforce_sid
|
与 Visualforce 会话的域相关联的 SID。Salesforce 返回一个混合应用程序直接在域的会话 Cookie 中设置的唯一 SID。 |
csrf_token
|
跨站点请求伪造 (CSRF) 标记，以防止子会话期间的攻击。 |
id_token
|
一种签名数据结构，包含经过身份验证的用户属性，包括用户的唯一标识符和指示标记发放时间的时间戳。此外，也会识别请求的客户端应用程序。请参见 OpenID Connect 规格。 如果范围参数包含 |
instance_url
|
指示用户的组织实例的 URL。例如：https://yourInstance.salesforce.com/.
|
id
|
可用于标识用户以及查询有关用户的更多信息的身份 URL。请参阅身份 URL。 |
token_type
|
Bearer 令牌类型，用于包含访问令牌的所有响应。
|
issued_at
|
签名创建时间的时间戳，单位毫秒。 |
sidCookieName
|
混合应用程序用于直接桥接 Web 会话的会话 Cookie 的名称。默认值是 sid。 |
cookie-sid_Client
|
用于检测和防止会话欺诈的会话 Cookie。此会话 Cookie 允许混合应用程序直接桥接 Web 会话。 |
cookie-clientSrc
|
用于安全保护的会话 Cookie。此会话 Cookie 允许混合应用程序直接桥接 Web 会话。 |
令牌响应也可以包含这些参数。
