面向 Web 应用程序集成的 OAuth 2.0 Web 服务器流
要将外部 Web 应用程序与 Salesforce API 集成，请使用 OAuth 2.0 Web 服务器流，它实施OAuth 2.0 授权代码授权类型。通过此流，托管 Web 应用程序的服务器必须能够保护由客户端 ID 和客户端密码定义的外部客户端应用程序的身份。
所需的 Edition
| 适用于：Salesforce Classic（并非在所有组织中可用）和 Lightning Experience |
| 在所有版本中可用 |
我们建议您使用带有适用于代码交换的证明密钥（PKCE，发音 pixy）的 Web 服务器流，以代替特殊场景的用户-客服人员流或用户名-密码流。使用 code_challenge 和 code_verifier 参数，通过 Web 服务器流实施 PKCE。有关 PKCE 的更多信息，请参见互联网工程任务组 (IETF)。我们还建议您阻止所有外部客户端应用程序使用用户代理流或用户名密码流。有关步骤，请参见阻止授权流以提高安全性。
以下是实施 Web 服务器流的用例示例。您最近开发了一个允许安全访问客户订单状态的 Web 服务。订单状态数据安全地存储在您的 Salesforce CRM 平台中。要授权帮助台用户查看客户的订单状态，您需要开发订单状态应用程序，并将其配置为具有 Web 服务器流的外部客户端应用程序。
- 帮助台用户单击订单状态 Web 应用程序。
- 外部客户端应用程序向 Salesforce 授权端点发布授权代码请求。
- 用户将被重定向到 Salesforce 登录页面。成功登录后，要求用户批准应用程序对订单状态数据的访问。
- 用户批准订单状态应用程序访问数据后，Salesforce 会向订单状态应用程序发送带有授权代码的回拨。
- 订单状态应用程序将授权代码传递给 Salesforce 标记端点，请求访问标记。
- Salesforce 验证授权代码并以范围的形式发回包含相关权限的访问标记。
- 订单状态应用程序向 Salesforce 发送请求，以访问订单状态数据。该请求包括具有相关范围的访问标记。
- Salesforce 验证访问标记和相关范围。
- 订单状态应用程序可以访问受保护的数据，客户的订单状态显示在应用程序中。
备注 如果访问令牌无效，外部客户端应用程序可以使用刷新令牌来获取新的访问令牌。
让我们仔细看看这个授权流的每个步骤。
请求授权代码
为了启动 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
|
外部客户端应用程序的使用者密钥。要访问使用者密钥，从应用程序管理器中，查找外部客户端应用程序，并从下拉列表中选择查看。然后，单击管理客户详细信息。在查看使用者密钥之前，有时会提示您验证您的身份。 |
redirect_uri
|
成功身份验证后用户重定向的 URL。重定向 URI 必须匹配外部客户端应用程序的回调 URL 字段中的一个值。否则，批准失败。您可以在外部客户端应用程序的 OAuth 设置页面上找到重定向 URI。该值必须是编码 URL。 |
response_type
|
外部客户端应用程序请求的 OAuth 2.0 授权类型。此流的值必须是 code，以表示外部客户端应用程序正在请求授权代码。 |
您也可以在授权代码请求中包含这些参数。
| 参数 | 描述 |
|---|---|
scope
|
定义外部客户端应用程序可以访问的受保护资源类型的权限。在构建外部客户端应用程序时，您可为其分配范围，并在授权流期间包含在 OAuth 令牌中。 如果您不包含此参数，则会请求分配给外部客户端应用程序的所有范围。此参数中传递的范围必须是已注册范围的子集。有关有效参数，请参阅OAuth 令牌和范围。 |
sso_provider
|
为 My Domain 登录 URL 或 Experience Cloud 站点 URL 配置的单点登录 (SSO) 身份提供商的开发人员姓名。您可以使用此参数来创建一种 SSO 体验，感觉您的应用程序与 SSO 提供商集成在一起。例如，您可以使用此参数在无头身份实施中提供 SSO。有关更多信息，请参见在应用程序中创建本地单点登录体验。 |
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=authorization_code&
code=aPrxhgZ2MIpkSy0aOdn07LjKFvsFOis6RGcWXz7p8JQCjcqfed5NQLe7sxWwMY_JQFuLwHRaRA==&
client_id=3MVG9IHf89I1t8hrvswazsWedXWY0iqK20PSFaInvUgLFB6vrcb9bbWFTSIHpO8G2jxBLJA6uZGyPFC5Aejq&
client_secret=*******************&
redirect_uri=https://www.mycustomerorderstatus.com/oauth2/callback
示例中的 POST 包含以下参数。
| 参数 | 描述 |
|---|---|
Request Header
|
请求页眉可以包含以下参数。
请求页眉还支持以下参数。
|
grant_type
|
外部客户端应用程序可以提供的验证类型，以证明它是安全的访问者。对于 Web 服务器流，值必须是 authorization_code。 |
code
|
从授权服务器接收的临时授权代码。外部客户端应用程序使用此代码交换访问令牌。这种 OAuth 2.0 流是将访问标记传递回应用程序的安全方式。 |
client_id
|
外部客户端应用程序的使用者密钥。要访问使用者密钥，从应用程序管理器中，查找外部客户端应用程序，并从下拉列表中选择查看。然后，单击管理客户详细信息。在查看消费者密钥之前，有时会提示您验证您的身份。 |
client_secret
|
外部客户端应用程序的使用者密码。要访问使用者密码，从应用程序管理器中，查找外部客户端应用程序，并从下拉列表中选择查看。然后，单击管理客户详细信息。在查看使用者密码之前，有时会提示您验证您的身份。 此参数是必填项，除非外部客户端应用程序未启用需要 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=authorization_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 令牌和范围。 |
id_token
|
一种签名数据结构，包含经过身份验证的用户属性，包括用户的唯一标识符和指示标记发放时间的时间戳。此外，也会识别请求的客户端应用程序。请参见 OpenID Connect 规格。 如果范围参数包含 |
instance_url
|
指示用户的组织实例的 URL。例如：https://yourInstance.salesforce.com/.
|
id
|
可用于标识用户以及查询有关用户的更多信息的身份 URL。请参阅身份 URL。 |
token_type
|
Bearer 令牌类型，用于包含访问令牌的所有响应。
|
issued_at
|
签名创建时间的时间戳，单位毫秒。 |
响应也可以包含这些参数。
| 参数 | 描述 |
|---|---|
refresh_token
|
|
sfdc_site_url
|
如果用户是 Experience Cloud 站点的成员，则提供站点 URL。 |
sfdc_site_id
|
如果用户是 Experience Cloud 站点的成员，则提供用户的站点 ID。 |
state
|
客户端请求的状态。仅当原始查询字符串中包含 state 参数时，才会包含此值。
|
