Generar una URL de puerta principal para unir en sesiones de la interfaz de usuario

Cómo funciona la API de puente de interfaz de usuario

Piense en el token de acceso de la sesión existente del usuario como una llave y la URL de la puerta principal como una puerta que protege el acceso a las interfaces de usuario de Salesforce. Con el token de acceso como clave, el usuario puede entrar directamente por la puerta en una interfaz de usuario de Salesforce con una nueva sesión.

Estos son algunos ejemplos de cómo puede utilizar esta función.

Si utiliza flujos de identidad desatendidos de Salesforce para una aplicación fuera de la plataforma, puede acortar sesiones de aplicaciones desatendidos en interfaces de usuario de Salesforce. Por ejemplo, aloja un sitio de comercio electrónico en una aplicación desatendida y sin plataforma que utiliza flujos de identidad desatendidos de Salesforce. También utiliza un sitio de Salesforce Experience Cloud para gestionar casos de asistencia al cliente. En su aplicación desatendida, desea mostrar un botón para cada uno de los casos de asistencia activos de un usuario de modo que pueda saltar a un caso específico y ver sus detalles. Para ver los detalles del caso, el usuario debe ir al sitio de Experience Cloud. En este punto, el usuario ya inició sesión en su aplicación desatendida, pero no tiene una sesión con el sitio de Experience Cloud aún.

En vez de hacer que el usuario vuelva a iniciar sesión cuando se le redirige, puede utilizar la API de puente de la interfaz de usuario. Envía el token de acceso del usuario desde su sesión de aplicación desatendida al extremo services/oauth2/singleaccess en su sitio de Experience Cloud. Para el URI de redireccionamiento, especifica una ruta que apunta al caso específico de Salesforce que el usuario solicita ver. API de puente de interfaz de usuario responde a esta solicitud con una URL de puerta principal. La aplicación desatendida redirige al usuario a la URL de la puerta principal, lo inicia automáticamente en la interfaz de usuario del sitio de Experience Cloud y lo redirige a su caso.

Otro caso de uso se inicia desde una sesión existente en una aplicación en un flujo de OAuth en una segunda aplicación. Por ejemplo, está utilizando un sitio de Experience Cloud como un proveedor de inicio de sesión único (SSO) para múltiples aplicaciones desatendidas y encabezadas. Desea unir una sesión iniciada en una aplicación desatendida a una aplicación encabezada. Envía el token de acceso desde la sesión desatendida a la API del puente de la interfaz de usuario, especificando la URL de autorización de la aplicación encabezada como su URI de redireccionamiento. Utiliza la URL de puerta principal resultante para cargar una nueva sesión en la aplicación encabezada. El usuario inicia sesión en el proveedor de SSO de Experience Cloud y se le redirige inmediatamente a la URL de autorización de la aplicación encabezada. La aplicación encabezada inicia a continuación un flujo de OAuth. Al final de este proceso, el usuario inicia sesión en ambas aplicaciones con una interrupción mínima.

Cómo utilizar la API de puente de la interfaz de usuario

Para obtener una URL de puerta principal, envíe una solicitud POST o GET al extremo services/oauth2/singleaccess. Este extremo solo admite las direcciones URL de Mi dominio y de sitios de Experience Cloud. No se admiten otras direcciones URL de inicio de sesión como login.salesforce.com y test.salesforce.com.

Incluya estos parámetros en la solicitud al extremo services/oauth2/singleaccess.

Este es un ejemplo que genera una URL de puerta principal que redirige a la página de gestión de usuarios de una organización en Configuración. Este ejemplo es una solicitud POST con el token de acceso en el cuerpo de la solicitud.

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

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

Este ejemplo también genera una URL de puerta principal que redirige a la página de gestión de usuarios de una organización, pero utiliza una solicitud GET. Por seguridad, las solicitudes GET deben enviar el token de acceso en un encabezado.

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

redirect_uri=lightning/setup/ManageUsers/home

Este ejemplo POST genera una URL de puerta principal que redirige a una página personalizada denominada mypage en un sitio de Experience Cloud. La ruta raíz del sitio de Experience Cloud incluye un sufijo, de modo que el URI de redireccionamiento también incluye este sufijo.

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

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

Nota Dependiendo del tipo de sitio de Experience Cloud y cuando se creó, algunas URL de sitio de Experience Cloud incluyen /s. Para obtener más información, consulte Rutas URL personalizadas en sitios LWR.

Si se realiza correctamente, la API devuelve una respuesta JSON con la URL de la puerta principal. Este es el aspecto de la respuesta si incluye redirect_uri, que se refleja en el valor startURL. Si no incluye redirect_uri, la URL de la puerta principal no incluye startURL.

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

La URL de la puerta principal de la respuesta es válida durante un máximo de 1 minuto desde que se devolvió y solo se puede utilizar una vez. Durante este periodo de tiempo, si envía la misma solicitud a la API de puente de la interfaz de usuario, devuelve exactamente la misma URL. Si realiza múltiples solicitudes, no amplía el tiempo de caducidad de esta URL. El extremo devuelve una nueva URL solo cuando la primera ha caducado.

Si no se realiza correctamente, la API devuelve un error. A continuación se incluye un mensaje de error de ejemplo.

Bad_OAuth_Token

A continuación se incluye una lista de errores y sugerencias para resolverlos.