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 aplicaciĆ³n web debe poder proteger la identidad de la aplicaciĆ³n cliente externa, definida por el Id. de 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 |
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 cliente externas para que no utilicen el flujo usuario-agente o el flujo nombre de usuario-contraseƱa. 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 Servicio de asistencia a ver el estado de pedidos de un cliente, desarrolla una aplicaciĆ³n Estado de pedido y la configura como una aplicaciĆ³n cliente externa con el flujo de servidor web.
- Un usuario del Centro de ayuda hace clic en la aplicaciĆ³n web Estado de pedido.
- La aplicaciĆ³n cliente externa publica una solicitud de cĆ³digo de autorizaciĆ³n en el extremo de autorizaciĆ³n 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 de acceso deja de ser vĆ”lido, la aplicaciĆ³n cliente externa 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 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.
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 aplicaciones, busque la aplicaciĆ³n cliente externa 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 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. |
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. Para obtener mĆ”s informaciĆ³n, consulte Crear una experiencia de inicio de sesiĆ³n Ćŗnico nativa en su aplicaciĆ³n. |
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 es necesario si se especifica un verificador
|
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, por ejemplo, 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 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 identificador UVID en el cuerpo de la solicitud, tambiƩn puede lo pasar 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 consola original, el estado especificado se pasa en el 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=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 cliente externa 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 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 aplicaciones, busque la aplicaciĆ³n cliente externa 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
|
Secreto de consumidor de la aplicaciĆ³n cliente externa. Para acceder al secreto de consumidor, desde el Gestor de aplicaciones, busque la aplicaciĆ³n cliente externa 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 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 de |
code_verifier
|
Solo es necesario 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 sea difĆcil adivinar el valor de
|
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: 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.
La 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 cliente externa, 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 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 direcciĆ³n URL de identidad no ha cambiado 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. |
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. 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 incluyen 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.
