OAuth 2.0 para aplicativos de primeira parte: Fluxo de registro autônomo para clientes privados

Etapa 1: o usuário abre o aplicativo de primeira parte e clica em Registrar

Um usuário abre seu aplicativo de primeira parte e clica em um link de registro. Ou eles clicam em um link para acessar um recurso que requer registro.

Etapa 2: o aplicativo de primeira parte exibe o formulário de registro

Em seu aplicativo de primeira parte, você exibe nativamente um formulário de registro para coletar informações sobre o usuário. Você controla tudo sobre esse formulário, incluindo a aparência e as informações do usuário que deseja coletar.

Há algumas considerações sobre quais informações você deseja coletar dos usuários. Quando seu aplicativo envia informações do usuário para o ponto de extremidade do desafio de autorização, o Salesforce verifica se há um endereço de email, um nome de usuário, um sobrenome e uma senha. Você pode coletar essas informações dos usuários ou gerá-las automaticamente, mas elas devem ser incluídas na sua solicitação POST. Ao decidir quais informações incluir, certifique-se de coletar um endereço de email ou número de telefone para que o usuário possa confirmar sua identidade.

Etapa 3: o usuário insere suas informações

No formulário de registro do aplicativo, o usuário insere suas informações.

Etapa 4: O aplicativo de primeira parte define um JWT de atestado do cliente e gera valores de code_verifier e code_challenge para PKCE

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 5: o aplicativo envia a solicitação inicial ao ponto de extremidade do desafio de autorização

No navegador, seu aplicativo envia uma solicitação POST ao ponto de extremidade services/oauth2/v1/authorization_challenge em seu site do Experience Cloud.

Inclua esse cabeçalho na sua solicitação, se necessário.

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

Aqui está um exemplo de solicitação de registro inicial.

POST /services/oauth2/v1/authorization_challenge? HTTP 1.1
Host: MyExperienceCloudSite.my.site.com
{
    "userdata": {
        "firstname": "Janice"
        "lastname": "Edwards"
        "email": "janice.edwards@example.com"
        "username": "jedwards@myapp.com"
        }
    "customdata": {
        "mobilePhone"="<mobile phone number>"
        }
    "password":"*********"
    "recaptcha": "*******"
    "login_type": "email"
    "emailtemplate": "unfiled$public/SalesNewCustomerEmail"
    "client_assertion": "Y2xpZW50YXNzZXJ0aW9u..."
}

Etapa 6: 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.

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. A resposta também 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. Eles já estão representados por 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.

Por exemplo, se o JWT de certificação do cliente for válido, mas a solicitação falhar porque o nome de usuário estava incorreto, reenvie uma solicitação que inclua apenas a auth_session, username e password.

Etapa 7: o Salesforce envia uma OTP ao usuário

Se a solicitação for bem-sucedida, o Salesforce ainda retornará uma resposta de erro porque ainda não pode conceder o código de autorização. Porém, dessa vez, a resposta de erro indica que o login foi inicializado e que o Salesforce enviou uma OTP para o endereço de email ou número de telefone do usuário. Para confirmar que a solicitação foi bem-sucedida, procure o código de erro login_initialized e o estado otp_sent. A resposta também inclui um parâmetro auth_session, que é importante para a próxima etapa.

Aqui está um exemplo de resposta.

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

{
  "error": "authorization_required",
  "auth_session": "uY29tL2F1dGhlbnRpY",
  "error_code": "login_initialized",
  "login_status": {
    "type": "SMS",
    "state": "otp_sent",
    "displayData": "+120******58"
   }
}

Etapa 8: seu aplicativo exibe nativamente um formulário de verificação

Em seu aplicativo de primeira parte, você exibe um formulário de verificação em que o usuário final pode inserir sua OTP. A aparência desse formulário depende totalmente de você.

Etapa 9: o usuário insere a OTP no formulário de verificação

O usuário recebe a OTP e a insere no formulário de verificação no seu aplicativo de primeira parte.

Etapa 10: seu aplicativo solicita um código de autorização

Para solicitar um código de autorização, seu aplicativo envia a auth_session e o OTP que o usuário inseriu para o ponto de extremidade de desafio de autorização usando outra solicitação POST para o services/oauth2/v1/authorization_challenge Essa solicitação não tem cabeçalhos obrigatórios. Inclua estes parâmetros no corpo da solicitação.

Aqui está um exemplo de solicitação.

POST /authorize HTTP/1.1
Host: MyExperienceCloudSite.my.site.com

auth_session=uY29tL2F1dGhlbnRpY*
login_otp=<otp_from_sms>

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

Se a OTP estiver correta e a solicitação de auth_session for válida, o Salesforce retornará um código de autorização e encerrará a auth_session. Aqui está um exemplo de resposta de código de autorização.

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

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

Etapa 12: 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 do token do Salesforce.

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 13: 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 14: o aplicativo cria a sessão do usuário

O aplicativo de primeira parte processa a resposta do token e cria a sessão do usuário.

Etapa 15: o usuário está registrado e executa uma ação no aplicativo

O usuário agora está registrado e 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.

Etapa 16: 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 17: 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 reservas de viagem.