Flujo de servidor web híbrido OAuth 2.0
Utilice el flujo de servidor web híbrido de OAuth 2.0 para proporcionar a aplicaciones híbridas gestión directa de sesiones web. Cuando el servidor que autoriza otorga un token de acceso, incluye los Id. de sesión (SID) para los dominios solicitados en su respuesta. La aplicación híbrida puede entonces establecer cookies de dominio de contenido, Lightning y Visualforce y acortar un token de acceso en una sesión web, proporcionando servicio ininterrumpido.
Ediciones necesarias
| Disponible en: Salesforce Classic (no disponible en todas las organizaciones) y Lightning Experience |
| Disponible en: todas las ediciones |
El flujo de servidor web híbrido sigue los mismos pasos de autorización utilizados en el flujo de usuario-agente de OAuth 2.0 para integración de aplicaciones móviles o de escritorio, con la excepción de que el flujo de servidor web híbrido utiliza un hybrid_auth_code como su tipo de otorgamiento. Por ejemplo, crea una aplicación híbrida para su departamento de ventas para acceder a información durante sus desplazamientos, incluyendo un tablero que realiza un seguimiento de clientes potenciales de ventas principales. Esta aplicación implementa el flujo de token de aplicación híbrida, que sigue estos pasos.
- Para integrar la aplicación híbrida con la API de Salesforce, cree una aplicación cliente externa. Active la configuración de OAuth y asigne estos ámbitos de OAuth a la aplicación cliente externa.
-
-
lightning -
content -
refresh_token -
visualforce -
web
-
- El usuario final abre la aplicación y se dirige a Salesforce para autenticar y autorizar la aplicación.
- Después de que el usuario apruebe el acceso para este flujo de autorización, la aplicación recibe la devolución de llamada desde Salesforce a la URL de redireccionamiento, que extrae los tokens de acceso y actualización. Los SID de contenido, Visualforce y Lightning para los dominios respectivos también están incluidos, junto con cookies de sesión que permiten a la aplicación acortar directamente una sesión web.
Nota Este flujo admite tokens de acceso basados en JWT solo si la aplicación cliente externa no tiene la rotación de tokens de actualización activada. Si la rotación de tokens de actualización está activada, la solicitud de token devuelve un errorinvalid_grant. - La aplicación establece las cookies de sesión de Lightning, Visualforce y contenido y acorta un token de acceso en una sesión web.
- El usuario puede acceder al tablero de clientes potenciales de ventas principales sin sesiones interrumpidas.
Solicitar un código de autorización
Para iniciar el flujo de servidor web híbrido de OAuth 2.0, el servicio web externo (a través de la aplicación cliente externa) publica una solicitud de código de autorización utilizando el tipo de otorgamiento de código de autorización en el extremo de autorización de Salesforce. Con un código de autorización, la aplicación cliente externa puede probar que se autorizó como visitante seguro del sitio y que tiene permiso para solicitar un token de acceso.
El código de autorización se realiza en la forma de un redireccionamiento HTTP, como este ejemplo.
https://MyDomainName.my.salesforce.com/services/oauth2/authorize?
client_id=3MVG9IHf89I1t8hrvswazsWedXWY0i1qK20PSFaInvUgLFB6vrcb9bbWFTSIHpO8G2jxBLJA6uZGyPFC5Aejq&
redirect_uri=https://www.mycustomerorderstatus.com/oauth2/callback&
response_type=codeIncluya estos parámetros en la solicitud del código de autorización.
| Parámetro | Descripción |
|---|---|
Request Header
|
El extremo de autorizaciones de OAuth 2.0 de Salesforce. Las aplicaciones cliente externas envían solicitudes de autorización de OAuth a este extremo. |
client_id
|
La clave de consumidor de la aplicación cliente externa. Para acceder a la clave de consumidor, desde el Gestor de aplicación cliente externa, busque la aplicación cliente externa y seleccione Modificar configuración desde el menú desplegable. A continuación amplíe la sección Configuración de OAuth y haga clic en Clave y secreto de consumidor. A veces se le solicita verificar su identidad antes de poder ver la clave de consumidor. |
redirect_uri
|
La URL donde se redirige a los usuarios después de una autenticación satisfactoria. El URI de redireccionamiento 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. Puede encontrar el URI de redireccionamiento en la página Configuración de OAuth de la aplicación cliente externa. Este valor debe tener codificación de URL. |
response_type
|
El tipo de concesión de OAuth 2.0 que solicita la aplicación cliente externa. El valor de este flujo debe ser code para indicar que la aplicación cliente externa está solicitando un código de autorización. |
También puede incluir estos parámetros en la solicitud del código de autorización.
| Parámetro | Descripción |
|---|---|
scope
|
Permisos que definen el tipo de recursos protegidos a los que puede acceder una aplicación cliente externa. Usted asigna ámbitos a una aplicación cliente externa cuando la crea, y se incluyen con los tokens de OAuth durante el flujo de autorización. Si no incluye este parámetro, se solicitan todos los ámbitos asignados a la aplicación cliente externa. Los ámbitos que se hayan pasado en este parámetro deben ser un subconjunto de los ámbitos registrados. Para parámetros válidos, consulte Tokens y ámbitos de OAuth. |
state
|
Cualquier estado que solicite el servicio web externo a la URL de devolución de llamadas. Este valor debe tener codificación de URL. |
immediate
|
Un valor booleano que determina si se solicita al usuario el inicio de sesión y la aprobación. El valor predeterminado es
La opción |
code_challenge
|
Especifica el valor de hash SHA256 del valor Este parámetro se requiere si se especifica
|
display
|
Cambia el tipo de visualización de las páginas de inicio de sesión y autorización. Salesforce admite estos valores:
|
login_hint
|
Proporciona un valor de nombre de usuario válido para rellenar previamente la página de inicio de sesión con el nombre de usuario, como Para pasar el parámetro |
nonce
|
Utilícelo con el ámbito openid para solicitar un token de Id. de usuario. El token de Id. de usuario se devuelve en la respuesta. Este parámetro es opcional, pero ayuda a detectar ataques de repetición.
|
prompt
|
Especifica cómo el servidor de autorización solicita al usuario una reaprobación y reautenticación. Salesforce admite estos valores:
Puede pasar los valores |
Encabezado de Uvid-Hint |
Opcionalmente, para conectar este flujo al flujo de invitados desatendido, puede incluir un encabezado 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 Token web de JSON (JWT) que contenga un Id. de visitante exclusivo (UVID) vinculado a la identidad de un usuario invitado. Al pasar el UVID a un flujo de usuario nombrado, puede llevar información contextual desde una sesión de usuario invitado, como las preferencias de cookies del usuario, a una sesión de usuario nombrada. |
Parámetro de cuerpo uvid_hint |
Un valor En lugar de pasar el UVID en el cuerpo de la solicitud, también puede pasarla en un token basado en JWT con un UVID a través del encabezado |
El usuario autentica y autoriza el acceso
Antes de que Salesforce proporcione códigos de autorización a aplicaciones cliente externas, se solicita a los usuarios autenticadores iniciar sesión en Salesforce.
Tras un inicio de sesión satisfactorio, Salesforce redirige a los usuarios a la página de aprobación para otorgar acceso a la aplicación.
Si los usuarios ya aprobaron el acceso, no es necesario volver a aprobar el acceso de nuevo.
Salesforce otorga el código de autorización
Después de que los usuarios aprueben el acceso a una aplicación cliente externa, Salesforce redirige a los usuarios a la URL de devolución de llamada, donde pueden ver la devolución de llamada con un código de autorización.
https://www.mycustomerorderstatus.com/oauth2/callback?
code=aPrx4sgoM2Nd1zWeFVlOWveD0HhYmiDiLmlLnXEBgX01tpVOQMWVSUuafFPHu3kCSjzk4CUTZg==- La primera parte de la devolución de llamada es la URL de devolución de llamada de la aplicación cliente externa:
https://www.mycustomerorderstatus.com/oauth2/callback. - La segunda parte es el código de autorización que la aplicación cliente externa utiliza para obtener un token de acceso:
code=aPrx4sgoM2Nd1zWeFVlOWveD0HhYmiDiLmlLnXEBgX01tpVOQMWVSUuafFPHu3kCSjzk4CUTZg==. El código de autorización caduca después de 15 minutos.
Si el parámetro state está incluido en la cadena de consulta original, el estado especificado se pasa al paso de aprobación.
Solicitar un token de acceso
Para solicitar un token de acceso, la aplicación cliente externa pasa el código de autorización al extremo del token de Salesforce como un POST HTTP.
POST /services/oauth2/token HTTP/1.1
Host: mycompany.my.salesforce.com
Content-length: 307
Content-type: application/x-www-form-urlencoded
grant_type=hybrid_auth_code&
code=aPrxhgZ2MIpkSy0aOdn07LjKFvsFOis6RGcWXz7p8JQCjcqfed5NQLe7sxWwMY_JQFuLwHRaRA==&
client_id=3MVG9IHf89I1t8hrvswazsWedXWY0iqK20PSFaInvUgLFB6vrcb9bbWFTSIHpO8G2jxBLJA6uZGyPFC5Aejq&
client_secret=*******************&
redirect_uri=https://www.mycustomerorderstatus.com/oauth2/callback
POST en el ejemplo contiene estos parámetros.
| Parámetro | Descripción |
|---|---|
Request Header
|
El encabezado de la solicitud puede contener estos parámetros.
El encabezado de la solicitud también admite estos parámetros.
El parámetro |
grant_type
|
El tipo de validación que la aplicación cliente externa puede proporcionar para probar que es un visitante seguro. Para el flujo de servidor web híbrido, el valor debe ser hybrid_auth_code. |
code
|
Un código de autorización temporal recibido del servidor de autorización. La aplicación cliente externa utiliza este código a cambio de un token de acceso. Este tipo de flujo de OAuth 2.0 es una forma segura de pasar el token de acceso de vuelta a la aplicación. |
client_id
|
La clave de consumidor de la aplicación cliente externa. Para acceder a la clave de consumidor, desde el Gestor de aplicación cliente externa, busque la aplicación cliente externa y seleccione Modificar configuración desde el menú desplegable. A continuación amplíe la sección Configuración de OAuth y haga clic en Clave y secreto de consumidor. A veces se le solicita verificar su identidad antes de poder ver la clave de consumidor. |
client_secret
|
Secreto de consumidor de la aplicación cliente externa. Para acceder al secreto de consumidor, desde el Gestor de aplicación cliente externa, busque la aplicación cliente externa y seleccione Modificar configuración desde el menú desplegable. A continuación amplíe la sección Configuración de OAuth y haga clic en Clave y secreto de consumidor. A veces se le solicita verificar su identidad antes de poder ver el secreto de consumidor. Este parámetro es obligatorio a menos que la aplicación cliente externa no tenga activado Requerir secreto para flujo de servidor web. Si no se requiere un |
redirect_uri
|
La URL donde se redirige a los usuarios después de una autenticación satisfactoria. El URI de redireccionamiento 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. Puede encontrar el URI de redireccionamiento en la página Configuración de OAuth de la aplicación cliente externa o desde la definición de la aplicación cliente externa. Este valor debe tener codificación de URL. |
También puede incluir estos parámetros.
| Parámetro | Descripción |
|---|---|
client_assertion
|
En vez de pasar client_secret, puede proporcionar client_assertion y client_assertion_type. Si no se proporciona un parámetro client_secret, Salesforce comprueba si hay client_assertion y client_assertion_type. Consulte Utilizar client_assertion en vez de client_secret. |
client_assertion_type
|
Proporcione este valor cuando utilice el parámetro El valor |
code_verifier
|
Se requiere únicamente si se especificó un parámetro code_challenge en la solicitud de autorización. Especifica 128 bytes de datos aleatorios con alta entropía para hacer que intentar determinar el valor
|
format
|
Si no se incluye en el encabezado de la solicitud, puede especificar el formato de devolución esperado. El parámetro
|
client_assertion en vez de client_secretSi proporciona client_assertion en vez de client_secret, el valor client_assertion debe incluir estos parámetros.
iss: Elclient_idde la definición de la aplicación cliente externa.sub: Elclient_idde la definición de la aplicación cliente externa.aud: La URL del servlet de token: http://nombrehost/services/oauth2/token.exp: El plazo de vencimiento de la afirmación, en 5 minutos, expresado como el número de segundos desde 1970-01-01T0:0:0Z según la zona horaria UTC.
client_assertion también debe estar firmada con la clave privada asociada con el certificado cargado del consumidor de OAuth. Solo se admite el algoritmo RS256. Para el método de autenticación de cliente private_key_jwt, consulte las especificaciones de OpenID Connect.
En lugar de enviar credenciales de cliente como parámetros en el cuerpo de la operación POST, Salesforce admite el esquema de autenticación HTTP básica. Este formato de esquema requiere client_id y client_secret en el encabezado de autorización de la publicación de la siguiente forma:
Authorization:
Basic64Encode(client_id:secret)
client_id y client_secret se separan con un punto (:). Para obtener más información consulte el documento Marco de autorización OAuth 2.0.
Este ejemplo muestra una solicitud POST de token de acceso que utiliza el esquema de autenticación HTTP básica en lugar de enviar credenciales de cliente en el cuerpo de la solicitud POST.
POST /services/oauth2/token HTTP/1.1
Host: mycompany.my.salesforce.com
Authorization: Basic client_id=3MVG9IHf89I1t8hrvswazsWedXWY0iqK20PSFaInvUgLFB6vrcb9bbWFTSIHpO8G2jxBLJA6uZGyPFC5Aejq&
client_secret=*******************&
grant_type=hybrid_auth_code&code=aPrxsmIEeqM9PiQroGEWx1UiMQd95_5JUZ
VEhsOFhS8EVvbfYBBJli2W5fn3zbo.8hojaNW_1g%3D%3D&
redirect_uri=https%3A%2F%2Fwww.mysite.com%2Fcode_callback.jspclient_id y client_secret se envían en el cuerpo de POST, se ignora el encabezado de autorización.Salesforce otorga un token de acceso
Después de que Salesforce valide las credenciales de la aplicación, envía de vuelta una respuesta con el token de acceso.
En este ejemplo, la respuesta está en un formato JSON.
{
"access_token": "00DB0000000TfcR!AQQAQFhoK8vTMg_rKA.esrJ2bCs.OOIjJgl.9Cx6O7KqjZmHMLOyVb.U61BU9tm4xRusf7d3fD1P9oefzqS6i9sJMPWj48IK",
"signature": "d/SxeYBxH0GSVko0HMgcUxuZy0PA2cDDz1u7g7JtDHw=",
"scope": "web openid",
"id_token": "eyJraWQiOiIyMjAiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdF9oYXNoIjoiSVBRNkJOTjlvUnUyazdaYnYwbkZrUSIsInN1YiI6Imh0dHBzOi8vbG9...",
"instance_url": "https://mycompany.my.salesforce.com",
"id": "https://login.salesforce.com/id/00DB0000000TfcRMAS/005B0000005Bk90IAC",
"token_type": "Bearer",
"issued_at": "1558553873237"
}
La respuesta del token incluye estos parámetros.
| Parámetro | Descripción |
|---|---|
access_token
|
Token de OAuth que una aplicación cliente externa utiliza para solicitar 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. |
signature
|
Firma HMAC-SHA256 con codificación Base64 firmada con client_secret. La firma puede incluir el Id. concatenado y issued_at value, que puede utilizar para verificar que la URL de identidad no cambió desde que la envió el servidor. |
scope
|
Los ámbitos asociados con el token de acceso. Los ámbitos definen más el tipo de recursos protegidos a los que el cliente puede acceder. Usted asigna ámbitos a una aplicación cliente externa cuando la crea, y se incluyen con los tokens de OAuth durante el flujo de autorización. Para parámetros válidos, consulte Tokens y ámbitos de OAuth. |
content_domain
|
El dominio de la sesión de contenido, que se asigna al SID de contenido: MyDomainName.file.force.com →
content_sid.
|
content_sid
|
El SID asociado con el dominio de la sesión de contenido. Salesforce devuelve un SID exclusivo que la aplicación híbrida establece directamente en la cookie de sesión del dominio. |
lightning_domain
|
El dominio de la sesión Lightning, que se asigna al SID de Lightning: <MyDomainName or
instance>.lightning.force.com → lightning_sid.
|
lightning_sid
|
El SID asociado con el dominio de la sesión de Lightning. Salesforce devuelve un SID exclusivo que la aplicación híbrida establece directamente en la cookie de sesión del dominio. |
visualforce_domain
|
El dominio de la sesión de Visualforce, que se asigna al SID de Visualforce: MyDomainName.vf.force.com →
visualforce_sid.
|
visualforce_sid
|
El SID asociado con el dominio de la sesión de Visualforce. Salesforce devuelve un SID exclusivo que la aplicación híbrida establece directamente en la cookie de sesión del dominio. |
csrf_token
|
El token de falsificación de petición en sitios cruzados (CSRF) para prevenir ataques durante sesiones secundarias. |
id_token
|
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 del cliente solicitante. Consulte Especificaciones de OpenID Connect. Este parámetro se devuelve si el parámetro scope incluye |
instance_url
|
Una URL que indica la instancia de la organización del usuario. Por ejemplo: https://yourInstance.salesforce.com/.
|
id
|
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. |
token_type
|
Un tipo de token Bearer, que se utiliza para todas las respuestas que influyen un token de acceso.
|
issued_at
|
Marca de tiempo del momento de creación de la firma en milisegundos. |
sidCookieName
|
El nombre de la cookie de sesión que la aplicación híbrida utiliza para acortar directamente una sesión web. El valor predeterminado es sid. |
cookie-sid_Client
|
Una cookie de sesión que detecta y evita manipulación de sesión. Esta cookie de sesión permite a la aplicación híbrida acortar directamente una sesión web. |
cookie-clientSrc
|
Una cookie de sesión que se utiliza para protección de seguridad. Esta cookie de sesión permite a la aplicación híbrida acortar directamente una sesión web. |
La respuesta del token también puede contener estos parámetros.
