生成前门 URL 桥接到 UI 会话中

UI 桥 API 的工作方式

将用户现有会话中的访问令牌视为密钥，将前门 URL 视为保护 Salesforce UI 访问权限的门。通过访问令牌作为密钥，用户可以使用全新的会话直接进入 Salesforce UI。

以下是一些如何使用此功能的示例。

如果您将 Salesforce 无头身份流用于平台外应用程序，您可以将无头应用程序会话桥接到 Salesforce UI 中。例如，您在使用 Salesforce 无头身份流的无头平台外应用程序上托管电子商务站点。您还可以使用 Salesforce Experience Cloud 站点来管理客户支持个案。在无头应用程序中，您想要为每个用户的活动支持个案显示按钮，以便他们可以跳转到特定个案并查看详细信息。要查看个案详细信息，用户必须转到 Experience Cloud 站点。此时，用户已经登录到您的无头应用程序，但尚未与 Experience Cloud 站点会话。

您可以使用 UI 桥 API，而不是让用户在重定向时再次登录。您可以将用户的访问令牌从无头应用程序会话发送到 Experience Cloud 站点上的services/oauth2/singleaccess端点。对于重定向 URI，您可以指定指向用户请求查看的特定 Salesforce 个案的路径。UI 桥 API 使用前门 URL 响应此请求。无头应用程序会将用户重定向到前门 URL，自动将其登录到 Experience Cloud 站点 UI，并将其重定向到个案。

另一个用例是从一个应用程序中的现有会话启动到另一个应用程序中的 OAuth 流。例如，您将 Experience Cloud 站点用作多个无头和有头应用程序的单点登录 (SSO) 提供商。您想要将无头应用程序中发起的会话桥接到有头应用程序中。您将访问令牌从无头会话发送到 UI 桥 API，并将标题应用程序的授权 URL 指定为重定向 URI。您可以使用生成的前门 URL 在标题应用程序中加载新会话。用户登录 Experience Cloud SSO 提供商，并立即重定向到标题应用程序的授权 URL。然后，标题应用程序开始 OAuth 流。在此过程结束时，用户以最小的中断登录到这两个应用程序。

如何使用 UI 桥 API

要获取前门 URL，请向 services/oauth2/singleaccess 端点发送 POST 或 GET 请求。此端点仅支持 My Domain 和 Experience Cloud 站点 URL。不支持其他登录 URL，例如 login.salesforce.com 和 test.salesforce.com。

在向 services/oauth2/Singleaccess 端点的请求中包含这些参数。

以下示例会生成前门 URL，该 URL 会重定向到组织的用户管理页面。此示例是请求正文中包含访问令牌的 POST 请求。

POST /services/oauth2/singleaccess? HTTP 1.1
Host: mydomainname.my.salesforce.com

access_token=**************&
redirect_uri=lightning/setup/ManageUsers/home

此示例还生成重定向到组织用户管理页面的前门 URL，但它使用 GET 请求。为了安全起见，GET 请求必须在标题中发送访问令牌。

GET /services/oauth2/singleaccess? HTTP 1.1
Host: mydomainname.my.salesforce.com
Authorization: Bearer <access token>

redirect_uri=lightning/setup/ManageUsers/home

此 POST 示例会生成前门 URL，该 URL 会重定向到 Experience Cloud 站点中名为 mypage 的自定义页面。Experience Cloud 站点的根路径包含后缀，因此重定向 URI 也包含此后缀。

POST /services/oauth2/singleaccess? HTTP 1.1
Host: myexperiencecloudsite.com/mysitename

access_token=**************&
redirect_uri=mysitename/mypage

备注 根据 Experience Cloud 站点的类型及其创建时间，一些 Experience Cloud 站点 URL 包含 /s。有关更多信息，请查看 LWR 站点中自定义 URL 路径。

如果成功，API 会返回带有前门 URL 的 JSON 响应。如果您包含redirect_uri，以下是响应的外观，这反映在startURL值中。如果您不包含redirect_uri，前门 URL 不会包含startURL。

{
"frontdoor_uri": "https://mydomainname.my.salesforce.com/secur/frontdoor.jsp?otp=*****&startURL=lightning%2Fsetup%2FManageUsers%2Fhome&cshc=x000001X7tNx0000006GpL"
}

响应中的前门 URL 在返回后的 1 分钟内有效，并且只能使用一次。在此期间，如果您向 UI 桥 API 发送相同的请求，它将返回完全相同的 URL。如果您多次请求，不会延长此 URL 的到期时间。端点仅在第一个 URL 过期时返回新 URL。

如果不成功，API 会返回错误。以下是示例错误响应。

Bad_OAuth_Token

以下是错误列表和解决建议。