OAuth 2.0 para aplicaciones de primera parte: Flujo de nombre de usuario-contraseña desatendido para clientes privados

Paso 1: El usuario final abre la aplicación de primera parte e inicia sesión

Un usuario final abre su aplicación de primera parte con la intención de iniciar sesión. En su aplicación, su formulario de inicio de sesión aparece mostrando campos de nombre de usuario y contraseña y un botón de inicio de sesión. Salesforce no proporciona este formulario de inicio de sesión. Su aspecto y comportamiento dependen de usted. Su usuario ingresa su nombre de usuario y contraseña y hace clic en el botón de inicio de sesión.

Paso 2: La aplicación de primera parte acuña un JWT de certificado de cliente y genera valores de code_verifier y code_challenge

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.

Nota Recomendamos encarecidamente que implemente siempre PKCE para este flujo. De lo contrario, no obtiene sus beneficios de seguridad.

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 3: La aplicación de primera parte solicita desatendidamente un código de autorización

Desde el navegador, 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).

Incluya estos parámetros en el cuerpo de la solicitud.

A continuación se incluye un ejemplo de solicitud al extremo de reto de autorización.

POST /services/oauth2/v1/authorization_challenge? HTTP 1.1
Host: MyExperienceCloudSite.my.site.com

username=janice.edwards@example.com&
password=*****&
client_assertion=******&
recaptcha=********&
scope=profile&
code_challenge=********

Paso 4: Salesforce valida la solicitud

Salesforce intenta primero validar el JWT de certificado de cliente validando 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é falla con la solicitud. A continuación se muestra un ejemplo de respuesta que se devuelve si el usuario envía un nombre de usuario o una contraseña incorrectos.

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 solo 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 la almacena. 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.

Nota Los parámetros de reCAPTCHA no se vinculan a auth_session, pero puede volver a enviar la solicitud sin ellos a no ser que hayan causado el fallo de la solicitud.

Estos son algunos ejemplos de escenarios de error comunes. Esta lista no es exhaustiva.

• El usuario envió el nombre de usuario o la contraseña incorrectos. Vuelva a enviar la solicitud solo con username, password y auth_session.
• El token de reCAPTCHA era incorrecto. Vuelva a enviar la solicitud solo con el token de reCAPTCHA, password, y auth_session.

Transcurridos 5 minutos desde que se emitió la sesión de autenticación, ya no funciona y obtiene un error auth_session_invalid. En ese caso, vuelva a enviar la solicitud completa con todos los parámetros que incluyó originalmente.

(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 5: Salesforce devuelve un código de autorización

Cuando su solicitud al extremo de reto de autorización se realiza correctamente (ya sea en el primer intento o después de varios reintentos con auth_session), Salesforce devuelve un código de autorización. Este es un ejemplo de una respuesta correcta del 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 6: 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.

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 7: 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.

Paso 8: La aplicación crea la sesión del usuario

La aplicación recibe la respuesta del token de acceso y crea la sesión del usuario.

Paso 9: 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.

Nota Cuando configura su aplicación cliente externa o aplicación conectada para el flujo Código de autorización y credenciales, establece la política Usuarios permitidos en Usuarios aprobados por el administrador se han autorizado previamente y configura qué perfiles o conjuntos de permisos pueden acceder a la aplicación. Con esta política, los usuarios acceden a la aplicación sin autorizarla, de modo que no obtienen una pantalla de autorización solicitándoles permitir a la aplicación acceder a sus datos.

Paso 10: 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 11: 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.