OAuth 2.0 para aplicaciones de primera parte: Inicio de sesión sin contraseña desatendido para clientes privados
Con el inicio de sesión sin contraseña desatendido, los usuarios inician sesión en su aplicación fuera de la plataforma a través de su dirección de email o número de teléfono y una contraseña simultánea. Para configurar el inicio de sesión sin contraseña para una aplicación sin plataforma desarrollada por su compañía, utilice este flujo de inicio de sesión sin contraseña desatendido, que implementa el protocolo borrador de OAuth 2.0 para aplicaciones de primera parte. Con este flujo, puede controlar completamente la experiencia de inicio de sesión de front-end en su aplicación de primera parte mientras Salesforce controla el trabajo de backend de autenticación de usuarios y otorgamiento de acceso a recursos protegidos. Este flujo solo se admite para clientes privados, como aplicaciones cliente-servidor, y solo se admite para usuarios externos.
Ediciones necesarias
| Disponible en: Salesforce Classic y Lightning Experience |
| Disponible en: Enterprise Edition, Unlimited Edition y Developer Edition |
Para configurar el inicio de sesión sin contraseña desatendido para un cliente privado, también puede utilizar la variación de inicio de sesión sin contraseña del flujo Código de autorización y credenciales, que implementa las API de identidad desatendida. Ambos flujos realizan el mismo caso de uso: inicio de sesión sin contraseña desatendido para una aplicación fuera de Salesforce Platform. Pero hay algunas diferencias clave a tener en cuenta.
| OAuth para aplicaciones propias | API de identidad desatendida |
|---|---|
| Admitido solo para clientes privados. | Admitido para clientes públicos y privados. |
| Se ajusta al proyecto de protocolo de OAuth 2.0 para aplicaciones de primera parte. | Flujo de Salesforce patentado que está construido sobre el estándar de OAuth 2.0. |
| Solo se admite para el marco de trabajo de la aplicación cliente externa Salesforce. Del mismo modo, la única forma de configurar parámetros de aplicación cliente externa para este flujo es a través de la API de metadatos. | Compatible con la aplicación cliente externa Salesforce y los marcos de trabajo de aplicaciones conectadas. |
| Por seguridad, este flujo siempre requiere un JWT de certificado de cliente. Salesforce utiliza el JWT de certificado de cliente para validar que la aplicación fue desarrollada por su compañía. | Por seguridad, requiere autenticación o reCAPTCHA, pero no un JWT de certificado de cliente. |
Antes de configurar este flujo, complete estos pasos.
- Complete los requisitos previos para Identidad desatendida.
- Generar un JWT de certificación de cliente.
- Configure una aplicación cliente externa de Salesforce.
- Configure ajustes de Experience Cloud.
De forma predeterminada, los usuarios ingresan su nombre de usuario para iniciar sesión. Para proporcionar a los usuarios más opciones, configure el descubrimiento de usuarios desatendidos. Por ejemplo, desarrolle un flujo donde los usuarios ingresen su dirección de email, número de teléfono o incluso un número de pedido. Consulte Inicio de sesión desatendido sin un nombre de usuario.
A continuación se muestra una descripción general del funcionamiento del flujo.
- Paso 1: Un usuario final va a su aplicación de primera parte e ingresa su dirección de email o número de teléfono. O bien, si está utilizando el descubrimiento de usuarios desatendidos, ingresan un identificador como una dirección de email, un número de teléfono o un número de pedido, junto con su contraseña.
- Paso 2: Su aplicación encuentra el nombre de usuario asociado con el número de teléfono o la dirección de email del usuario.
- Paso 3: Su aplicación acuña un JWT de certificado de cliente. También genera parámetros Clave de prueba para intercambio de códigos (PKCE).
- Paso 4: Su aplicación de primera parte envía una solicitud POST desatendida al extremo services/oauth2/v1/authorization_challenge en su sitio de Experience Cloud. La solicitud incluye el JWT de certificado de cliente del usuario y la información que el usuario envió, junto con otros parámetros.
- Paso 5: Para confirmar que su aplicación externa envió la solicitud, Salesforce valida el JWT de certificado de cliente y luego valida los otros parámetros en la solicitud. Si la solicitud se realiza correctamente, Salesforce devuelve una respuesta de error con
auth_session, pero la respuesta indica que Salesforce envió una OTP al usuario. - (Opcional) Si está utilizando descubrimiento de usuarios desatendidos, su controlador Apex encuentra al usuario basándose en el identificador que utilizó para iniciar sesión. Si las credenciales de usuario son válidas y el usuario tiene una dirección de email o un número de teléfono verificados, el inicio de sesión continúa.
- Paso 6: Salesforce envía una OTP a la dirección de email o el número de teléfono del usuario.
- Paso 7: Su aplicación muestra de forma nativa un formulario de verificación.
- Paso 8: El usuario ingresa su OTP en el formulario de verificación.
- Paso 9: Su aplicación envía otra solicitud POST al extremo services/oauth2/v1/authorization_challenge, esta vez para solicitar un código de autorización. Esta solicitud incluye
auth_sessiondevuelta desde la primera solicitud junto con la OTP que ingresó el usuario. - Paso 10: Salesforce verifica la solicitud, devuelve el código de autorización y finaliza el
auth_session. - Paso 11: Para intercambiar el código por un token de acceso, su aplicación de primera parte envía una solicitud al extremo /services/oauth2/token.
- Paso 12: Salesforce devuelve una respuesta de token que contiene el token de acceso.
- Paso 13: Su aplicación de primera parte procesa la respuesta del token y crea la sesión del usuario.
- Paso 14: El usuario final ahora inició sesión y realiza una acción en su aplicación que requiere acceso a un recurso de Salesforce protegido.
- Paso 15: Su aplicación de primera parte realiza una llamada autenticada a una API de Salesforce.
- Paso 16: El usuario ahora puede acceder a sus datos de Salesforce en su aplicación de primera parte.
Paso 1: El usuario final ingresa su dirección de email o número de teléfono para iniciar sesión
Un usuario final visita su aplicación de primera parte. Su aplicación muestra de forma nativa un formulario de inicio de sesión que solo solicita la dirección de email o el número de teléfono del usuario. El usuario ingresa su dirección de email o número de teléfono en el formulario.
Paso 2: La aplicación de primera parte encuentra el nombre de usuario
Su aplicación encuentra el nombre de usuario asociado con el número de teléfono o dirección de email del usuario.
Paso 3: La aplicación de primera parte acuña un JWT de certificado de cliente y genera valores de code_verifier y code_challenge para PKCE
La aplicación acuña un JWT de certificado de cliente.
La aplicación también genera valores para los parámetros PKCE utilizados para verificar el código de autorización.
Para obtener más información sobre PKCE, consulte la especificación RFC 7636: Clave de prueba para el intercambio de códigos por clientes públicos de OAuth proporcionado por Internet Engineering Task Force (IETF).
La especificació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 ignora cualquier valor que envíe en este parámetro y establece de forma predeterminada SHA256.
Paso 4: La aplicación envía una solicitud inicial al extremo de reto de autorización
Para inicializar el inicio de sesión sin contraseña, su aplicación envía las credenciales del usuario, junto con otros parámetros, al extremo services/oauth2/v1/authorization_challenge en su sitio de Experience Cloud a través de una solicitud POST desatendida.
No hay encabezados obligatorios para esta solicitud. Opcionalmente, para conectar este flujo con el flujo de invitados desatendido, puede incluir un encabezado Uvid-Hint con un token de acceso basado en JWT que contiene un valor de Id. de visitante exclusivo (UVID).
| Encabezado | ¿Obligatorio? | Descripción |
|---|---|---|
Uvid-Hint
|
No. Si implementa el flujo de usuarios invitados en su aplicación, puede opcionalmente utilizar este encabezado para pasar en un token de acceso basado en JWT que contenga un UVID vinculado a la identidad de un usuario invitado. Al pasar el En lugar de pasar un token basado en JWT con |
Un token de acceso basado en JWT que contiene un valor UVID, que es un identificador exclusivo universal (UUID) de Versión 4 que su aplicación genera y gestiona completamente. Para obtener un token de acceso con UVID, debe activar su aplicación cliente externa o aplicación conectada para emitir tokens de acceso basados en JWT e implementar el flujo de invitados desatendido en su aplicación. |
Incluya estos parámetros en el cuerpo de la solicitud.
| Parámetro | ¿Obligatorio? | Descripción |
|---|---|---|
username
|
Sí. | Nombre de usuario asociado con la dirección de email o el número de teléfono del usuario. |
login_type
|
Sí. | El método que el usuario está utilizando para iniciar sesión. El valor puede ser sms o email. |
client_assertion
|
Sí. | El JWT de certificado de cliente que generó, firmado por el certificado configurado para su aplicación cliente externa. |
recaptcha_token
|
Obligatorio si estas condiciones se aplican a su configuración:
|
Un token cifrado emitido por la API de reCAPTCHA de Google cuando un usuario completa un reto de reCAPTCHA. |
recaptchaevent
|
Obligatorio si estas condiciones se aplican a su configuración:
|
Un objeto JSON que contiene estos subparámetros.
Para obtener más información, consulte la documentación de reCAPTCHA de Google. |
scope
|
No. | Permisos que definen el tipo de recursos protegidos a los que puede acceder la aplicación cliente externa. Usted asigna ámbitos a la aplicación cliente externa cuando la construye, y se incluyen con los tokens de OAuth durante el flujo de autorización. Utilice este parámetro para solicitar un subconjunto de los ámbitos asignados a su aplicación cliente externa. Si no incluye este parámetro, se solicitan todos los ámbitos asignados a la aplicación. |
client_id
|
Sí. | La clave de consumidor de la aplicación cliente externa. |
code_challenge
|
Obligatorio si requería PKCE para su aplicación cliente externa. Para que las funciones de seguridad de este flujo funcionen correctamente, recomendamos encarecidamente que siempre requiera PKCE. | Especifica el valor de hash SHA256 del valor Si se proporciona Si |
email_template
|
Se requiere especificar varias plantillas de email si se activa la lista de admisión de plantillas de email. Si no activó la lista de admisión de plantillas de email, no puede incluir este parámetro. Si no incluye este parámetro, Salesforce utiliza la plantilla de email predeterminada configurada en su configuración de Experience Cloud, independientemente de si la lista de admisión está activada. Si no hay ninguna plantilla configurada, Salesforce utiliza una plantilla de email OTP predeterminada. El idioma de plantilla de email para plantillas predeterminadas está controlado por la configuración de idioma del usuario en Salesforce. |
El nombre del desarrollador de la plantilla de email personalizada. Este parámetro solo puede incluir una plantilla de email desde la lista de admisión. Para controlar el idioma de las plantillas de email personalizadas, cree plantillas en el idioma que desee. |
login_hint
|
Obligatorio si está utilizando un controlador de Apex de descubrimiento de usuarios desatendido. | Un identificador que su controlador de Apex utiliza para buscar la cuenta de Salesforce de un usuario. Por ejemplo, recopile el número de pedido de un usuario en su aplicación y páselo en el parámetro login_hint. Enviamos el valor login_hint directamente a su controlador de Apex. |
customdata
|
Obligatorio si está utilizando un controlador de descubrimiento de usuarios desatendido que gestiona datos personalizados. Por ejemplo, si también está utilizando el controlador con un flujo de inicio de sesión que gestiona datos personalizados, debe pasar datos personalizados en el flujo de contraseña olvidada. De lo contrario, es opcional pero puede ser útil para ayudar a su gestor a encontrar el usuario. |
Cadena JSON que contiene datos adicionales que su controlador de descubrimiento desatendido de Apex utiliza para buscar la cuenta de Salesforce de un usuario. Por ejemplo, pase información acerca de la configuración regional del usuario. |
A continuación se incluye un ejemplo de solicitud.
POST /services/oauth2/v1/authorization_challenge HTTP/1.1
Host: MyExperienceCloudSite.my.site.com
username=janice.edwards@example.com&
login_type=sms&
client_assertion=**********&
recaptcha_token=********&
scope=profile&
client_id=******&
code_challenge=********Paso 5: Salesforce valida la solicitud
Salesforce intenta primero validar el JWT de certificación de cliente comprobando que la firma pasada en el parámetro client_asssertion coincide con la firma para el certificado configurado para la aplicación cliente externa.
Si el JWT de certificado de cliente no es válido, Salesforce devuelve un error invalid_attestation y debe volver a enviar la solicitud con todos los parámetros que envió originalmente. A continuación se incluye un ejemplo de respuesta de error.
HTTP/1.1 403 Forbidden
Content-Type: application/json
Cache-Control: no-store
{
"error": "invalid_attestation",
"error_code": "client_attestation_failed"
}
Si el JWT del certificado de cliente es válido, pero hay otros problemas con la solicitud, Salesforce devuelve una respuesta de error especificando qué salió mal. A continuación se muestra un ejemplo de respuesta que se devuelve si Salesforce no puede encontrar un nombre de usuario que coincida con el que se envió en la solicitud.
HTTP/1.1 403 Forbidden
Content-Type: application/json
Cache-Control: no-store
{
"error": "authorization_required",
"auth_session": "uY29tL2F1d*****",
"error_code": "invalid_credentials"
}La respuesta incluye un parámetro auth_session que permanece válido durante 5 minutos después de su emisión. Durante el periodo de tiempo en el que auth_session es válida, puede utilizarla para volver a enviar la solicitud. En las versiones corregidas que vuelva a enviar, incluya auth-session y los valores corregidos para los parámetros que provocaron el fallo de la solicitud. También debe volver a enviar password con cada solicitud porque Salesforce no almacena este valor confidencial. Pero para otros parámetros, si no provocaron el fallo de la solicitud, puede dejarlos fuera. Salesforce ya sabe que envió estos parámetros porque están vinculados a auth_session.
auth_session, pero puede volver a enviar la solicitud sin ellos a no ser que hayan causado el fallo de la solicitud.Por ejemplo, si su JWT de certificado de cliente es válido pero la solicitud falla porque el nombre de usuario era incorrecto, vuelva a enviar una solicitud que incluya solo auth_session, username y password.
(Opcional) El controlador de descubrimiento de usuarios desatendido encuentra el usuario
Si está utilizando un controlador de descubrimiento de usuarios desatendido, el controlador toma los parámetros login_hint y customdata y encuentra el usuario asociado. El controlador confirma que la dirección de email o el número de teléfono del usuario está verificado.
Para obtener un controlador de ejemplo, consulte Auth.HeadlessUserDiscoveryHandler.
Paso 6: Salesforce envía una OTP al usuario
Si la solicitud se realiza correctamente, Salesforce aún devuelve una respuesta de error porque aún no puede otorgar el código de autorización. Pero esta vez, la respuesta de error indica que se inicializó el inicio de sesión y que Salesforce envió una OTP a la dirección de email o el número de teléfono del usuario. Para confirmar que la solicitud se realizó correctamente, busque el código de error login_initialized y el estado otp_sent. La respuesta también incluye un parámetro auth_session, que es importante para el siguiente paso.
A continuación se incluye un ejemplo de respuesta.
HTTP/1.1 403 Forbidden
Content-Type: application/json
Cache-Control: no-store
{
"error": "authorization_required",
"auth_session": "uY29tL2F1dGhlbnRpY",
"error_code": "login_initialized",
"login_status": {
"type": "SMS",
"state": "otp_sent",
"displayData": "+120******58"
}
}Paso 7: Su aplicación muestra de forma nativa un formulario de verificación
En su aplicación de primera parte, muestra un formulario de verificación donde el usuario final puede ingresar su OTP. El aspecto de este formulario depende completamente de usted.
Paso 8: El usuario ingresa OTP en el formulario de verificación
El usuario recibe la OTP en su dirección de email o número de teléfono y la ingresa en el formulario de verificación en su aplicación de primera parte.
Paso 9: Su aplicación solicita un código de autorización
Para solicitar un código de autorización, su aplicación envía otra solicitud POST al extremo /services/oauth2/v1/authorization_challenge. Esta solicitud no tiene encabezados obligatorios. Incluya estos parámetros en el cuerpo de la solicitud.
| Parámetro | ¿Obligatorio? | Descripción |
|---|---|---|
auth_session
|
Sí. | Representa el intento de inicio de sesión actual. Utilice el valor auth_session que recibió en la respuesta desde su primera solicitud al extremo de reto de autorización. Asegúrese de utilizar auth_session desde la solicitud que indica que se inicializó el inicio de sesión y se envió la OTP. |
login_otp
|
Sí. | La OTP que el usuario final ingresó en el formulario de verificación de su aplicación. |
A continuación se incluye un ejemplo de solicitud.
POST /services/oauth2/v1/authorization_challenge HTTP/1.1
Host: MyExperienceCloudSite.my.site.com
auth_session=uY29tL2F1dGhlbnRpY*
login_otp=<otp_from_sms>Paso 10: Salesforce devuelve un código de autorización
Si la OTP es correcta y auth_session es válida, Salesforce devuelve un código de autorización y finaliza auth_session. A continuación se incluye un ejemplo de respuesta de código de autorización.
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
{
"authorization_code": "uY29tL2F1d******"
}Paso 11: Su aplicación intercambia el código de autorización por un token de acceso
Después de obtener el código de autorización, su aplicación envía una solicitud al extremo services/oauth2/token.
Esta solicitud no tiene encabezados. 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. |
client_secret
|
Sí. | El secreto de consumidor de la aplicación cliente externa. En este flujo, actúa como una contraseña que la aplicación utiliza para acceder a Salesforce. |
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 cliente externa. De lo contrario, la aprobación falla. Este valor debe tener codificación de URL. |
grant_type
|
Sí. | El tipo de validación que la aplicación puede proporcionar para probar que es un visitante seguro. Para este flujo, el valor debe ser authorization_code. |
code_verifier
|
Obligatorio si requería PKCE para su aplicación cliente externa. Para que las funciones de seguridad de este flujo funcionen correctamente, recomendamos encarecidamente que siempre requiera 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 estar codificado con base64url como se define en https://datatracker.ietf.org/doc/html/rfc4648#section-5. Si existe un valor Si el valor |
A continuación se incluye una solicitud de token de ejemplo.
POST services/oauth2/token? HTTP 1.1
Host: MyExperienceCloudSite.my.site.com
code=********&
client_id=**********&
client_secret=*********&
redirect_uri=<callback_URL>&
grant_type=authorization_code&
code_verifier=*******Paso 12: Salesforce otorga un token de acceso
Después de validar las credenciales de la aplicación. Salesforce devuelve un token de acceso. A continuación se incluye un ejemplo de respuesta de token de acceso en formato JSON.
{
"access_token":"*******************",
"sfdc_community_url":"https://MyDomainName.my.site.com",
"sfdc_community_id":"0DBxxxxxxxxxxxx",
"signature":"ts6wm/svX3jXlCGR4uu+SbA04M6qhD1SAgVTEwZ59P4=",
"scope":"openid api",
"id_token":"XXXXXX",
"instance_url":"https://yourInstance.salesforce.com",
"id":"https://yourInstance.salesforce.com/id/00Dxxxxxxxxxxxx/005xxxxxxxxxxxx",
"token_type":"Bearer",
"issued_at":"1667600739962"
}La respuesta del token de acceso contiene estos parámetros.
| Parámetro | ¿Obligatorio? | Descripción |
|---|---|---|
access_token
|
Sí. | Token de OAuth que una aplicación cliente externa utiliza para solicitar el acceso a un recurso protegido en nombre de la aplicación cliente. Pueden acompañar permisos adicionales en la forma de ámbitos al token de acceso. |
id
|
Sí. | Una URL de identidad que se puede utilizar para identificar al usuario y para consultar con el fin de obtener más información acerca del usuario. Consulte URL de identidad. |
id_token
|
No. | Una estructura de datos firmada que contiene atributos de usuario autenticados, incluyendo un identificador único para el usuario y una marca de tiempo que indica el momento en que se emite el token. También identifica la aplicación solicitante. Consulte Especificaciones de OpenID Connect. |
instance_url
|
Sí. | Una URL que indica la instancia de la organización del usuario. Por ejemplo, https://yourInstance.salesforce.com/. |
issued_at
|
Sí. | Una marca de hora de la creación de la firma, expresada como el número de milisegundos desde 1970-01-01T0:0:0Z UTC. |
refresh_token
|
No. | Token obtenido del servidor web, usuario-agente o flujo de token de aplicación híbrida. Se trata de un valor secreto. Tome las medidas apropiadas para protegerlo. Este parámetro solo se devuelve si su aplicación cliente externa o aplicación conectada se configura con un ámbito refresh_token. |
signature
|
Sí. | Firma HMAC-SHA256 con codificación Base64 firmada con client_secret. La firma puede incluir el Id. concatenado y el valor issued_at, que puede utilizar para verificar que la URL de identidad no cambió desde que la envió el servidor. |
sfdc_community_url
|
Sí. | La URL del sitio de Experience Cloud. |
sfdc_community_id
|
Sí. | El Id. de sitio de Experience Cloud del usuario. |
state
|
No. | El estado solicitado por el cliente. Este valor solo se incluye si el parámetro state está incluido en la cadena de consulta original. |
token_type
|
Sí. | Un tipo de token Bearer, que se utiliza para todas las respuestas que influyen un token de acceso. |
Paso 13: La aplicación crea la sesión del usuario
Su aplicación recibe la respuesta del token de acceso, la procesa y crea la sesión del usuario.
Paso 14: El usuario inicia sesión y realiza una acción en la aplicación
El usuario final ahora tiene su sesión iniciada y realiza una acción en su aplicación que requiere acceso a datos de Salesforce. Por ejemplo, hace clic en un botón para ver su historial de pedidos, que se almacena en Salesforce.
Paso 15: La aplicación realiza una llamada autenticada a un extremo de Salesforce
Para acceder a los datos de Salesforce del usuario, su aplicación utiliza el token de acceso para realizar una llamada autenticada a un extremo de Salesforce protegido, como una API de Salesforce.
Paso 16: El usuario puede acceder a datos de Salesforce
El usuario puede ahora acceder a datos de Salesforce protegidos en su aplicación. Por ejemplo, puede ver su historial de pedidos. Desde la perspectiva del usuario, el proceso completo desde el inicio de sesión hasta el acceso a sus datos se produjo sin requerir nunca salir de la aplicación.
