APIs de identidade autônomos: Fluxo de credenciais e código de autorização para clientes públicos

Um componente-chave desse fluxo é o JavaScript do lado do cliente que envia a solicitação de autorização, realiza a troca de código e processa o token de acesso. Aqui está um exemplo de JavaScript que usa um aplicativo conectado.

var clientId = "<Connected App Client ID>";
var baseURL = "<Experience Cloud Domain>";
var redirectURL = "<Experience Cloud Domain>/services/apexrest/code/extraction"
      
// Performs the code exchange
function doCodeExchange(authorizeResponse) {
   //Perform Code Exchange
   //Get Access Token
   var client = new XMLHttpRequest();
   client.open("POST", authorizeResponse.sfdc_community_url + "/services/oauth2/token", true);
   client.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");
   client.send("code=" + authorizeResponse.code + "&grant_type=authorization_code&client_id=" + clientId + "&redirect_uri=" + redirectURL);
   client.onreadystatechange = function() {
       if(this.readyState == 3) {
           response = JSON.parse(client.response);
           getUserInfo(response.access_token, response.sfdc_community_url)
       }
   }
}

// Gets User Info
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";
       }
   }
}

//Starts the Login Process
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) {
           response = JSON.parse(client.response);
           doCodeExchange(response);
       }
   }
   return false;
}    

Outro componente-chave é o manipulador de retorno de chamada no lado do servidor, que extrai o código do redirecionamento 302 e o retorna ao aplicativo. Neste exemplo, o manipulador é uma classe do Apex exposta como um ponto final REST público e o Compartilhamento de recurso entre origens (CORS) está habilitado para oferecer proteção de script entre sites. Para simplificar o desenvolvimento, use o ponto final de eco OAuth 2.0 para obter o código de autorização.

@RestResource(urlMapping='/code/extraction')
global class CodeExtractorAPI {
  
   @HttpGet
   global static CodeResponse doGet() {
       RestRequest req = RestContext.request;
       RestResponse res = RestContext.response;
       try {
           res.statusCode = 200;
           return new CodeResponse(req.params.get('code'), req.params.get('sfdc_community_url'), req.params.get('sfdc_community_id'), req.params.get('state'));
       } catch (Exception e) {
           res.statusCode = 500;
           return new CodeResponse('Could not parse auth code redirect URI');
       }
      
   }
  
   // Response Wrapper
   global class CodeResponse {
       String code;
       String sfdc_community_url;
       String sfdc_community_id;
       String state;
       Boolean success;
       String errMsg;
      
       public CodeResponse(String code, String sfdc_community_url, String sfdc_community_id, String state) {
           this.code = code;
           this.sfdc_community_url = sfdc_community_url;
           this.sfdc_community_id = sfdc_community_id;
           this.state = state;
           this.success = true;
       }
      
        public CodeResponse(String errMsg) {
           this.success = false;
           this.errMsg = this.errMsg;
       }       
   }
}

O usuário final abre o aplicativo de terceiros e faz login

O usuário abre o aplicativo de terceiros para fazer login. No seu aplicativo, seu formulário de login é exibido com campos de nome de usuário e senha e um botão de login. O Salesforce não fornece esse formulário de login. A aparência dele depende de você. O usuário insere o nome de usuário e a senha e clica no botão de login.

O aplicativo de terceiros gera valores de code_verifier e code_challenge (opcional)

Se estiver usando a extensão Chave de comprovação para Code Exchange (PKCE), o aplicativo gerará valores usados para verificar o código de autorização.

Seu fluxo incluirá essa etapa somente se você estiver usando a extensão Chave de comprovação para Code Exchange (PKCE). Como uma prática recomendada de segurança, recomendamos enfaticamente usar a extensão PKCE ao implementar o Fluxo de código e credenciais de autorização, especialmente para aplicativos de página única. Para obter mais informações sobre a PKCE, consulte a especificaçãoRFC 7636: Chave de prova para troca de código por clientes públicos da OAuth fornecida pela Internet Engineering Task Force (IETF).

A especificação PKCE definida em RFC 7636 também inclui um parâmetro code_challenge_method opcional que pode ser enviado na solicitação de autorização. O Salesforce ignora qualquer valor enviado nesse parâmetro e o padrão é SHA256.

O aplicativo de terceiros envia uma solicitação autônoma de código de autorização

