API de identidad desatendida: Flujo de invitados desatendido para clientes privados
Para usuarios que interactúan con su aplicación de plataforma sin conexión pero no tienen necesariamente iniciada la sesión, puede utilizar el Flujo de invitados desatendido para identificar usuarios con un Id. de visitante exclusivo (UVID). Cuando el usuario inicia sesión o se registra, puede trasladar el UVID y mantener cualquier información contextual asociada con ella, como las preferencias de un usuario. Este flujo es una variación del flujo Código de autorización y credenciales.
Ediciones necesarias
| Disponible en: Salesforce Classic (no disponible en todas las organizaciones) y Lightning Experience |
| Disponible en: Enterprise Edition, Unlimited Edition y Developer Edition |
Antes de configurar este flujo, complete estos pasos.
- Completar los requisitos previos para Identidad desatendida
- Integre su aplicación fuera de la plataforma con Salesforce utilizando una de estas opciones. Asegúrese de configurar políticas adicionales para el flujo de invitados.
Por ejemplo, aloja una aplicación de comercio electrónico fuera de la plataforma Salesforce. Desea que los usuarios puedan guardar artículos en un carrito sin iniciar sesión. Puede utilizar el flujo de usuario invitado para generar un UVID para el usuario, y puede almacenar la información del carrito del usuario y vincularla al UVID. Cuando el usuario inicia sesión o se registra por última vez, pasa el UVID en un flujo de registro o inicio de sesión desatendido. Debido a que tiene el contexto del carrito desde UVID, puede guardar los artículos del usuario, dándole una mejor experiencia.
El ejemplo de carrito de compra es solo una de muchas posibilidades cuando se incluye el UVID y el flujo de invitado. Otras posibilidades incluyen comprender lo que hace que sus usuarios deseen inscribirse en su aplicación y recordar sus preferencias.
El flujo de invitado y UVID solo son compatibles con tokens de acceso basados en tokens Web de JSON (JWT). Para conectar el UVID a un usuario nombrado, debe configurar el flujo de usuario nombrado para emitir tokens de acceso basados en JWT también.
Estas instrucciones le indican cómo implementar el flujo para un cliente privado con su propio backend. Los clientes privados tienen un lugar seguro para almacenar el secreto de consumidor de su aplicación, que funciona como una contraseña para el intercambio de códigos, de modo que recomendamos enviar el secreto de consumidor cuando solicite un token de acceso.
También recomendamos que proteja aún más su flujo implementando la extensión OAuth 2.0 Proof Key for Code Exchange (PKCE). PKCE ayuda a garantizar que el cliente que inicia el flujo es el mismo cliente que lo completa. Para obtener más información acerca de cómo funciona PKCE y cómo puede aplicarlo, consulte Construir la extensión PKCE en sus implementaciones.
Esta es una descripción general del flujo de invitados. Estos pasos cubren el flujo hasta el punto en que se identifica el usuario invitado, pero no se inicia sesión.
- El visitante desconocido llega a la aplicación, o realiza una acción como hacer clic en un botón (1).
- La aplicación busca un UVID. Si no puede encontrar uno, solicita un UVID de su backend cliente (2).
- Si se solicita, el backend cliente genera un UVID y lo envía a su aplicación (3).
- Su aplicación recibe el UVID (4a).
- Si está utilizando PKCE, su aplicación genera parámetros de PKCE (4b).
- Para obtener un código de autorización, su aplicación envía el UVID en una solicitud GET o POST sin encabezado al extremo de autorización (
services/oauth2/authorize) (5). - Salesforce valida el UVID y devuelve un redireccionamiento 302 a una URL preconfigurada que contiene el código de autorización (6).
- El backend de cliente de su aplicación extrae el código y otros parámetros del redireccionamiento 302 e intercambia el código de un token de acceso con una solicitud en el extremo de tokens de Salesforce (
services/oauth2/token) (7). - Salesforce devuelve un token de acceso basado en JWT de invitado con el UVID en la reclamación de sujeto (8).
- El backend de cliente de su aplicación procesa el token de acceso basado en JWT de invitados y almacena el valor de UVID, que puede mantenerse privado. Devuelve una sesión de invitado y, opcionalmente, el token de invitado (9).
- Su aplicación recibe la respuesta del token y crea la sesión de invitado (10).
- El visitante no conocido anteriormente tiene ahora una sesión de invitado vinculada al valor de UVID en el token de acceso (11).
Como se menciona en el paso 7 para un cliente privado, usted crea un controlador de devolución de llamadas del lado del servidor que puede extraer el redireccionamiento 302 y devolver un código de autorización a su aplicación. Para ver cómo puede crear este controlador, consulte Flujo Código de autorización y credenciales para clientes privados, que incluye un controlador de Apex de ejemplo expuesto como un recurso de REST.
El usuario final desconocido llega a su aplicación
El flujo se inicia cuando un usuario final visita su aplicación. También puede configurarlo para que se inicie cuando el usuario realice una acción, como por ejemplo, guardar un artículo en un carrito.
La aplicación solicita un UVID si es necesario
Su aplicación intenta encontrar un UVID de visitas anteriores a la aplicación. Por ejemplo, determina si puede extraer el UVID desde una cookie o desde almacenamiento local en el navegador. Si la aplicación no puede encontrar un UVID, solicita uno desde su backend cliente.
El backend cliente genera un UVID
Si se solicita, el backend cliente genera un valor de UVID. Salesforce no está implicado en la generación, el almacenamiento o el mantenimiento de UVID. Depende completamente de su aplicación. El único requisito es que el UVID debe ser un identificador exclusivo universal de Versión 4 (v4 UUID).
La aplicación recibe el UVID
Su aplicación recibe el UVID desde el backend de cliente.
La aplicación genera parámetros de PKCE
Si está utilizando PKCE, su aplicación genera parámetros de code_verifier y code_challenge.
La especificación de la extensión PKCE definida en RFC 7636 también incluye un parámetro code_challenge_method opcional que puede enviar en la solicitud de autorización. Salesforce no tendrá en cuenta cualquier valor que se envíe en este parámetro, y establecerá SHA256 de forma predeterminada.
La aplicación intercambia el UVID para un código de autorización
Su aplicación envía de forma desatendida una solicitud GET o POST al extremo de autorización de Salesforce en su sitio de Experience Cloud. La solicitud contiene el UVID y otros parámetros para identificar la aplicación y especificar el tipo de solicitud.
Tiene dos opciones para el modo en que envía el UVID en esta solicitud. Puede enviar un valor de UVID sin formato o enviar un token de acceso basado en JWT con el UVID acuñado en él. Por ejemplo, si tiene un token de acceso basado en JWT desde una sesión anterior, el envío del token al extremo de autorización es una forma sencilla de reutilizarlo sin analizarlo de forma específica para el UVID.
Incluya estos encabezados en su solicitud.
| Encabezado | ¿Obligatorio? | Descripción |
|---|---|---|
Uvid-Hint
|
Obligatorio si no envía el UVID en el cuerpo de la solicitud. Debe incluir siempre un UVID, ya sea que se envíe en el encabezado o en el cuerpo de la solicitud. | Contiene el UVID como un valor sin formato o un token de acceso basado en JWT con un UVID acuñado en él. Si envía el identificador UVID como un valor sin formato, incluya un prefijo Si envía un token de acceso basado en JWT con un identificador UVID, incluya un prefijo |
Auth-Request-Type
|
Sí. | Especifica el tipo de solicitud que desea realizar a Salesforce. Para el inicio de sesión sin contraseña desatendido, este valor debe establecerse en guest. |
Incluya estos parámetros en el cuerpo de la solicitud.
| Parámetro | ¿Obligatorio? | Descripción |
|---|---|---|
uvid_hint
|
Obligatorio si no incluye el UVID en el encabezado. | Contiene el UVID como un valor sin formato o un token de acceso basado en JWT con un UVID acuñado en él. Si envía el identificador UVID como un valor sin formato, incluya un prefijo Si envía un token de acceso basado en JWT con un identificador UVID, incluya un prefijo |
client_id
|
Sí. | La clave de consumidor de la aplicación cliente externa o la aplicación conectada. |
response_type
|
Sí. | El tipo de otorgamiento de OAuth 2.0 que solicita su aplicación. Como este flujo es una variación del flujo Código de autorización y credenciales, este valor debe ser code_credentials. |
redirect_uri
|
Sí. | La URL donde se redirige a los usuarios después de una autenticación satisfactoria. Para clientes privados, utilice un |
code_challenge
|
Solo si está utilizando la extensión PKCE, que es lo recomendable, especialmente para un cliente público. | Especifica el valor de hash SHA256 del valor Si se proporciona un desafío Si el desafío |
scope
|
Sí. | Los permisos que definen el tipo de recursos protegidos a los que la aplicación puede acceder. Los valores que envía en esta solicitud deben coincidir o ser un subconjunto de los ámbitos asignados a su aplicación cliente externa o aplicación conectada. Para obtener más información acerca de cada ámbito y su finalidad, consulte Tokens y ámbitos de OAuth. |
Estas solicitudes de autorización de ejemplo implementan PKCE.
A continuación se incluye un ejemplo de solicitud donde el UVID se pasa como un valor sin formato en el encabezado de la solicitud.
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
A continuación se incluye un ejemplo de solicitud donde el UVID se pasa en un token de acceso basado en JWT en el encabezado.
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
En este ejemplo, el UVID se pasa como un valor sin formato en el cuerpo de la solicitud.
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 devuelve un redireccionamiento 302
Salesforce valida el UVID. Si se pasó el UVID como un valor sin formato, Salesforce valida su formato. Si se pasó como un token de acceso basado en JWT, Salesforce comprueba la validez del token.
Salesforce devuelve entonces un redireccionamiento HTTP 302 a una URL preconfigurada que contiene el código de autorización. Si el flujo se produce en el navegador, el redireccionamiento 302 se procesa en el navegador y Salesforce envía automáticamente la respuesta de redireccionamiento a la URL de redireccionamiento, que apunta al controlador de devolución de llamadas del lado del servidor en el backend del cliente. Esta es una URL preconfigurada de ejemplo.
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=0DBxxxxxxxxxxxxEl backend de cliente extrae el código y lo intercambia por un token de acceso
El backend de cliente extrae el código de autorización y otros parámetros desde la URL preconfigurada. A continuación inicia un intercambio de códigos enviando el código y otros parámetros en una solicitud POST desatendida al extremo /services/oauth2/token.
Incluya estos encabezados en la solicitud.
| Parámetro | ¿Obligatorio? | Descripción |
|---|---|---|
Uvid-Hint
|
Sí. | Contiene el UVID como un valor sin formato o un token de acceso basado en JWT con un UVID acuñado en él. Para el intercambio de códigos, no incluya un prefijo para el UVID. Por ejemplo, si pasa el UVID como un valor sin formato, el encabezado es simplemente |
Auth-Request-Type
|
Sí. | Especifica el tipo de solicitud que desea realizar a Salesforce. Para el inicio de sesión sin contraseña desatendido, este valor debe establecerse en guest. |
Incluya estos parámetros en el cuerpo de la solicitud.
| Parámetro | ¿Obligatorio? | Descripción |
|---|---|---|
code
|
Sí. | El servidor de autorización crea un código de autorización, que es un token efímero que pasa al cliente después de una autenticación correcta. El cliente envía el código de autorización al servidor de autorización para obtener un token de acceso y, opcionalmente, un token de actualización. |
client_id
|
Sí. | La clave de consumidor de la aplicación cliente externa o la aplicación conectada. |
client_secret
|
Sí. | El secreto de consumidor de la aplicación cliente externa o la aplicación cliente externa. |
redirect_uri
|
Sí. | La URL donde se redirige a los usuarios después de una autenticación satisfactoria. redirect_URI debe coincidir con uno de los valores del campo URL de devolución de llamada de la aplicación conectada. De lo contrario, la aprobación falla. Este valor debe tener codificación de URL. Para clientes privados, utilice un |
grant_type
|
Sí. | El tipo de validación que la aplicación puede proporcionar para probar que es un visitante seguro. Como este flujo es una variación del flujo Código de autorización y credenciales, el valor debe ser authorization_code. |
code_verifier
|
Solo si está utilizando PKCE. | Especifica 128 bytes de datos aleatorios con alta entropía para hacer que intentar determinar el valor del código sea difícil. Establezca este parámetro para ayudar a evitar ataques de intercepción de códigos de autorización. El valor debe ser base64url-encoded (codificado con base64url) como se define en https://datatracker.ietf.org/doc/html/rfc4648#section-5. Si existe un valor de verificador Si el valor de verificador |
A continuación se incluye un ejemplo de solicitud de token que implementa PKCE. En este ejemplo, el UVID se envía como un valor sin formato.
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 otorga un token de acceso basado en JWT
Después de validar las credenciales de la aplicación. Salesforce devuelve un token de acceso basado en JWT de invitado y un estado al backend del cliente. El token de acceso de invitado contiene el UVID en la reclamación (sub) del sujeto. Este es un fragmento de código de un token de acceso basado en JWT de ejemplo. Como recordatorio, estos tokens tienen tres componentes: un encabezado, una carga, y una firma. Este ejemplo muestra la carga. Como puede observarse, el valor UVID de la reclamación sub tiene el prefijo 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": "**********"
}Para obtener una explicación completa de cada reclamación en un token de acceso basado en JWT, consulte Tokens de acceso basados en JWT en la Ayuda de Salesforce.
Respuesta de token de acceso de procesos de backend de cliente
El backend de cliente procesa la respuesta del token de acceso y almacena el valor UVID. Devuelve una sesión de invitado a su aplicación. También puede devolver el token de acceso basado en JWT, pero no es obligatorio.
La aplicación crea la sesión de invitado
Su aplicación recibe la respuesta del token de su backend de cliente y crea una sesión de invitado.
El usuario desconocido está ahora identificado
El usuario final desconocido ahora tiene una sesión de invitado vinculada al valor de UVID devuelto en el token de acceso basado en JWT. En este punto, depende de usted lo que desee hacer con el UVID. Para obtener información acerca de cómo pasarlo a un flujo de autorización de usuario nombrado, consulte Ampliación del flujo de usuario invitado en un flujo de usuario nombrado.
