OAuth 2.0 para aplicativos de primeira parte: Fluxo de nome de usuário autônomo – senha para clientes particulares

Etapa 1: o usuário final abre o aplicativo de primeira parte e faz login

Um usuário final abre seu aplicativo de primeira parte com a intenção de fazer login. No aplicativo, seu formulário de login aparece mostrando 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.

Etapa 2: O aplicativo de primeira parte cria um JWT de atestado do cliente e gera valores de code_verifier e code_challenge

O aplicativo lembra um JWT de atestado do cliente.

O aplicativo também gera valores para os parâmetros de PKCE usados para verificar o código de autorização.

Nota Recomendamos enfaticamente que você sempre implemente a PKCE para esse fluxo. Caso contrário, você não obterá seus benefícios de segurança.

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.

Etapa 3: o aplicativo de primeira parte solicita um código de autorização autônomo

No navegador, seu aplicativo envia as credenciais do usuário, juntamente com outros parâmetros, para o ponto de extremidade services/oauth2/v1/authorization_challenge em seu site do Experience Cloud por meio de uma solicitação POST autônoma.

Não há cabeçalhos obrigatórios para essa solicitação. 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 contendo um valor de ID de visitante exclusivo (UVID).

Inclua estes parâmetros no corpo da solicitação.

Aqui está um exemplo de solicitação para o ponto final de desafio de autorização.

POST /services/oauth2/v1/authorization_challenge? HTTP 1.1
Host: MyExperienceCloudSite.my.site.com

username=janice.edwards@example.com&
password=*****&
client_assertion=******&
recaptcha=********&
scope=profile&
code_challenge=********

Etapa 4: o Salesforce valida a solicitação

O Salesforce primeiro tenta validar o JWT de atestado do cliente validando se a assinatura passada no parâmetro client_asssertion corresponde à assinatura do certificado configurado para o aplicativo cliente externo.

Se o JWT de atestado do cliente não for válido, o Salesforce retornará um erro invalid_attestation e você deverá reenviar a solicitação com todos os parâmetros enviados originalmente. Aqui está um exemplo de resposta de erro.

HTTP/1.1 403 Forbidden
Content-Type: application/json
Cache-Control: no-store

{
  "error": "invalid_attestation",
  "error_code": "client_attestation_failed"
}

Se o JWT de atestado do cliente for válido, mas houver outros problemas com a solicitação, o Salesforce retornará uma resposta de erro especificando o que estava errado com a solicitação. Aqui está um exemplo de resposta que será retornada se o usuário enviar o nome de usuário ou senha incorreto.

HTTP/1.1 403 Forbidden
Content-Type: application/json
Cache-Control: no-store

{
  "error": "authorization_required",
  "auth_session": "uY29tL2F1d*****",
  "error_code": "invalid_credentials"
}

A resposta inclui um parâmetro auth_session que permanece válido por 5 minutos após ser emitido. Durante o período em que a auth_session é válida, você pode usá-la para reenviar a solicitação. Nas versões corrigidas que você reenvia, inclua apenas os valores corrigidos para os parâmetros que causaram a falha da solicitação. Você também deve reenviar a password a cada solicitação, pois o Salesforce não a armazena. Porém, para outros parâmetros, se eles não causarem a falha da solicitação, você poderá ignorá-los. O Salesforce já sabe que você enviou esses parâmetros porque eles estão vinculados à auth_session.

Nota Os parâmetros reCAPTCHA não são vinculados à auth_session, mas você pode reenviar a solicitação sem eles, a menos que causem a falha da solicitação.

Aqui estão alguns exemplos de cenários de erro comuns. Essa lista não é abrangente.

• O usuário enviou o nome de usuário ou senha incorreto. Reenvie a solicitação apenas com username, password e auth_session.
• O token reCAPTCHA estava incorreto. Reenvie a solicitação apenas com o token reCAPTCHA, password, e auth_session.

Após 5 minutos a contar do momento em que a sessão de autenticação foi emitida, ela não funciona mais e você recebe um erro auth_session_invalid. Nesse caso, reenvie a solicitação completa com todos os parâmetros que você incluiu originalmente.

(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 pegará os parâmetros login_hint e customdata e encontrará 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.

Etapa 5: o Salesforce retorna um código de autorização

Quando sua solicitação para o ponto de extremidade de desafio de autorização é bem-sucedida, seja na primeira tentativa ou após várias tentativas com a auth_session, o Salesforce retorna um código de autorização. Aqui está um exemplo de uma resposta de código de autorização bem-sucedida.

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store

{
  "authorization_code": "uY29tL2F1d******"
}

Etapa 6: seu aplicativo troca o código de autorização para um token de acesso

Depois de obter o código de autorização, seu aplicativo envia uma solicitação ao ponto de extremidade services/oauth2/token.

Essa solicitação não tem cabeçalhos. Inclua estes parâmetros no corpo da solicitação.

Aqui está um exemplo de solicitação de token.

POST services/oauth2/token? HTTP 1.1
Host: MyExperienceCloudSite.my.site.com

code=********&
client_id=**********&
client_secret=*********&
redirect_uri=<callback_URL>&
grant_type=authorization_code&
code_verifier=*******

Etapa 7: o Salesforce concede um token de acesso

Depois de validar as credenciais do aplicativo. O Salesforce retorna um token de acesso. Veja aqui um exemplo de resposta de token de acesso no formato JSON.

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

Etapa 8: o aplicativo cria a sessão do usuário

O aplicativo recebe a resposta de token de acesso e cria a sessão do usuário.

Etapa 9: o usuário está conectado e executa uma ação no aplicativo

Agora, o usuário está conectado e executa uma ação no seu aplicativo que solicita o acesso a dados do Salesforce. Por exemplo, ele clica em um botão para visualizar seu histórico de pedido, 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.

Etapa 10: o aplicativo faz uma chamada autenticada para um ponto de extremidade 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 final do Salesforce protegido, como uma API do Salesforce.

Etapa 11: o usuário pode acessar 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 pedidos. Da perspectiva do usuário, todo o processo, desde o login até o acesso aos dados, ocorreu sem exigir que o usuário saísse do aplicativo.