Configurar el flujo de intercambio de tokens
Algunos casos de uso requieren que integre Salesforce con un proveedor de identidad externa junto con múltiples aplicaciones y microservicios. Para simplificar estas integraciones, utilice el flujo de intercambio de tokens de OAuth 2.0. Con este flujo, intercambie tokens desde un proveedor de identidad externo para tokens de Salesforce.
Ediciones necesarias
| Disponible en: Enterprise Edition, Performance Edition, Unlimited Edition y Developer Edition |
Por ejemplo, aloja un portal de clientes fuera de la plataforma Salesforce. Para proporcionar el inicio de sesión y el registro a sus clientes, utiliza un proveedor de identidad. Cuando sus clientes inician sesión, acceden a los datos desde una variedad de servicios de negocio, incluyendo aplicaciones web y microservicios. Para autorizar a su portal a conceder a los usuarios acceso a sus datos, todos estos servicios de negocio aceptan tokens de acceso de su proveedor de identidad.
Usted utiliza Salesforce para realizar un seguimiento de los casos de asistencia de los clientes y desea proporcionar a los usuarios una forma de acceder a sus casos en su portal. Configurando Salesforce para aceptar tokens de su proveedor de identidad, puede ajustar fácilmente Salesforce a su patrón de integración. Utilizando el flujo de intercambio de tokens, Salesforce valida los tokens del proveedor de identidad, los asigna a un usuario de Salesforce y emite tokens de Salesforce, dejándolos los usuarios pueden acceder a sus datos dentro de su portal.
Este es un aspecto paso a paso del flujo de intercambio de tokens.
El usuario final solicita acceso a datos de Salesforce (1)
Un usuario final inicia sesión en su aplicación. Solicita acceso a recursos de Salesforce protegidos. Por ejemplo, hace clic en un botón para ver sus casos.
La aplicación tiene un token válido (2)
Cuando el usuario final inició sesión, recibió uno o más tokens de su proveedor de identidad. Por ejemplo, recibió un token de acceso y un token de actualización. Para obtener acceso a datos de Salesforce, su aplicación puede intercambiar uno de estos tokens. Salesforce acepta estos tipos de tokens.
- Tokens de acceso
- Actualizar tokens
- Tokens web de JSON (JWT)
- Afirmaciones SAML
- Tokens de Id.
La aplicación solicita un intercambio de un token de Salesforce (3)
Para obtener un token de Salesforce, su aplicación envía una solicitud POST al extremo /services/oauth2/token en su URL de inicio de sesión de Mi dominio o URL de sitio de Experience Cloud.
La solicitud admite un encabezado.
| Encabezado | ¿Obligatorio? | Descripción |
|---|---|---|
Uvid-Hint
|
No. Si implementa el flujo de usuario invitado en su aplicación, puede utilizar opcionalmente este encabezado para pasar en un Id. de visitante exclusivo (UVID) vinculado a la identidad de un usuario invitado. Utilice el UVID para llevar información contextual desde una sesión de usuario invitado, como las preferencias de cookie del usuario, a una sesión de usuario nombrada. | Contiene el UVID, un identificador exclusivo universal de Versión 4 (UUID) que identifica visitantes desconocidos. Envíe el UVID como un valor sin formato, o bien envíe un token de acceso basado en JWT con un UVID acuñado en él. Para enviar el UVID como un valor sin formato, incluya un prefijo UVID de modo que la solicitud tenga el formato Para enviar un token de acceso basado en JWT con un UVID, incluya un prefijo de JWT antes del valor, como |
Incluya estos parámetros en la solicitud.
| Parámetro | ¿Obligatorio? | Descripción |
|---|---|---|
grant_type
|
Sí. | El método de OAuth 2.0 que utiliza la aplicación para solicitar el token de acceso. El flujo de intercambio de tokens admite estos valores.
|
subject_token
|
Sí. | El token emitido por el proveedor de identidad. La longitud máxima es de 10.000 caracteres. |
subject_token_type
|
Sí. | El tipo de token emitido por el proveedor de identidad. El flujo admite estos tipos de token.
|
client_id
|
Sí. | La clave de consumidor de la aplicación conectada o la aplicación cliente externa. |
client_secret
|
Depende de la configuración de su aplicación conectada o aplicación cliente externa. Para aplicaciones conectadas, para requerir Para aplicaciones cliente externas, establezca el campo |
El secreto de consumidor de la aplicación conectada o la aplicación cliente externa. Recomendamos que envíe un secreto de consumidor solo si su aplicación tiene un backend de cliente privado donde puede mantener el secreto seguro. Para clientes públicos que no tienen un back-end privado, como aplicaciones móviles y aplicaciones de una única página, no recomendamos enviar un secreto porque se puede perder en el navegador. |
scope
|
No. | Los permisos que definen el tipo de recursos protegidos a los que la aplicación conectada puede acceder. Los valores que envía en esta solicitud deben coincidir o ser un subconjunto de los ámbitos asignados a su aplicación conectada o aplicación cliente externa. Para obtener más información acerca de cada ámbito y su finalidad, consulte Tokens y ámbitos de OAuth. |
token_handler
|
No, pero se recomienda encarecidamente. Si no incluye este parámetro, Salesforce utiliza su controlador predeterminado. Defina un controlador predeterminado utilizando el campo isDefault en el tipo de metadatos OauthTokenExchHandlerApp. Debe tener al menos un controlador predeterminado. | El nombre del controlador de intercambio de tokens de Apex utilizado para validar el token y asignarlo a un usuario de Salesforce. |
A continuación se incluye una solicitud de token de ejemplo que contiene un token de acceso.
POST /services/oauth2/token? HTTP 1.1
Host: MyDomainName.my.site.com
Uvid-Hint: UVID abcd-1234-efgh
grant_type=urn:ietf:params:oauth:grant-type:token-exchange&
subject_token=*************&
subject_token_type=urn:ietf:params:oauth:token-type:access_token&
client_id=***********&
client_secret=************&
scope=web&
token_handler=MyTokenHandler
El tiempo de ejecución de Salesforce OAuth completa la validación inicial (4)
El tiempo de ejecución de OAuth de Salesforce recibe la solicitud y la ejecuta a través de una validación inicial. La validación se basa en estos requisitos.
- La aplicación conectada o la aplicación cliente externa deben estar activadas para el flujo de intercambio de tokens. Consulte Integrar una aplicación para el flujo de intercambio de tokens.
subject_token_typeen la solicitud debe estar activado para el controlador de intercambio de tokens. Para activar un controlador para un tipo de token, establezca el campo correspondiente en la definición de metadatos de OauthTokenExchangeHandler del controlador comotrue.subject_token_typeValorCampo OauthTokenExchangeHandler urn:ietf:params:oauth:token-type:access_tokenisAccessTokenSupported urn:ietf:params:oauth:token-type:refresh_tokenisRefreshTokenSupported urn:ietf:params:oauth:token-type:id_tokenisIdTokenSupported urn:ietf:params:oauth:token-type:saml2isSaml2Supported urn:ietf:params:oauth:token-type:jwtisJwtSupported - Si la solicitud incluye
client_secret, debe coincidir con el secreto de consumidor de la aplicación conectada o la aplicación cliente externa. - Si la solicitud incluye
token_handler, la organización debe tener un controlador de intercambio de tokens de Apex compatible que coincida con el nombre de la solicitud. - El controlador de intercambio de tokens debe estar activado, lo que significa que el campo isEnabled en su definición de metadatos OauthTokenExchangeHandler debe estar establecido en
true.
Si la solicitud cumple estos requisitos iniciales, Salesforce envía el token desde el proveedor de identidad externa al controlador de intercambio de tokens de Apex.
El controlador de Apex valida el token (5)
El controlador de Apex recibe el token del proveedor de identidad y lo valida empleando su lógica de validación personalizada. El modo en que desea validar el token depende completamente de usted.
(Opcional) Apex Handler llama al proveedor de identidad para su validación (6)
Dependiendo de sus requisitos de validación, puede configurar opcionalmente su controlador para realizar una llamada al proveedor de identidad. Si el token es opaco o si desea validarlo en tiempo real, llame al introspección del token o al extremo de información de usuario en el proveedor de identidad externo.
El controlador de Apex asigna el token a un asunto de Salesforce (7)
El controlador de Apex identifica el asunto del token, que es el usuario final al que se emite, y lo asigna a un asunto de Salesforce.
(Opcional) Apex Handler llama al proveedor de identidad para obtener información de usuario (8)
Para obtener suficiente información para crear un asunto o para obtener información adicional acerca de un asunto entrante, puede opcionalmente configurar su controlador para realizar una llamada al proveedor de identidad o a otro sistema externo.
Apex Handler busca o configura un usuario (9)
Si el controlador encuentra un usuario basándose en datos del token o de una llamada externa, devuelve el usuario.
Si el campo isUserCreationAllowed se establece como true en la definición de metadatos de OauthTokenExchangeHandler del controlador, el controlador configura un nuevo objeto Usuario y lo devuelve a Salesforce. Esta acción no crea en realidad el usuario; en lugar del objeto Usuario se devuelve a Salesforce para la inserción automatizada.
Para obtener más información acerca de la personalización de su controlador para validar tokens y asignar asuntos, consulte Validación de controlador de intercambio de tokens y asignación de asunto en la Guía del desarrollador de Apex.
Asignación de usuario de Salesforce OAuth Runtime Completes (10)
El tiempo de ejecución de Salesforce OAuth comprueba si el controlador devolvió un usuario. Si es así, confirma si el usuario existe y completa la asignación. Si el usuario no existe y si el controlador está configurado para configurar usuarios, Salesforce inserta automáticamente el usuario en nombre del controlador de intercambio de tokens.
Respuesta de token de devolución de tiempo de ejecución de OAuth de Salesforce (11)
Salesforce devuelve una respuesta que contiene un token de acceso de Salesforce y cualquier otro token o parámetros que haya solicitado, incluyendo tokens de actualización, tokens de ID y tokens híbridos. El token de acceso puede ser opaco o basado en JWT, dependiendo de su aplicación conectada o configuración de aplicación cliente externa.
Si pasó un UVID en la solicitud de token, también se pasa por el flujo. Para una respuesta de token opaca, el UVID se expone en el extremo services/oauth2/userinfo en su URL de inicio de sesión de Mi dominio o URL de sitio de Experience Cloud. Para una respuesta de token basada en JWT, el UVID se acuerda en el nuevo token de acceso.
La aplicación recibe respuesta (12)
Su aplicación recibe la respuesta del token, incluyendo el token de acceso y otros tokens y parámetros. A continuación se incluye un ejemplo de respuesta de token.
{
"access_token":"*******************",
"signature":"ts6wm/svX3jXlCGR4uu+SbA04M6qhD1SAgVTEwZ59P4=",
"scope":"openid api",
"id_token":"XXXXXX",
"instance_url":"https://MyDomainName.my.salesforce.com",
"id":"https://MyDomainName.my.salesforce.com/id/00Dxxxxxxxxxxxx/005xxxxxxxxxxxx",
"token_type":"Bearer",
"issued_at":"1667600739962"
}El extremo de información del usuario de llamadas de aplicación (13)
Si es necesario para completar el inicio de sesión de usuario, su aplicación puede llamar al extremo /services/oauth2/userinfo en su URL de inicio de sesión de Mi dominio o URL de sitio de Experience Cloud. Por ejemplo, si pasó un UVID en su solicitud de token y Salesforce devolvió una respuesta con un token de acceso opaco, llame al extremo Información de usuario para obtener el UVID.
La aplicación solicita acceso a datos de Salesforce (14)
Ahora que su aplicación tiene un token de acceso de Salesforce, realiza una solicitud autenticada a un recurso de Salesforce protegido para obtener al usuario sus datos.
El usuario final accede a datos de Salesforce (15)
Si la solicitud se realiza correctamente, el usuario final puede acceder a sus datos de Salesforce en su aplicación. Desde la perspectiva del usuario, simplemente hicieron clic en un botón y vieron sus datos, sin necesidad de iniciar sesión o aprobar el acceso.
