API de identidad desatendida: Flujo Código de autorización y credenciales para clientes privados

Un componente clave de este flujo es JavaScript del lado del cliente que solicita autorización y recibe la respuesta del token de acceso. Este ejemplo utiliza una aplicación conectada.

var clientId = '<Connected App Client ID>';
var baseURL = '<Experience Cloud Domain>';
var redirectURL = '<Experience Cloud Domain>/services/apexrest/code/exchange';

function getUserInfo(accessToken, userInfoBaseURL) {
   var client = new XMLHttpRequest();
   client.open("GET", userInfoBaseURL + "/services/oauth2/userinfo", true);
   client.setRequestHeader("Content-Type", "application/json");
   client.setRequestHeader("Authorization", "Bearer " + accessToken);
   client.send();
   client.onreadystatechange = function() {
       if(this.readyState == 3) {
           response = JSON.parse(client.response);
           response.access_token = accessToken;
           document.getElementById("json").textContent = JSON.stringify(response, undefined, 2);
           document.getElementById("results").style.display="block";
       }
   }
}

function startLogin() {
   var username = document.getElementById('user_name').value;
   var password = document.getElementById('password').value;
   var encodedUNP = btoa(username + ':' + password);
   var client = new XMLHttpRequest();
   client.open("POST", baseURL + "/services/oauth2/authorize", true);
   client.setRequestHeader("Auth-Request-Type", "Named-User");
   client.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");
   client.setRequestHeader("Authorization", "Basic " + encodedUNP);
   client.send("response_type=code_credentials&client_id=" + clientId + "&redirect_uri=" + redirectURL);
   client.onreadystatechange = function() {
       if(this.readyState == 3) {
           console.log("here");
           console.log(client.response);
           response = JSON.parse(client.response);
           if (response.success) {
               getUserInfo(response.access_token, baseURL);
           }
       }
   }
   return false;
}    

Otro componente clave es el controlador de devolución de llamada del lado del servidor, que extrae el código y lo intercambia por un token de acceso. Este es un ejemplo de controlador de devolución de llamada utilizando una clase de Apex expuesta como un recurso de REST.

