Como configurar o login social OAuth

Este guia orienta você na configuração do login social para que os clientes possam fazer login nos PCs clientes usando suas contas do Google, Facebook, Apple, X ou Discord. HandyCafe usa o fluxo de concessão de autorização de dispositivo (RFC 8628), que é projetado para dispositivos sem um navegador completo. Os clientes escaneiam um código QR com seus telefones para se autenticar.

O que você precisa

• Acesso de administrador ao HandyCafe Server.
• Uma conta do Google Cloud Console (para Google OAuth) ou acesso equivalente ao portal do desenvolvedor para outros provedores.
• O HandyCafe Server em execução e acessível em sua rede.
• Pelo menos um PC cliente conectado para testar o fluxo de login.

Como funciona o fluxo do dispositivo OAuth no HandyCafe

Antes de mergulhar na configuração, aqui está um resumo do fluxo:

1. Um cliente em um PC cliente ocioso clica no botão de login social (por exemplo, "Fazer login com o Google").
2. O cliente envia uma solicitação de início do OAuth ao servidor.
3. O servidor entra em contato com o endpoint de autorização de dispositivo do provedor e recebe um código de dispositivo, um código de usuário e um URL de verificação.
4. O cliente exibe um código QR e o código do usuário na tela inicial.
5. O cliente escaneia o código QR com seu telefone e se autentica junto ao provedor.
6. O servidor sonda o provedor até que a autenticação seja concluída.
7. O servidor cria uma solicitação de login OAuth que aparece na página Solicitações.
8. Um administrador ou caixa aprova a solicitação.
9. Uma nova conta de membro é criada (ou uma conta existente é vinculada) e o cliente faz login.

Como configurar o Google OAuth

O Google é o provedor mais comumente usado. Esta seção aborda todas as etapas, desde a criação do projeto do Google Cloud até o teste do primeiro login.

Parte A: Crie credenciais do Google Cloud

1. Abra o Console do Google Cloud em https://console.cloud.google.com em seu navegador.
2. Crie um novo projeto ou selecione um existente. Dê um nome reconhecível como "HandyCafe OAuth".
3. Navegue até APIs e serviços > tela de consentimento do OAuth.
4. Selecione Externo como o tipo de usuário (a menos que você tenha uma organização do Google Workspace e queira apenas interno).
5. Preencha os campos obrigatórios: Nome do aplicativo (“Nome do seu café”), Email de suporte ao usuário e Email de contato do desenvolvedor.
6. Clique em Salvar e continuar nas seções Escopos e Usuários de teste. Você não precisa adicionar escopos especiais. Os escopos padrão de e-mail e perfil são suficientes.
7. Navegue até APIs e serviços > Credenciais.
8. Clique em Criar credenciais > ID do cliente OAuth.
9. Em Tipo de aplicativo, selecione TVs e dispositivos de entrada limitada. Isto é crítico. HandyCafe usa o fluxo de concessão de autorização de dispositivo, que requer esse tipo de cliente específico.
10. Insira um nome para o cliente (por exemplo, "HandyCafe Device Flow").
11. Clique em Criar.
12. Copie Client ID e Client Secret da caixa de diálogo de confirmação. Armazene-os com segurança. Você precisará de ambos os valores na próxima seção.

Parte B: Configurar o servidor HandyCafe

13. Abra o aplicativo HandyCafe Server.
14. Navegue até Configurações usando o ícone de engrenagem na barra lateral esquerda.
15. Selecione a guia OAuth.
16. Ative a alternância OAuth na parte superior da página. Isso permite globalmente o login social em todos os PCs clientes.
17. Localize a linha do provedor Google na lista de provedores.
18. Ative o botão Google para ativar este provedor.
19. Cole seu ID do cliente da etapa 12 no campo ID do cliente.
20. Cole seu Segredo do cliente da etapa 12 no campo Segredo do cliente.
21. Clique em Salvar para aplicar a configuração.

Resultado esperado: a guia OAuth mostra o Google como ativado com suas credenciais preenchidas. As configurações são enviadas a todos os clientes conectados.