No navegador, seu aplicativo personalizado, por meio de JavaScript, envia uma solicitação autônoma de código de autorização para o ponto final de autorização da API de Login autônomo do Salesforce. Se você não estiver usando a descoberta autônoma de usuário, poderá usar o método GET ou POST para essa solicitação. Se você estiver usando a descoberta autônoma de usuário, somente solicitações POST terão suporte.

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 solicitações GET e POST, é necessário incluir o cabeçalho Auth-Request-Type: Named-User.

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.MyExperienceCloudSite.my.site.com/services/apexrest/code/extraction&
client_id=******&
code_challenge=Y29kZ*******

Se estiver usando uma solicitação POST, poderá incluir as credenciais de usuário com codificação Base64 em um cabeçalho de autorização ou colocar no corpo da solicitação.

Se estiver usando a descoberta autônoma de usuário, você não enviará um nome de usuário e uma senha. Em vez disso, você envia um identificador no parâmetro login_hint, dados personalizados opcionais e uma senha. Inclua o identificador, os dados personalizados e a senha no corpo de uma solicitação POST. Não use uma solicitação GET.

Opcionalmente, para conectar esse fluxo ao fluxo de convidado autônomo, você pode incluir um cabeçalho Uvid-Hint com um token de acesso baseado em JWT com um valor UVID, que é um identificador universalmente exclusivo (UUID) versão 4 gerado e gerenciado totalmente pelo seu aplicativo. Para obter um token de acesso com um UVID, você deve habilitar seu aplicativo cliente externo ou aplicativo conectado para emitir tokens de acesso baseados em JWT e implementar o fluxo de convidado autônomo em seu aplicativo.

Se implementar o fluxo de usuário convidado no seu aplicativo, como opção, você poderá usar esse cabeçalho para passar em um token de acesso baseado em JSON Web Token (JWT) contendo um ID do visitante exclusivo (UVID) vinculado à identidade de um usuário convidado. Ao passar o UVID para um fluxo de usuário nomeado, você pode trazer informações contextuais de uma sessão do usuário convidado, como as preferências de cookies do usuário, para uma sessão do usuário nomeado.

Também é possível incluir o valor simples do UVID no corpo da solicitação.

Nota Se tiver a configuração Exigir credenciais de usuário no corpo POST para o Fluxo de código e credenciais de autorização no aplicativo cliente externo ou conectado, poderá enviar as credenciais de usuário apenas no corpo da solicitação. Com essa configuração habilitada, não é possível usar o método GET para a solicitação de código de autorização. Você pode usar apenas o método POST.

Para os métodos GET e POST, inclua estes parâmetros obrigatórios no corpo da solicitação de autorização.

Você também pode incluir estes parâmetros opcionais na solicitação de autorização.

(Opcional) O Manipulador de descoberta autônoma de usuário encontra o usuário

Se você estiver usando um manipulador autônomo de descoberta de usuário, o manipulador pega os parâmetros login_hint e customdata e encontra o usuário associado. O manipulador confirma que o endereço de email ou número de telefone do usuário foi verificado.

Para obter um exemplo de manipulador, consulte Auth.HeadlessUserDiscoveryHandler.

O Salesforce valida as credenciais e retorna um redirecionamento 302 ao manipulador de retorno de chamada no lado do servidor

A API de Login autônomo do Salesforce recebe a solicitação de autorização. Ela valida as credenciais do usuário e retorna um redirecionamento HTTP 302 para um URL pré-configurado que contém o código de autorização. Em seguida, o Salesforce envia automaticamente a resposta de redirecionamento para o URL de redirecionamento, que aponta para o manipulador de retorno de chamada no lado do servidor no ponto de extremidade de /code/extraction, neste exemplo. Durante esse processo, o navegador não é redirecionado, tudo acontece nos bastidores.

O manipulador de retorno de chamada no lado do servidor extrai código e o retorna para o aplicativo

