Flujo servidor web de OAuth 2.0 para la integraciĆ³n de aplicaciones web
Para integrar una aplicaciĆ³n web externa con la API de Salesforce, utilice el flujo servidor web de OAuth 2.0, que implementa el tipo de otorgamiento de cĆ³digo de autorizaciĆ³n de OAuth 2.0. Con este flujo, el servidor que aloja la pĆ”gina web debe ser capaz de proteger la identidad de la aplicaciĆ³n conectada, definida por el Id. del cliente y el secreto de cliente.
Ediciones necesarias
| Disponible en: Salesforce Classic (no disponible en todas las organizaciones) y Lightning Experience |
| Disponible en: todas las ediciones |
Consulte Las nuevas aplicaciones conectadas ya no se pueden crear en Spring ā26 para obtener mĆ”s detalles.
Recomendamos que utilice el flujo de servidor web con Clave de prueba para Code for Exchange (PKCE, pronosticado pixi) en lugar del flujo usuario-agente o el flujo nombre de usuario-contraseƱa para escenarios especiales. Utilice los parĆ”metros code_challenge y code_verifier para implementar PKCE con el flujo de servidor web. Para obtener mĆ”s informaciĆ³n sobre PKCE, consulte Grupo de tareas de ingenierĆa de Internet (IETF.). TambiĆ©n recomendamos que bloquee todas las aplicaciones conectadas utilizando el flujo usuario-agente. Para los pasos, consulte Bloquear flujos de autorizaciĆ³n para mejorar la seguridad.
Este es un caso de uso de ejemplo para implementar el flujo servidor web. Recientemente desarrollĆ³ un servicio web que permite el acceso seguro al estado de pedidos de clientes. Los datos de estado del pedido se almacenan de forma segura en su plataforma de CRM de Salesforce. Para autorizar a los usuarios del Centro de ayuda a ver el estado del pedido de un cliente, desarrolla una aplicaciĆ³n Estado de pedido y la configura como una aplicaciĆ³n conectada con el flujo del servidor web.
- Un usuario del Centro de ayuda hace clic en la aplicaciĆ³n web Estado de pedido.
- La aplicaciĆ³n conectada publica una solicitud de cĆ³digo de autorizaciĆ³n en el extremo de autorizaciones de Salesforce.
- Se redirige al usuario a la pĆ”gina de inicio de sesiĆ³n de Salesforce. DespuĆ©s de un inicio de sesiĆ³n satisfactorio, se solicita al usuario que apruebe el acceso de la aplicaciĆ³n a los datos del estado del pedido.
- DespuĆ©s de que el usuario apruebe que la aplicaciĆ³n Estado de pedido acceda a los datos, Salesforce envĆa una devoluciĆ³n de llamada a la aplicaciĆ³n Estado de pedido con un cĆ³digo de autorizaciĆ³n.
- La aplicaciĆ³n Estado de pedido pasa el cĆ³digo de autorizaciĆ³n al extremo de tokens de Salesforce, solicitando un token de acceso.
- Salesforce valida el cĆ³digo de autorizaciĆ³n y envĆa de vuelta un token de acceso que incluye permisos asociados en la forma de Ć”mbitos.
- La aplicaciĆ³n Estado de pedido envĆa una solicitud de vuelta a Salesforce para acceder a los datos de estado del pedido. La solicitud incluye el token de acceso con los Ć”mbitos asociados.
- Salesforce valida el token de acceso y los Ɣmbitos asociados.
- La aplicaciĆ³n Estado de pedido puede acceder a los datos protegidos, y el estado del pedido del cliente se muestra en la aplicaciĆ³n.Nota Si el token d acceso deja de ser vĆ”lido, la aplicaciĆ³n conectada puede utilizar un token de actualizaciĆ³n para obtener un nuevo token de acceso.
Echemos un vistazo con detalle a cada paso de este flujo de autorizaciĆ³n.
- Solicitar un cĆ³digo de autorizaciĆ³n
- El usuario autentica y autoriza el acceso
- Salesforce otorga el cĆ³digo de autorizaciĆ³n
- Solicitar un token de acceso
- Salesforce otorga un token de acceso
Solicitar un cĆ³digo de autorizaciĆ³n
Para iniciar el flujo de servidor web de OAuth 2.0, el servicio web externo (a travĆ©s de la aplicaciĆ³n conectada), publica una solicitud de cĆ³digo de autorizaciĆ³n empleando el tipo de otorgamiento de cĆ³digo de autorizaciĆ³n al extremo de autorizaciones de Salesforce. Con un cĆ³digo de autorizaciĆ³n, la aplicaciĆ³n conectada puede probar que fue autorizada como visitante seguro en el 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.
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 conectadas envĆan solicitudes de autorizaciĆ³n de OAuth a este extremo. |
client_id
|
Haga clic en la clave de consumidor de la aplicaciĆ³n conectada. Para acceder a la clave de consumidor, desde el Gestor de aplicaciones, busque la aplicaciĆ³n conectada y seleccione Ver desde el menĆŗ desplegable. A continuaciĆ³n haga clic en Gestionar detalles 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 conectada. De lo contrario, la aprobaciĆ³n falla. Puede encontrar el URI de redireccionamiento en la pĆ”gina Gestionar aplicaciones conectadas de la aplicaciĆ³n conectada o en la definiciĆ³n de la aplicaciĆ³n conectada. Este valor debe tener codificaciĆ³n de URL. |
response_type
|
El tipo de otorgamiento de OAuth 2.0 que solicita la aplicaciĆ³n conectada. El valor para este flujo debe ser code para indicar que la aplicaciĆ³n conectada 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
|
Los permisos que definen el tipo de recursos protegidos a los que la aplicaciĆ³n conectada puede acceder. Usted asigna Ć”mbitos a una aplicaciĆ³n conectada cuando la construye, 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 conectada. Los Ć”mbitos que se hayan pasado en este parĆ”metro deben ser un subconjunto de los Ć”mbitos registrados. |
sso_provider
|
El nombre del desarrollador de un proveedor de identidad de inicio de sesiĆ³n Ćŗnico (SSO) configurado con una URL de inicio de sesiĆ³n de Mi dominio o una URL de sitio de Experience Cloud. Puede utilizar este parĆ”metro para crear una experiencia de SSO que hace parecer que su aplicaciĆ³n estĆ” integrada con el proveedor de SSO. Por ejemplo, puede utilizar este parĆ”metro para ofrecer SSO en una implementaciĆ³n de Identidad desatendida. |
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 las aplicaciones conectadas, se solicita a los usuarios que se estĆ”n autenticando que inicien 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 conectada, Salesforce redirige a los usuarios a la URL de devoluciĆ³n de llamadas, 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 conectada.
https://www.mycustomerorderstatus.com/oauth2/callback. - La segunda parte es el cĆ³digo de autorizaciĆ³n que la aplicaciĆ³n conectada 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 conectada pasa el cĆ³digo de autorizaciĆ³n al extremo de tokens de Salesforce como una operaciĆ³n POST de 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=authorization_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 conectada puede proporcionar para probar que es un visitante seguro. Para el flujo de servidor web, el valor debe ser authorization_code. |
code
|
Un cĆ³digo de autorizaciĆ³n temporal recibido del servidor de autorizaciĆ³n. La aplicaciĆ³n conectada utiliza este cĆ³digo como intercambio por 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
|
Haga clic en la clave de consumidor de la aplicaciĆ³n conectada. Para acceder a la clave de consumidor, desde el Gestor de aplicaciones, busque la aplicaciĆ³n conectada y seleccione Ver desde el menĆŗ desplegable. A continuaciĆ³n haga clic en Gestionar detalles de consumidor. A veces se le solicita verificar su identidad antes de poder ver la clave de consumidor. |
client_secret
|
Haga clic en el secreto de consumidor de la aplicaciĆ³n conectada. Para acceder al secreto de consumidor, desde el Gestor de aplicaciones, busque la aplicaciĆ³n conectada y seleccione Ver desde el menĆŗ desplegable. A continuaciĆ³n haga clic en Gestionar detalles 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 conectada no tenga Requerir secreto para flujo de servidor web activado. Si no se requiere |
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 conectada. De lo contrario, la aprobaciĆ³n falla. Puede encontrar el URI de redireccionamiento en la pĆ”gina Gestionar aplicaciones conectadas de la aplicaciĆ³n conectada o en la definiciĆ³n de la aplicaciĆ³n conectada. 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.
|
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_secret.Si proporciona client_assertion en vez de client_secret, el valor de client_assertion debe incluir estos parƔmetros.
iss:client_idde la definiciĆ³n de la aplicaciĆ³n conectada.sub:client_idde la definiciĆ³n de la aplicaciĆ³n conectada.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=authorization_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 conectada, devuelve 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 incluye estos parƔmetros:
| ParĆ”metro | DescripciĆ³n |
|---|---|
access_token
|
Token de OAuth que una aplicaciĆ³n conectada utiliza para solicitar el acceso a un recurso protegido en nombre de una 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 conectada cuando la construye, y se incluyen con los tokens de OAuth durante el flujo de autorizaciĆ³n. |
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. |
La respuesta tambiƩn puede contener estos parƔmetros.