Parte C: Teste o fluxo de login

22. Vá para um PC cliente conectado. A tela inativa agora deve mostrar uma seção de login social com um botão de login do Google.
23. Clique no botão de login do Google na tela inativa do cliente.
24. O cliente exibe um código QR e um código de usuário (uma pequena sequência alfanumérica).
25. Digitalize o código QR com seu telefone. Abre a página de verificação de dispositivos do Google.
26. Faça login com uma conta Google e digite o código de usuário quando solicitado.
27. Autorize o aplicativo.

Resultado esperado: No servidor, um som de notificação é reproduzido e uma nova entrada aparece na página Solicitações. A solicitação mostra o nome da conta Google, o endereço de e-mail e o PC cliente que iniciou o login.

Como aprovar uma solicitação de login

Cada login OAuth gera uma solicitação que deve ser aprovada por um administrador ou caixa antes que o cliente obtenha acesso.

1. Quando chega uma solicitação de login, um som de notificação é reproduzido no servidor e um emblema aparece no ícone da página Solicitações na barra lateral.
2. Navegue até a página Solicitações.
3. A solicitação pendente mostra:
   • Nome do provedor (por exemplo, Google).
   • Nome de exibição do provedor (por exemplo, "John Smith").
   • Endereço de e-mail (por exemplo, "john@example.com").
   • O PC cliente que iniciou a solicitação (nome de host ou nome de exibição).
   • Carimbo de data e hora.
4. Revise os detalhes da solicitação. Verifique se a pessoa no PC cliente corresponde às informações da conta.
5. Clique em Aprovar para aceitar a solicitação.

Resultado esperado: Se nenhuma conta-membro existente estiver vinculada a esta identidade OAuth, uma nova conta-membro será criada automaticamente. O nome de exibição e o e-mail do provedor são usados. O cliente está conectado e o PC cliente passa da tela inativa para a página online. Se uma conta-membro tiver sido vinculada anteriormente a esta identidade OAuth, o membro existente fará login diretamente.

Dica: se a solicitação de login for suspeita (por exemplo, o PC está desacompanhado ou a solicitação parece automatizada), clique em Rejeitar. O cliente verá uma mensagem "Acesso negado" e poderá tentar novamente.

Como configurar o Facebook OAuth

1. Abra o Portal do Desenvolvedor do Facebook em https://developers.facebook.com .
2. Crie um novo aplicativo. Selecione o tipo de aplicativo Consumidor.
3. Navegue até a página Configurações > Básico do aplicativo. Observe o ID do aplicativo e o Segredo do aplicativo.
4. Navegue até Adicionar produto e adicione Login do Facebook para dispositivos.
5. Nas configurações de Login do Facebook para dispositivos, adicione seus URIs de redirecionamento, se exigido pelo portal.
6. Abra o HandyCafe Server e navegue até Configurações > OAuth.
7. Localize a linha do provedor Facebook.
8. Ative a alternância do Facebook.
9. Cole o App ID no campo Client ID.
10. Cole o Segredo do aplicativo no campo Segredo do cliente.
11. Clique em Salvar.

Resultado esperado: Facebook aparece como provedor habilitado. As telas inativas do cliente mostram um botão de login do Facebook junto com quaisquer outros provedores habilitados.

Como configurar o Discord OAuth

1. Abra o Portal do Desenvolvedor Discord em https://discord.com/developers/applications .
2. Crie um novo aplicativo. Nomeie-o com o nome do seu café.
3. Navegue até a seção OAuth2 na barra lateral esquerda.
4. Copie o ID do cliente e gere um Segredo do cliente. Armazene o segredo com segurança, pois o Discord o mostra apenas uma vez.
5. Abra o HandyCafe Server e navegue até Configurações > OAuth.
6. Localize a linha do provedor Discord (está desabilitada por padrão).
7. Ative o botão de alternância do Discord.
8. Cole o ID do Cliente no campo ID do Cliente.
9. Cole o Segredo do cliente no campo Segredo do cliente.
10. Clique em Salvar.

