无头身份 API：专用客户端的无头来宾流

未知最终用户到达您的应用程序

该流将在最终用户访问您的应用程序时启动。您还可以将其配置为在用户执行某个操作时启动，例如将商品保存到购物车。

应用程序会在必要时请求 UVID

应用程序尝试从之前对该应用程序的访问中找到 UVID。例如，它确定是否可以从 Cookie 或浏览器的本地存储中提取 UVID。如果应用程序找不到 UVID，它会从其客户端后端请求一个。

客户端后端生成 UVID

提出请求后，客户端后端会生成 UVID 值。Salesforce 不参与生成、存储或维护 UVID。完全取决于您的应用程序。唯一的要求是 UVID 必须是版本 4 通用唯一标识符 (v4 UUID)。

应用程序接收 UVID

应用程序从客户端后端接收 UVID。

应用程序生成 PKCE 参数

如果您正在使用 PKCE，应用程序会生成code_verifier和code_challenge参数。

RFC 7636 中定义的 PKCE 规范还包括您可以在授权请求中发送的可选code_challenge_method参数。Salesforce 忽略您在此参数中发送的任何值，并默认设置为 SHA256。

应用程序将 UVID 交换为授权代码

应用程序向 Experience Cloud 站点上的 Salesforce 授权端点无头发送 GET 或 POST 请求。该请求包含 UVID 和其他参数，用于识别应用程序和指定请求的类型。

您有两个选项选择如何在此请求中发送 UVID。您可以发送普通的 UVID 值，或者发送带有 UVID 的基于 JWT 的访问令牌。例如，如果您在以前的会话中有一个基于 JWT 的访问令牌，那么将该令牌发送到授权端点是重用它的一种简单方法，而不需要专门为 UVID 解析它。

在您的请求中包括这些标题。

在请求正文中包含这些参数。

这些示例授权请求全部实施 PKCE。

下面是一个请求示例，其中 UVID 作为请求标题中的普通值传递。

POST /services/oauth2/authorize? HTTP 1.1
Host: MyExperienceCloudSite.my.site.com
Uvid-Hint: UVID abcd-1234-efgh
Auth-Request-Type: guest

response_type=code_credentials&
client_id=***********&
redirect_uri=https://www.MyExperienceCloudSite.my.site.com/services/oauth2/echo&
code_challenge=********&
scope=openid

下面是一个请求示例，其中 UVID 在标题的基于 JWT 的访问令牌中传递。

POST /services/oauth2/authorize? HTTP 1.1
Host: MyExperienceCloudSite.my.site.com
Uvid-Hint: JWT **************
Auth-Request-Type: guest

response_type=code_credentials&
client_id=***********&
redirect_uri=https://www.MyDomainName.my.site.com/services/apexrest/code/exchange&
code_challenge=********
scope=openid

在此示例中，UVID 在请求正文中作为普通值传递。

POST /services/oauth2/authorize? HTTP 1.1
Host: MyExperienceCloudSite.my.site.com
Auth-Request-Type: guest

uvid_hint=UVID abcd-1234-efgh&
response_type=code_credentials&
client_id=***********&
redirect_uri=https://www.MyDomainName.my.site.com/services/apexrest/code/exchange&
code_challenge=********
scope=openid

Salesforce 返回 302 重定向

Salesforce 验证 UVID。如果 UVID 作为普通值传递，Salesforce 会验证其格式。如果它作为基于 JWT 的访问令牌传递，Salesforce 将检查令牌的有效性。

然后，Salesforce 将 HTTP 302 重定向返回到包含授权代码的预配置 URL。如果流在浏览器中发生，302 重定向将在浏览器中处理，Salesforce 会自动将重定向响应发送到重定向 URL，该 URL 指向客户端后端的服务器端回调处理器。这是一个预配置 URL 的例子。

https://www.MyDomainName.my.site.com/services/apexrest/code/exchange?code=aPrxC1*******
&sfdc_community_url=https%3A%2F%2FMyDomainName.my.site.com&sfdc_community_id=0DBxxxxxxxxxxxx

客户端后端提取代码并将其交换为访问令牌

客户端后端从预配置的 URL 中提取授权码和其他参数。然后，它通过向/services/oauth2/token端点发送无头 POST 请求中的代码和其他参数来启动代码交换。

在请求中包括这些标题。

在请求正文中包含这些参数。

以下是实施 PKCE 的示例令牌请求。在此示例中，UVID 被作为普通值发送。

POST services/oauth2/token? HTTP 1.1
Host: MyExperienceCloudSite.my.site.com
Auth-Request-Type: guest
Uvid_Hint: abcd-1234-efgh

code=********&
client_id=**********&
client_secret=*********&
redirect_uri=https://www.MyDomainName.my.site.com/services/apexrest/code/exchange&
grant_type=authorization_code&
code_verifier=*******

Salesforce 授予基于 JWT 的访问令牌

验证应用程序的凭据后。Salesforce 向客户端后端返回基于 JWT 的来宾访问令牌和状态。来宾访问令牌在主题 (sub) 声明中包含 UVID。以下是基于 JWT 的访问令牌的示例片段。提醒一下，这些令牌有三个组成部分：标题、有效负载和签名。此示例向您显示有效负载。如您所见,sub 声明中的 UVID 值以 uvid 为前缀。

{
  "tnk": "example/00XXXXXX",
  "ver": "1.0",
  "kid": "CORE_ATJWT************",
  "tty": "sfdc-core-token",
  "typ": "JWT",
  "alg": "RS256"
}

{
  "scp": "open_id",
  "aud": [
    "https://example.com"
  ],
  "sub": "uvid:abcd-1234-efgh",
  "nbf": "1675197036",
  "iss": "https://MyExperienceCloudSite.my.site.com",
  "exp": "1675198836",
  "iat": "1675197036",
   jti”: xRb**********”
  "client_id": "**********"
}

有关基于 JWT 的访问令牌中每个声明的完整解释，请参阅 Salesforce 帮助中的基于 JWT 的访问令牌。

客户端后端处理访问令牌响应

客户端后端处理访问令牌响应并存储 UVID 值。它会向应用程序返回来宾会话。它还可以返回基于 JWT 的访问令牌，但这不是必需的。

应用程序创建来宾会话

应用程序从其客户端后端接收令牌响应，并创建来宾会话。

现在识别出未知用户

未知最终用户现在有一个与基于 JWT 的访问令牌中返回的 UVID 值相关联的来宾会话。此时，您可自行决定如何处理 UVID。要了解如何将其传递到命名用户授权流，请参见将来宾用户流扩展到命名用户流。