Implementar o fluxo do servidor da Web OAuth 2.0
Nota
Deseja aprender em português (Brasil)? Comece o desafio em um Trailhead Playground de português (Brasil) e use as traduções fornecidas entre parênteses para navegar. Copie e cole somente os valores em inglês porque as validações dos desafios dependem de dados em inglês. Se você não passar no desafio em sua organização de português (Brasil), recomendamos que (1) mude o local para os Estados Unidos, (2) mude o idioma para inglês, seguindo as instruções aqui, e (3) clique novamente no botão “Validar o desafio”.
Consulte o emblema Trailhead no seu idioma para saber mais sobre como aproveitar a experiência de Trailhead em outros idiomas.
Como escolher um fluxo
Agora que você criou um aplicativo conectado Customer Order Status para usuários de suporte, precisará implementar um fluxo para o aplicativo. Como o aplicativo conectado está integrado a um serviço Web externo (o site Customer Order Status) com a API do Salesforce, é melhor usar o fluxo do servidor da Web OAuth 2.0. Esse fluxo de autorização usa o tipo de concessão de código de autorização. Se precisar relembrar esse fluxo do OAuth 2.0, reveja o módulo Noções básicas de aplicativos conectados.
Solicitar um código de autorização
Para iniciar o fluxo do servidor da Web OAuth 2.0, o serviço Web Customer Order Status, por meio do aplicativo conectado, publica uma solicitação de código de autorização (usando o tipo de concessão de código de autorização) para o ponto de extremidade de autorização do Salesforce. O código de autorização é como um crachá de visitante. Com ele, o aplicativo conectado pode provar que foi autorizado como visitante seguro do site e tem permissão para solicitar um token de acesso.
A chamada é feita na forma de um redirecionamento de HTTP, como o que está abaixo.
https://mycompany.my.salesforce.com/services/oauth2/authorize? client_id=3MVG9IHf89I1t8hrvswazsWedXWY0i1qK20PSFaInvUgLFB6vrcb9bbWFTSIHpO8G2jxBLJA6uZGyPFC5Aejq& redirect_uri=https://www.mycustomerorderstatus.com/oauth2/callback& response_type=code
Se você não está familiarizado com esses tipos de chamada, não se preocupe. Vamos detalhar seus componentes individuais.
Componente 1
https://mycompany.my.salesforce.com/services/oauth2/authorize
Esse endereço é o ponto de extremidade de autorização OAuth 2.0 da instância do Salesforce. É o ponto de extremidade para onde seus aplicativos conectados enviam solicitações de autorização OAuth.
Componente 2
client_id=3MVG9IHf89I1t8hrvswazsWedXWY0i1qK20PSFaInvUgLFB6vrcb9bbWFTSIHpO8G2jxBLJA6uZGyPFC5Aejq
A ID do cliente é a chave de consumidor do aplicativo conectado. Para acessar a chave de consumidor, clique em Manage Consumer Details (Gerenciar detalhes do consumidor) na página Manage Connected Apps (Gerenciar aplicativos conectados) do aplicativo conectado e verifique sua identidade.
Componente 3
redirect_uri=https://www.mycustomerorderstatus.com/oauth2/callback
O URI de redirecionamento é o destino para onde os usuários são redirecionados após uma autorização bem-sucedida. O URI de redirecionamento é a URL de retorno de chamada do aplicativo conectado, que você também pode encontrar na página Manage Connected Apps (Gerenciar aplicativos conectados) do aplicativo conectado.
Essa imagem mostra a URL de retorno de chamada que corresponde aos exemplos de código. Para seu aplicativo conectado, use a URL de retorno de chamada https://openidconnect.herokuapp.com/callback inserida na Unidade 1: Criar um aplicativo conectado.
Componente 4
response_type=code
O tipo de resposta diz ao Salesforce que tipo de concessão do OAuth 2.0 está sendo solicitado pelo aplicativo conectado. O tipo de código de resposta indica que o aplicativo conectado está solicitando um código de autorização.
Autenticar o usuário e conceder acesso ao aplicativo
Antes de o Salesforce dar um código de autorização para o aplicativo conectado, você precisará se autenticar fazendo login na sua organização do Salesforce.
Depois de fazer login, clique em Allow (Permitir) para autorizar o aplicativo conectado a acessar os dados da sua organização do Salesforce.
Receber retorno de chamada
Depois de autorizar o aplicativo, o Salesforce envia um retorno de chamada ao aplicativo conectado com um código de autorização.
https://www.mycustomerorderstatus.com/oauth2/callback? code=aPrx4sgoM2Nd1zWeFVlOWveD0HhYmiDiLmlLnXEBgX01tpVOQMWVSUuafFPHu3kCSjzk4CUTZg==
Componente 1
A primeira parte do retorno de chamada é a URL de retorno de chamada do aplicativo conectado.
https://www.mycustomerorderstatus.com/oauth2/callback
Componente 2
A segunda parte é o código de autorização aprovando o aplicativo.
code=aPrx4sgoM2Nd1zWeFVlOWveD0HhYmiDiLmlLnXEBgX01tpVOQMWVSUuafFPHu3kCSjzk4CUTZg==
Solicitar token de acesso
Agora que o aplicativo conectado tem um código de autorização válido, ele o transmite ao ponto de extremidade de token do Salesforce para solicitar um token de acesso.
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
Vamos ver também os componentes individuais dessa chamada.
Componente 1
POST /services/oauth2/token HTTP/1.1 Host: mycompany.my.salesforce.com Content-length: 307 Content-type: application/x-www-form-urlencoded
As primeiras duas linhas desse componente são a solicitação de POST feita ao ponto de extremidade de token OAuth 2.0 da instância do Salesforce. Esse ponto de extremidade é onde seus aplicativos conectados enviam solicitações de token de acesso e atualização.
As duas linhas a seguir mostram o tamanho e o tipo de conteúdo da solicitação.
Componente 2
grant_type=authorization_code
O tipo de concessão define o tipo de validação que o aplicativo conectado pode fornecer para provar que é um visitante seguro. Nesse caso, ele está fornecendo um código de autorização.
Componente 3
code=aPrxhgZ2MIpkSy0aOdn07LjKFvsFOis6RGcWXz7p8JQCjcqfed5NQLe7sxWwMY_JQFuLwHRaRA
O código de autorização é um valor temporário que você recebe do servidor de autorização (nesse caso, o Salesforce). O aplicativo conectado usa esse código em troca de um token de acesso. Esse tipo de fluxo do OAuth 2.0 é uma forma segura de transmitir o token de acesso de volta para o aplicativo.
Componente 4
client_id=3MVG9IHf89I1t8hrvswazsWedXWY0i1qK20PSFaInvUgLFB6vrcb9bbWFTSIHpO8G2jxBLJA6uZGyPFC5Aejq
Esse componente também deve parecer familiar. É a chave de consumidor do aplicativo conectado da página de gerenciamento de aplicativos conectados.
Componente 5
client_secret=*******************
O segredo do cliente é igual ao segredo do consumidor do aplicativo conectado. Você acessa o segredo do consumidor da mesma forma que acessa a chave de consumidor. Na página Manage Connected Apps (Gerenciar aplicativos conectados), clique em Manage Consumer Details (Gerenciar detalhes do consumidor) e verifique sua identidade.
Essa imagem mostra a URL de retorno de chamada que corresponde aos exemplos de código. Para seu aplicativo conectado, use a URL de retorno de chamada https://openidconnect.herokuapp.com/callback inserida na Unidade 1: Criar um aplicativo conectado.
Componente 6
redirect_uri=https://www.mycustomerorderstatus.com/oauth2/callback
Você se lembra desse componente das primeiras duas chamadas? É a URL de retorno de chamada do aplicativo conectado.
Receber token de acesso
Quando você criou o aplicativo conectado, selecionou a opção Require Secret for Web Server Flow (Exigir segredo para o Fluxo de servidor da web). Essa exigência significa que o Salesforce não pode dar um token de acesso ao aplicativo conectado enquanto o aplicativo não enviar um segredo de consumidor válido. Ou seja, nessa etapa, o Salesforce valida o código de autorização do aplicativo conectado, a chave de consumidor e o segredo de consumidor.
Depois que o Salesforce valida as credenciais do aplicativo conectado, ele retorna um token de acesso em formato JSON. O token de acesso também inclui permissões associadas na forma de escopos e um token de ID para o aplicativo.
{
"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://mydomain.my.salesforce.com/id/00DB0000000TfcRMAS/005B0000005Bk90IAC",
"token_type": "Bearer",
"issued_at": "1558553873237"
}Sua vez
Agora é sua vez de testar o fluxo do servidor da Web OAuth 2.0. Como há transmissão de informações confidenciais entre a instância do Salesforce e a URL de retorno de chamada durante o fluxo, é essencial que essas informações não sejam transmitidas a locais aleatórios. Para demonstrar de forma segura o fluxo de autorização, vamos usar um OpenID Connect Playground seguro criado apenas para este fim. O OpenID Connect Playground fica hospedado em um servidor Heroku seguro que mostra o fluxo de autorização, mas protegendo seus dados.
Quando você implementa esse fluxo no mundo real, é imperativo usar um host seguro para a URL de retorno de chamada a fim de manter a proteção dos seus dados.
Vamos começar. Primeiro, reúna algumas informações sobre o aplicativo conectado que você criou na primeira etapa deste projeto.
- Chave de consumidor
- Segredo do consumidor
- URL de retorno de chamada
Você também precisará ter a URL do My Domain (Meu domínio) do seu Trailhead Playground, que pode ser encontrada em Setup (Configuração) | My Domain (Meu domínio).
Experimentar
- Abra o OpenID Connect Playground.
- Copie a URL do My Domain (Meu domínio) do seu Trailhead Playground e cole após o https:// como host do login.
- Cole a chave de consumidor do seu aplicativo conectado.
- Cole o segredo do consumidor do seu aplicativo conectado. (O OpenID Connect Playground usa POST para enviar informações, o que significa que o segredo do cliente não é registrado em log.)
- Verifique se a URL de retorno de chamada do seu aplicativo conectado corresponde ao URI de redirecionamento (URL de retorno de chamada). Dica: você digitou essa URL de retorno de chamada na primeira etapa deste projeto.
- Clique em Next (Avançar) para enviar uma solicitação de código de autorização. Se você receber um pedido de permissão para o OpenID Connect Playground acessar seu Trailhead Playground, clique em Allow (Permitir). Se a solicitação for bem-sucedida, você receberá um código de autorização. No lado direito da página, você poderá ver a solicitação de autorização e a resposta do servidor Heroku. Elas devem se parecer com a solicitação e a resposta que mostramos acima.
- Clique em Next (Avançar) para solicitar um token de acesso. Se a solicitação for bem-sucedida, você receberá um token de acesso e um token de ID. No lado direito da página, você poderá ver a solicitação de token de acesso e a resposta do servidor Heroku. Elas devem se parecer com a solicitação e a resposta que mostramos acima.
- Clique novamente em Next (Avançar) para transmitir o token de acesso novamente para o servidor Heroku. O servidor Heroku deve responder com os metadados do seu aplicativo conectado.
Crédito extra: acessar dados de status dos pedidos
Parabéns! Você implementou com êxito o fluxo do servidor da Web OAuth 2.0. Agora o aplicativo conectado Customer Order Status pode enviar uma solicitação para sua organização do Salesforce a fim de acessar os dados de status de determinado pedido. A solicitação do aplicativo conectado inclui o token de acesso. Depois que sua organização do Salesforce validar o token de acesso e os escopos associados, ela concederá ao aplicativo acesso aos dados de status do pedido.
Se você quiser ir além desta trilha, poderá recuperar o status do pedido fazendo o seguinte:
- Crie um pedido em seu Trailhead Playground. Consulte Pedidos na Ajuda do Salesforce.
- Use a consulta cURL apropriada para recuperar o status do seu novo pedido por meio da API REST do Salesforce.
Dica A plataforma MacOS dá suporte a cURL automaticamente, assim como o Windows 10 build 17063. Se sua plataforma ainda não tem cURL instalado, baixe-o em https://curl.haxx.se/.
Se você está usando uma plataforma que não seja macOS ou Windows (por exemplo, Linux), modifique a consulta cURL conforme a necessidade para atender aos requisitos da sua plataforma.
Consulta cURL Mac:curl https://<your_trailhead_domain>/services/data/v55.0/sobjects/Order/<order_ID>\?fields\=Status -H 'Authorization: Bearer <access_token>' -H "X-PrettyPrint:1"
Consulta cURL Windows:curl https://<your_trailhead_domain>/services/data/v55.0/sobjects/Order/<order_ID>?fields=Status -H “Authorization: Bearer <access_token>” -H "X-PrettyPrint:1"
Na consulta cURL, substitua:
- <your_trailhead_domain> pelo nome de domínio do seu Trailhead Playground.
- <order_ID> pela ID do pedido localizado na URL da página Order (Pedido).
- <access_token> pelo token de acesso recebido do OpenID Connect Playground.
- Uma consulta bem-sucedida deverá receber uma resposta como esta:
{ "attributes" : { "type" : "Order", "url" : "/services/data/v55.0/sobjects/Order/8014P000001s9OLXXX" }, "Status" : "Draft", "Id" : "8014P000001s9OLXXX" }
Hora de gerenciar seu aplicativo conectado
Agora é hora de brincar de administrador do Salesforce. Na próxima etapa, você vai gerenciar o acesso ao aplicativo conectado.
Recursos
-
Ajuda do Salesforce: Fluxos de autorização de OAuth
-
Ajuda do Salesforce: Fluxo do servidor da Web OAuth 2.0 para integração de aplicativos Web
-
Trailhead: Noções básicas do API