Resultado esperado: Discord agora está disponível como opção de login nas telas inativas do cliente.

Como permitir login sem crédito

Por padrão, o HandyCafe permite que clientes autenticados pelo OAuth façam login mesmo que não tenham saldo na carteira ou crédito de tempo. Você pode alterar esse comportamento.

1. Navegue até Configurações > OAuth.
2. Localize o botão de alternância Permitir login sem crédito.
3. Se ativado (padrão), os clientes que autenticam via OAuth podem fazer login independentemente do saldo. Um caixa pode iniciar uma sessão pós-paga para eles.
4. Se desativado, os clientes deverão ter saldo na carteira ou crédito de tempo para fazer login. Os clientes com saldo zero verão uma mensagem solicitando que visitem o caixa para recarregar.
5. Clique em Salvar após alterar a alternância.

Resultado esperado: O comportamento entra em vigor imediatamente para novas solicitações de login. As sessões existentes não são afetadas.

Como vincular uma identidade OAuth a um membro existente

Se um cliente já tiver uma conta de membro (criada manualmente por um caixa) e fizer login via OAuth pela primeira vez, o processo de aprovação poderá vincular a identidade OAuth à sua conta existente.

1. Quando a solicitação de login do OAuth chegar na página Solicitações, verifique se o e-mail corresponde a um membro existente.
2. Se o sistema detectar uma correspondência, a caixa de diálogo de aprovação oferecerá a vinculação da identidade OAuth ao membro existente em vez de criar uma nova conta.
3. Aprove a solicitação com a opção de link selecionada.

Resultado esperado: A conta-membro existente ganha um link OAuth. Logins futuros deste provedor ignorarão a etapa de aprovação e farão login do membro diretamente (após a primeira aprovação).

Erros comuns a evitar

• Usando o tipo de cliente OAuth errado no Console do Google Cloud. Você deve selecionar "TVs e dispositivos de entrada limitada" ao criar o ID do cliente OAuth. Se você selecionar "Aplicativo Web" ou "Aplicativo de desktop", o fluxo de autorização do dispositivo não funcionará e o cliente não conseguirá obter um código do dispositivo.
• Esquecer de ativar a alternância global do OAuth. Ativar provedores individuais não é suficiente. A alternância mestre do OAuth na parte superior da página de configurações do OAuth também deve estar ativada.
• Não aprovar solicitações de login. Logins OAuth exigem aprovação explícita do servidor. Se ninguém monitorar a página Solicitações, os clientes aguardarão indefinidamente na tela inativa. Considere designar um caixa para monitorar as solicitações durante os horários de pico.
• Permitir que os códigos dos dispositivos expirem. Os códigos dos dispositivos têm uma vida útil limitada (normalmente de 5 a 10 minutos). Se o cliente demorar muito para escanear o código QR e autenticar, o código expirará e ele deverá reiniciar. Aconselhe os clientes a digitalizarem imediatamente.
• Colando credenciais com espaço em branco extra. Ao copiar o ID do cliente ou o segredo do cliente do console do provedor, certifique-se de que nenhum espaço à esquerda ou à direita seja incluído. Espaços em branco extras causarão falhas de autenticação.
• Esquecer de publicar o aplicativo Google OAuth. Os aplicativos Google no modo "Teste" permitem apenas um número limitado de usuários de teste. Para permitir que qualquer cliente faça login, você deve publicar o aplicativo por meio da página da tela de consentimento do OAuth e concluir todas as etapas de verificação necessárias.
• Misturando ID do Cliente e Segredo do Cliente. Esses são dois valores diferentes. O ID do cliente é público. O Segredo do Cliente deve ser mantido confidencial. Trocá-los causará falhas de autenticação.
• Não configurando o nome do café. O nome do café nas configurações do HandyCafe é exibido na tela inativa do cliente durante o fluxo OAuth. Um nome em branco ou padrão parece pouco profissional. Defina o nome do seu café em Configurações > Geral antes de ativar o OAuth.