@RestResource(urlMapping='/code/exchange')
global class CodeExchangeAPI {
  
   @HttpGet
   global static ExchangeResponse doGet() {
       RestRequest req = RestContext.request;
       RestResponse res = RestContext.response;
       try {
           res.statusCode = 200;
          
              String accessToken = doCodeExchange(req.params.get('code'), req.params.get('sfdc_community_url'));
           if (accessToken != null) {
                return new ExchangeResponse(accessToken, req.params.get('state'));
           } else {
               return new ExchangeResponse('Could not parse auth code redirect URI');
           }
       } catch (Exception e) {
           res.statusCode = 500;
           return new ExchangeResponse('Could not parse auth code redirect URI');
       }
      
   }
  
  
   global static String doCodeExchange(String code, String communityURL) {
       String clientId = 'Connected App Client ID';
       String redirectURL = '<Experience Cloud Domain>/services/apexrest/code/exchange';
       String clientSecret = null;
      
       Http h = new Http();
       HttpRequest req = new HttpRequest();
       req.setMethod('POST');
      
       //Create Code Exchange URL
       String url = communityURL + '/services/oauth2/token';
       req.setEndpoint(url);
      
       //Post Body
       String body = 'grant_type=authorization_code';
       body = body + '&client_id=' + clientId;
       body = body + '&code=' + code;
       if (clientSecret != null) {
          body = body + '&client_secret=' + clientSecret;
       }
       body = body + '&redirect_uri=' + redirectURL;
      
       //URL encode Post Body
       String encodedBody = EncodingUtil.urlEncode(body, 'UTF-8');
      
       // Set request body
       req.setBody(body);
      
       //Add Headers
       req.setHeader('Content-Type','application/x-www-form-urlencoded');
      
       //Send Token Request
       HttpResponse res = h.send(req);
      
       if (res.getStatusCode() == 200) {
           //Extract Token from Response
           Map<String,Object> tokenResponseMap = (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
           return (String)tokenResponseMap.get('access_token');
       } else {
           return null;
       }
   }
  
   // Response Wrapper
   global class ExchangeResponse {
       String access_token;
       String state;
       String errMsg;
       Boolean success; 
      
       public ExchangeResponse(String access_token, String state) {
           this.access_token = access_token;
           this.state = state;
           this.success = true;
       }
      
        public ExchangeResponse(String errMsg) {
           this.success = false;
           this.errMsg = this.errMsg;
       }       
   }
}

Este es un desglose detallado de este flujo.

El usuario final abre la aplicación externa e inicia sesión

Su usuario abre su aplicación externa para 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.

La aplicación externa genera valores code_verifier y code_challenge (opcional)

Si está utilizando la extensión Proof Key for Code Exchange (PKCE), la aplicación genera valores utilizados para verificar el código de autorización.

Como mejor práctica de seguridad, recomendamos encarecidamente el uso de la extensión PKCE cuando implemente el flujo Código de autorización y credenciales. 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.

Cuando implemente este flujo empleando un controlador de devolución de llamadas del lado del servidor, active los parámetros Requerir secreto para flujo de servidor web y Requerir secreto para flujo de token de actualización en su aplicación cliente externa o aplicación conectada. Con estos parámetros activados, asegúrese de que su controlador de devolución de llamada mantiene el secreto de consumidor seguro.

La aplicación externa realiza una solicitud desatendida de un código de autorización

Desde el navegador, la aplicación externa envía una solicitud de autorización desatendida al extremo de autorización de la API de inicio de sesión desatendido en su sitio de Experience Cloud utilizando Java asíncrono y XML (AJAX). Si no está utilizando descubrimiento de usuarios desatendidos, puede utilizar el método GET o POST para esta solicitud. Si está utilizando descubrimiento de usuarios desatendidos, solo se admiten solicitudes POST.

function startLogin() {
   var username = document.getElementById('user_name').value;
   var password = document.getElementById('password').value;
   var encodedUNP = btoa(username + ':' + password);
   var client = new XMLHttpRequest();
   client.open("POST", baseURL + "/services/oauth2/authorize", true);
   client.setRequestHeader("Auth-Request-Type", "Named-User");
   client.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");
   client.setRequestHeader("Authorization", "Basic " + encodedUNP);
   client.send("response_type=code_credentials&client_id=" + clientId + "&redirect_uri=" + redirectURL);
   client.onreadystatechange = function() {
       if(this.readyState == 3) {
           console.log("here");
           console.log(client.response);
           response = JSON.parse(client.response);
           if (response.success) {
               getUserInfo(response.access_token, baseURL);
           }
       }
   }
   return false;
}  

Para solicitudes GET y POST, debe incluir el encabezado Auth-Request-Type: Named-User:

Opcionalmente, para conectar este flujo al flujo de invitados desatendido, puede incluir un encabezado Uvid-Hint con un token de acceso basado en JWT que contiene un valor UVID, que es un identificador exclusivo universal (UUID) de versión 4 que genera y gestiona completamente por su aplicación. Para obtener un token de acceso con un UVID, debe activar su aplicación cliente externa o aplicación conectada para emitir tokens de acceso basados en JWT e implementar el flujo de invitados desatendido en su aplicación.

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.

También puede incluir el valor UVID sin formato en el cuerpo de la solicitud.

GET /services/oauth2/authorize? HTTP 1.1
Host: MyDomainName.my.site.com
Auth-Request-Type: Named-User
Authorization: Basic <encoded username:password>

response_type=code_credentials&
redirect_uri=https://www.MyDomainName.my.site.com/services/apexrest/code/exchange&
client_id=******&
code_challenge=Y29kZ*******

Si está utilizando una solicitud POST, puede incluir las credenciales de usuario con codificación Base64 en un encabezado de autorización o puede ponerlas en el cuerpo de la solicitud.

Si está utilizando descubrimiento de usuarios desatendidos, no envía un nombre de usuario y una contraseña. En su lugar, envía un identificador en el parámetro login_hint, datos personalizados opcionales y una contraseña. Incluya el identificador, los datos personalizados y la contraseña en el cuerpo de una solicitud POST. No utilice una solicitud GET.

Nota Si tiene la configuración Requerir credenciales de usuario en el cuerpo POST para el flujo Código de autorización y credenciales activada en su aplicación cliente externa o aplicación conectada, puede enviar las credenciales de usuario solo en el cuerpo de solicitud. Con esta configuración activada, no puede utilizar el método GET para la solicitud del código de autorización. Solo puede utilizar el método POST.

Para los métodos GET y POST, incluya estos parámetros obligatorios en el cuerpo de la solicitud de autorización.

También puede incluir estos parámetros opcionales en la solicitud de autorización.

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

Salesforce valida las credenciales y devuelve un redireccionamiento 302

https://www.MyDomainName.my.site.com/services/apexrest/code/exchange?code=aPrxC1*******
&sfdc_community_url=https%3A%2F%2FMyDomainName.my.site.com&sfdc_community_id=0DBxxxxxxxxxxxx

El controlador de devolución de llamadas extrae el código y realiza el intercambio de códigos

El controlador de devolución de llamadas del lado del servidor extrae el código de autorización y otros parámetros de la de redireccionamiento 302. A continuación inicia el intercambio de códigos enviando una solicitud POST sin encabezado al extremo del token.

@RestResource(urlMapping='/code/exchange')
global class CodeExchangeAPI {
  
   @HttpGet
   global static ExchangeResponse doGet() {
       RestRequest req = RestContext.request;
       RestResponse res = RestContext.response;
       try {
           res.statusCode = 200;
          
              String accessToken = doCodeExchange(req.params.get('code'), req.params.get('sfdc_community_url'));
           if (accessToken != null) {
                return new ExchangeResponse(accessToken, req.params.get('state'));
           } else {
               return new ExchangeResponse('Could not parse auth code redirect URI');
           }
       } catch (Exception e) {
           res.statusCode = 500;
           return new ExchangeResponse('Could not parse auth code redirect URI');
       }
      
   }

global static String doCodeExchange(String code, String communityURL) {
       String clientId = 'Connected App Client ID';
       String redirectURL = '<Experience Cloud Domain>/services/apexrest/code/exchange';
       String clientSecret = '<ConnecedApp Secret>';
      
       Http h = new Http();
       HttpRequest req = new HttpRequest();
       req.setMethod('POST');
      
       //Create Code Exchange URL
       String url = communityURL + '/services/oauth2/token';
       req.setEndpoint(url);
      
       //Post Body
       String body = 'grant_type=authorization_code';
       body = body + '&client_id=' + clientId;
       body = body + '&code=' + code;
       if (clientSecret != null) {
          body = body + '&client_secret=' + clientSecret;
       }
       body = body + '&redirect_uri=' + redirectURL;
      
       //URL encode Post Body
       String encodedBody = EncodingUtil.urlEncode(body, 'UTF-8');
      
       // Set request body
       req.setBody(body);
      
       //Add Headers
       req.setHeader('Content-Type','application/x-www-form-urlencoded');
      
       //Send Token Request
       HttpResponse res = h.send(req);
      
       if (res.getStatusCode() == 200) {
           //Extract Token from Response
           Map<String,Object> tokenResponseMap = (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
           return (String)tokenResponseMap.get('access_token');
       } else {
           return null;
       }
   }

Para la solicitud de token de acceso, solo puede utilizar una solicitud POST: no se admiten las solicitudes GET. Debe incluir un encabezado Content-Type. Incluya estos parámetros obligatorios en el cuerpo de la solicitud.

También puede incluir estos parámetros opcionales en la solicitud de token.

 // Response Wrapper
   global class ExchangeResponse {
       String access_token;
       String state;
       String errMsg;
       Boolean success; 
      
       public ExchangeResponse(String access_token, String state) {
           this.access_token = access_token;
           this.state = state;
           this.success = true;
       }
      
        public ExchangeResponse(String errMsg) {
           this.success = false;
           this.errMsg = this.errMsg;
       }       
   }

Salesforce otorga un token de acceso

{
"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 obligatorios.

La respuesta del token de acceso también puede incluir estos parámetros.

El controlador de devolución de llamadas procesa la respuesta de tokens y devuelve parámetros a la aplicación

//Send Token Request
       HttpResponse res = h.send(req);
      
       if (res.getStatusCode() == 200) {
           //Extract Token from Response
           Map<String,Object> tokenResponseMap = (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
           return (String)tokenResponseMap.get('access_token');
       } else {
           return null;
       }

El controlador de devolución de llamadas del lado del servidor devuelve el token de acceso y el estado al navegador, junto con datos de usuario, tokens y datos de sesión. En nuestro ejemplo, el contenedor de respuesta devuelve el token de acceso a la aplicación. Como mejor práctica, recomendamos que configure su servidor para almacenar el token de acceso, cree una sesión para la aplicación y devuelva la sesión a la aplicación, en vez de devolver el token de acceso. Como desarrollador, está al completo del control de la creación de la sesión, el almacenamiento del token de acceso y la gestión del estado de inicio de sesión, de modo que su implementación específica depende de usted.

{"success":true,"state":"https://MyExperienceCloudSite.my.site.com/","errMsg":null,"access_token":"00*******"}

La aplicación procesa la respuesta del token y crea la sesión de usuario

function getUserInfo(accessToken, userInfoBaseURL) {
   var client = new XMLHttpRequest();
   client.open("GET", userInfoBaseURL + "/services/oauth2/userinfo", true);
   client.setRequestHeader("Content-Type", "application/json");
   client.setRequestHeader("Authorization", "Bearer " + accessToken);
   client.send();
   client.onreadystatechange = function() {
       if(this.readyState == 3) {
           response = JSON.parse(client.response);
           response.access_token = accessToken;
           document.getElementById("json").textContent = JSON.stringify(response, undefined, 2);
           document.getElementById("results").style.display="block";
       }
   }
}

El usuario final inicia sesión y realiza una acción en la aplicación

El usuario final ahora inició sesión. 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 reserva de viajes, 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.

La aplicación externa 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.

El usuario final 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 reserva de viajes. Desde la perspectiva del usuario final, 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.