@RestResource(urlMapping='/code/extraction')
global class CodeExtractorAPI {
  
   @HttpGet
   global static CodeResponse doGet() {
       RestRequest req = RestContext.request;
       RestResponse res = RestContext.response;
       try {
           res.statusCode = 200;
           return new CodeResponse(req.params.get('code'), req.params.get('sfdc_community_url'), req.params.get('sfdc_community_id'), req.params.get('state'));
       } catch (Exception e) {
           res.statusCode = 500;
           return new CodeResponse('Could not parse auth code redirect URI');
       }
      
   }
The response wrapper sets the variables for the code response, including success and error indicators.
// Response Wrapper
   global class CodeResponse {
       String code;
       String sfdc_community_url;
       String sfdc_community_id;
       String state;
       Boolean success;
       String errMsg;
      
       public CodeResponse(String code, String sfdc_community_url, String sfdc_community_id, String state) {
           this.code = code;
           this.sfdc_community_url = sfdc_community_url;
           this.sfdc_community_id = sfdc_community_id;
           this.state = state;
           this.success = true;
       }
      
        public CodeResponse(String errMsg) {
           this.success = false;
           this.errMsg = this.errMsg;
       }       
   }

<?
header('Access-Control-Allow-Headers: *');
header('Access-Control-Allow-Origin: *');
header('Content-Type: application/json; charset=utf-8');
$out = [];
foreach ($_GET as $name => $value) {
   $out[$name] = $value;
}
echo json_encode($out);
?>

Após extrair o código, o manipulador de retorno de chamada envia-o de volta para o navegador.

O aplicativo recebe a resposta do código e realiza a troca de códigos

{"success":true,"state":"https://MyExperienceCloudSite.my.site.com/","sfdc_community_url":"https://MyExperienceCloudSite.my.site.com/vforcesite","sfdc_community_id":"0DBxxxxxxxxxxxx","errMsg":null,"code":"aPrxC1*******"}

O navegador solicita de modo autônomo a troca do código por um token de acesso. No exemplo de JavaScript no lado do cliente, a função doCodeExchange envia o código em uma solicitação POST para o ponto de extremidade de token do Experience Cloud.

var clientId = "<Connected App Client ID>";
var baseURL = "<Experience Cloud Domain>";
var redirectURL = "<Experience Cloud Domain>/services/apexrest/code/extraction"
      
// Performs the code exchange
function doCodeExchange(authorizeResponse) {
   //Perform Code Exchange
   //Get Access Token
   var client = new XMLHttpRequest();
   client.open("POST", authorizeResponse.sfdc_community_url + "/services/oauth2/token", true);
   client.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");
   client.send("code=" + authorizeResponse.code + "&grant_type=authorization_code&client_id=" + clientId + "&redirect_uri=" + redirectURL);
   client.onreadystatechange = function() {
       if(this.readyState == 3) {
           response = JSON.parse(client.response);
           getUserInfo(response.access_token, response.sfdc_community_url)
       }
   }
} 

Para a solicitação de token de acesso, você pode usar apenas uma solicitação POST. Não há suporte para solicitações GET. Você deve incluir um cabeçalho Content-Type. Inclua estes parâmetros obrigatórios no corpo da solicitação.

Você também pode incluir estes parâmetros opcionais na solicitação de token.

O Salesforce concede um token de acesso

{
"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"
}

A resposta do token de acesso contém estes parâmetros obrigatórios.

A resposta do token de acesso também pode incluir estes parâmetros.

O aplicativo processa a resposta do token e cria a sessão do usuário

O navegador armazena as informações da resposta do token e cria a sessão do usuário. Nesse ponto, o usuário está conectado e o JavaScript do lado do cliente chama o ponto final de Informações do usuário do Salesforce para confirmar que o login foi bem-sucedido, como mostrado neste fragmento.

Nota Conclua uma revisão de segurança completa do seu armazenamento de token de acesso. Nunca armazene o token de acesso no armazenamento local do navegador e evite armazená-lo em um cookie, se possível.

// Gets User Info
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";
       }
   }
}

O usuário final está conectado e executa uma ação no aplicativo

O usuário agora está conectado. Ele executa uma ação no seu aplicativo que requer acesso a dados do Salesforce. Por exemplo, ele clica em um botão para visualizar seu histórico de reservas de viagem, que é armazenado no Salesforce.

Nota Ao configurar seu aplicativo cliente externo ou aplicativo conectado para o Fluxo de código e credenciais de autorização, você configura a política Usuários permitidos como Usuários aprovados pelo administrador são pré-autorizados e configura quais perfis ou conjuntos de permissões podem acessar o aplicativo. Com essa política, os usuários acessam o aplicativo sem autorizá-lo, portanto, eles não recebem uma tela de autorização solicitando que eles permitam que o aplicativo acesse seus dados.

O aplicativo faz uma chamada autenticada para um ponto final do Salesforce

Para acessar os dados do Salesforce do usuário, o aplicativo usa o token de acesso para fazer uma chamada autenticada para um ponto de extremidade do Salesforce protegido, como uma API do Salesforce.

O usuário final pode acessar os dados do Salesforce

Agora o cliente pode acessar os dados protegidos do Salesforce em seu aplicativo. Por exemplo, ele pode ver seu histórico de reservas de viagem. Da perspectiva do usuário final, todo o processo, desde o login até o acesso aos dados, ocorreu sem exigir que o usuário saia do aplicativo.