{"section":"tutorials","requestedLocale":"pt","requestedSlug":"criar-autenticacao-oauth2","locale":"pt","slug":"criar-autenticacao-oauth2","path":"docs/pt/tutorials/autenticação/criar-autenticacao-oauth2.md","branch":"main","content":"Para alguns lojistas, existe a necessidade de criar uma autenticação adicional na VTEX com sua base própria de logins. Por exemplo:\n\n- Um \"clube fidelidade\" de clientes, com login e senha já criados em sua própria plataforma.\n- Login de funcionário para venda em sua \"loja de colaboradores\".\n\nPor conta disso, a VTEX disponibiliza autenticação OAuth2 integrada ao VTEX ID.\n\n> ⚠️ Como este é um assunto com aspectos bastante técnicos, recomendamos o acompanhamento de um parceiro ou equipe de TI.\n\n## O que é OAuth2\n\nO OAuth é um protocolo de autorização muito utilizado em aplicações web escaláveis. A versão atual é a 2.0, que utiliza tokens para acessar seus dados em outro sistema.\n\n## Qual é a utilidade do OAuth2\n\nPara as lojas VTEX, o principal benefício trazido pelo OAuth2 é a possibilidade de reaproveitar login e senhas já criados em sistemas externos integrados à VTEX. Isso agiliza o processo de autenticação quando necessário, sendo a mesma lógica da autenticação via Facebook e Google+, por exemplo.\n\n## Guia oficial de referência\n\nVocê pode consultar o guia oficial do protocolo OAuth2 neste endereço: https://tools.ietf.org/html/rfc6749\n\n## Fluxo de integração do OAuth2 com o VTEX ID\n\nCom base na documentação oficial, veja abaixo uma ilustração que explica a integração do OAuth2 com o VTEX ID:\n![oauth2](https://cdn.statically.io/gh/vtexdocs/help-center-content/refs/heads/main/docs/pt/tutorials/autenticação/criar-autenticacao-oauth2_1.jpg)\n\nA partir dessa ilustração, vamos detalhar os passos a seguir.\n\nNote que qualquer parte do processo só acontece exclusivamente pelo protocolo **HTTPS**.\n\n### 1. URL de autorização (getAuthorizationCode)\n\nO usuário (cliente da loja) verá a tela de login do VTEX ID e irá optar por usar determinado provedor de identidade (externo à VTEX).\n\nO VTEX ID irá redirecionar o usuário para uma URL de autorização do provedor de identidade. Naturalmente, isso será uma requisição com o método GET neste servidor.\n\nEssa URL de autorização é fornecida pelo lojista e terá pelo menos três parâmetros (querystring):\n\n- Client ID: é o identificador do VTEX ID no provedor de identidade; o parâmetro tem nome livre (sugerido `client_id`) e seu valor é determinado pelo provedor (sendo sempre fixo);\n- URL de retorno: será usado nos próximos passos do fluxo; seu valor é determinado pelo VTEX ID mas o nome do parâmetro é livre (sugerido `return_url`);\n- \"state\": é usado junto à URL de retorno e tem nome e valor determinados pelo VTEX ID (não deve ser alterado).\n\nSe necessário, o VTEX ID aceita a inclusão de parâmetros adicionais, bastando indicar o nome das chaves e seus valores. Lembrando que chaves e valores são sempre fixos.\n\nA partir da URL de autorização, o usuário irá passar pelo processo de autenticação no provedor de identidade externo.\n\nAutenticado com sucesso, o provedor deverá redirecionar o usuário de volta para o VTEX ID, de modo que a URL de destino deverá ser:\n\n- a URL de retorno que foi enviada pelo VTEX ID;\n- junto do parâmetro \"state\" (mantendo seu valor original);\n- e mais um novo parâmetro, que irá representar o código de autenticação gerado pelo provedor de identidade; seu nome é livre (sugerido `auth_code`).\n\n### 2. URL para troca de código de autorização por código de acesso (getAccessCode)\n\nQuando o usuário voltar para a URL de retorno, o VTEX ID irá capturar o código de autorização para, a partir dos servidores de backend (fora do browser do cliente), obter um código de acesso.\n\nEste código de acesso será utilizado para obter os dados do cliente com segurança e criar os cookies que identificarão o usuário dentro dos serviços da VTEX.\n\nEssa URL será usada necessariamente com o método POST.\n\nO código de autorização deve ser enviado no corpo da requisição (body), que pode ser tanto no formato JSON (content-type `application/json`) ou form-urlencoded (content-type `application/x-www-form-urlencoded`). É necessário nos indicar o método desejado e qual o nome da chave que vai representá-lo.\n\nParâmetros adicionais podem ser enviados na querystring e/ou no body. Lembrando que chaves e valores são sempre fixos.\n\nPara a segurança do processo o VTEX ID precisa do Client ID e Client Secret (o ID é o mesmo do início do processo, de modo que eles funcionam como appKey e appToken). Eles podem ser enviados com o header \"Authorization\" ou como parâmetros na URL (chaves de nome livre).\n\nNa resposta esperamos receber o código de acesso no body, que pode ser no formato JSON (content-type `application/json`) ou form-urlencoded (content-type `application/x-www-form-urlencoded`); o nome da propriedade é livre, bastando informá-la para mapeamento.\n\nParâmetros adicionais podem fazer parte da resposta, mas a princípio não são úteis.\n\n### 3. URL para obter os dados do usuario (getUserInfo)\n\nEssa URL será usada necessariamente com o método GET.\n\nO cliente deve ser reconhecido pelo próprio código de acesso, que será enviado como um header Authorization Bearer. Opcionalmente, ele também pode ser enviado como parâmetro (querystring).\n\nSe necessário, o VTEX ID aceita a inclusão de parâmetros adicionais, bastando indicar o nome das chaves e seus valores. As chaves e valores sempre serão fixos.\n\nNa resposta esperamos receber o e-mail do cliente e seu ID no provedor de identidade. Também é adequado disponibilizar o nome do cliente (embora não seja obrigatório). Os dados podem ser entregues no formato JSON (`content-type application/json`) ou form-urlencoded (`content-type application/x-www-form-urlencoded`).\n\nInformações adicionais podem fazer parte da resposta, mas a princípio não são úteis.\n\n**Importante**: a chave única da plataforma VTEX é o e-mail. Do lado do provedor de identidade pode ser solicitado outro tipo de informação para autenticar a pessoa (CPF, CNPJ, login, telefone etc) mas o que deve ser enviado na integração para a VTEX é o e-mail que foi autenticado. Esse cenário atende B2B, B2C, B2E.\n\nConcluída essa etapa, o usuário vai receber um cookie com o token de autorização que lhe identificará dentro dos serviços da VTEX.\n\n## Exemplo de uso\n\nA seguir exemplificamos o processo usado para uma integração OAuth2 tendo o Google como provedor de identidade:\n\n#### getAuthorizationCode\n\nRequest:\n\n```\nGET https://accounts.google.com/o/oauth2/auth?redirect_uri=https://vtexid.vtex.com.br/VtexIdAuthSiteKnockout/ReceiveAuthorizationCode.ashx&scope=https://www.googleapis.com/auth/userinfo.profile%20https://www.googleapis.com/auth/userinfo.email&access_type=offline&response_type=code&client_id={clientId}&state={state}\n```\n\n#### getAccessCode\n\nRequest:\n\n```\nPOST https://accounts.google.com/o/oauth2/token\n\nBody: redirect_uri=https://vtexid.vtex.com.br/VtexIdAuthSiteKnockout/ReceiveAuthorizationCode.ashx&grant_type=authorization_code&client_id={clientId}&client_secret={clientSecret}&code={authorizationCode}\n```\n\nResponse:\n\n```\n{\n\t\"access_token\" : {accessToken},\n\t\"expires_in\" : 3600,\n\t\"id_token\" : {jwt},\n\t\"token_type\" : \"Bearer\"\n}\n```\n\n#### getUserInfo\n\nRequest:\n\n```\nGET https://www.googleapis.com/oauth2/v1/userinfo?access_token={accessToken}\n```\n\nResponse:\n\n```\n{\n\t\"id\": {id},\n\t\"email\": {email},\n\t\"verified_email\": true,\n\t\"name\": \"Rodrigo Silva de Andrade\",\n\t\"given_name\": \"Rodrigo\",\n\t\"family_name\": \"Silva de Andrade\",\n\t\"link\": \"xxxxxx\",\n\t\"picture\": \"xxxx\",\n\t\"gender\": \"male\",\n\t\"locale\": \"pt-BR\"\n}\n```\n\n## Resumo\n\nAssim que o serviço estiver desenvolvido e público na internet, todos os dados de configuração devem ser encaminhados à VTEX (via ticket de suporte) para que seja configurado o ambiente da loja e integrado ao VTEX ID, disponibilizando mais uma opção de login para seus clientes.\n\n> ℹ️ Se você tiver múltiplas lojas (subcontas) listadas em **Configurações da conta > Gerenciamento da conta > Conta**, cada uma exigirá sua própria configuração de provedor de identidade OAuth2.\n\nEm resumo, são eles:\n\n- todos endpoints habilitados para HTTPS\n- credenciais (client ID e client Secret, ou equivalente)\n- credenciais (usuário/email e senha) para teste de configuração\n- nome desejado para o provedor de identidade, que no resultado final será apresentado como texto do botão \"Entrar como \\{nome do provedor\\}\"\n\nPara **getAuthorizationCode**:\n\n- URL da requisição (método GET)\n- nome do parâmetro para client ID\n- nome do parâmetro para URL de retorno\n- parâmetros adicionais (se houver, indicando chave e valor)\n- chave que contém o código de autorização (na resposta)\n\nPara **getAccessCode**:\n\n- URL da requisição (método POST)\n- modo para código de autorização (body em JSON ou form-urlencoded)\n- parâmetros adicionais na URL (se houver)\n- parâmetros adicionais no body (se houver)\n- modo para credenciais (header Authorization)\n- formato da resposta (body em JSON ou form-urlencoded)\n- chave que contém o código de acesso (na resposta)\n\nPara **getUserInfo**:\n\n- URL da requisição (método GET)\n- parâmetros adicionais (se houver)\n- chave que contém o ID do usuário (na resposta)\n- chave que contém o e-mail (na resposta)\n- chave que contém o nome (na resposta, se houver)"}