Configurando Autenticação OAuth do Gmail

Este guia irá orientá-lo na criação de um aplicativo Google Cloud para autenticação OAuth com Gmail. OAuth fornece uma maneira mais segura de acessar sua conta Gmail em comparação com a autenticação tradicional por senha.

Pré-requisitos

• Uma conta Google (pessoal ou Google Workspace)
• Acesso ao Google Cloud Console
• URL da sua instalação Perfex CRM (para configuração do URI de redirecionamento)

Configuração Passo a Passo

Passo 1: Criar um Projeto Google Cloud

1. Acesse o Google Cloud Console
2. Clique no dropdown do projeto no topo da página
3. Clique em "New Project"
4. Insira um nome para o projeto (por exemplo, "Perfex Mailbox OAuth")
5. Clique em "Create"
6. Aguarde a criação do projeto e selecione-o

Passo 2: Habilitar Gmail API

1. Na Google Cloud Console, navegue para "APIs & Services" > "Library"
2. Pesquise por "Gmail API"
3. Clique em "Gmail API" nos resultados
4. Clique em "Enable"
5. Aguarde a habilitação da API

Passo 3: Configurar Tela de Consentimento OAuth

1. Navegue para "APIs & Services" > "OAuth consent screen"
2. Selecione "External" como tipo de usuário (a menos que você tenha uma conta Google Workspace, então pode escolher "Internal")
3. Clique em "Create"
4. Preencha as informações necessárias:
   • App name: Insira o nome do seu aplicativo (por exemplo, "Perfex CRM Mailbox")
   • User support email: Seu endereço de e-mail
   • Developer contact information: Seu endereço de e-mail
5. Clique em "Save and Continue"
6. Na página "Scopes", clique em "Add or Remove Scopes"
7. Adicione os seguintes escopos:
   • https://www.googleapis.com/auth/gmail.readonly
   • https://www.googleapis.com/auth/gmail.send
   • https://www.googleapis.com/auth/gmail.modify
8. Clique em "Update", depois "Save and Continue"
9. Na página "Test users" (se usando tipo de app External):
   • Adicione seu endereço Gmail como usuário de teste
   • Clique em "Save and Continue"
10. Revise e clique em "Back to Dashboard"

Passo 4: Criar Credenciais OAuth 2.0

1. Navegue para "APIs & Services" > "Credentials"
2. Clique em "Create Credentials" > "OAuth client ID"
3. Selecione "Web application" como tipo de aplicação
4. Insira um nome para seu cliente OAuth (por exemplo, "Perfex Mailbox Client")
5. Em "Authorized redirect URIs", clique em "Add URI"
6. Adicione seu URI de redirecionamento no formato:

https://your-domain.com/admin/mailbox/oauth/callback?provider=gmail

Substitua your-domain.com pelo seu domínio real do Perfex CRM.

7. Clique em "Create"
8. IMPORTANTE: Copie e salve ambos:
   • Client ID (você precisará disso)
   • Client Secret (você precisará disso - clique em "Show" para revelá-lo)

Passo 5: Configurar no Perfex CRM

1. Acesse a área admin do seu Perfex CRM
2. Navegue para Mailbox > Configuration
3. Selecione "OAuth2" como seu método de autenticação
4. Selecione "Gmail" como seu provedor
5. Insira seu Client ID no campo "Gmail Client ID"
6. Insira seu Client Secret no campo "Gmail Client Secret"
7. Clique em "Save Configuration"
8. Clique no botão "Connect Gmail"
9. Autorize o aplicativo na janela popup do Google
10. Você deve ver uma mensagem de sucesso confirmando a conexão

Limitações e Considerações Importantes

Limitações do Google Test App

These limitations are imposed by Google, not by our software.

1. Expiração de Token (7 Dias) - Apps não verificados (apps em modo de teste) têm tokens OAuth que expiram após 7 dias. Após 7 dias, os usuários devem reautorizar a conexão. Esta é uma política de segurança do Google para aplicações não verificadas.

2. Restrições de Usuários de Teste - Apenas usuários adicionados à lista "Test users" podem usar o app OAuth. Máximo de 100 usuários de teste permitidos. Esta restrição se aplica até que o app seja verificado e publicado.

3. Processo de Verificação do App - Para remover a expiração de token de 7 dias, você deve enviar seu app para verificação do Google. A verificação pode levar várias semanas (tipicamente 4-8 semanas). O Google revisa seu app quanto à segurança e conformidade.

Verificação e Publicação do App

Para remover as limitações:

1. Enviar para Verificação

   • Vá para "OAuth consent screen" na Google Cloud Console
   • Clique no botão "PUBLISH APP"
   • Preencha o formulário de verificação com:
     • Propósito e funcionalidade do app
     • URL da política de privacidade
     • URL dos termos de serviço
     • Demonstração em vídeo (opcional mas recomendado)
   • Envie para revisão

2. Cronograma de Verificação

   • Revisão inicial: 1-2 semanas
   • Solicitações de informações adicionais: Variável (se o Google precisar de esclarecimentos)
   • Aprovação final: 4-8 semanas no total (típico)

3. Após a Verificação

   • Tokens não expiram mais após 7 dias
   • Sem restrições de usuários de teste
   • App pode ser usado por qualquer usuário Gmail

Produção vs. Teste

• Modo de Teste: Configuração rápida, mas tokens expiram a cada 7 dias
• Modo de Produção: Requer verificação, mas tokens não expiram
• A escolha é sua - nosso software funciona com ambos os modos

Atualização de Token

Nosso módulo lida automaticamente com a atualização de tokens quando possível. No entanto:

• Apps não verificados: Tokens expiram após 7 dias e requerem reautorização manual
• Apps verificados: Tokens são atualizados automaticamente sem intervenção do usuário

Notas

• O URI de redirecionamento deve corresponder exatamente ao que você configurou na Google Cloud Console
• Mantenha seu Client Secret seguro - nunca o compartilhe publicamente
• Se você alterar seu domínio, atualize o URI de redirecionamento na Google Cloud Console
• O fluxo OAuth é tratado inteiramente pelo Google - nosso módulo apenas inicia e recebe o callback

Solução de Problemas

Erro "Redirect URI mismatch":

• Certifique-se de que o URI de redirecionamento na Google Cloud Console corresponde exatamente: https://your-domain.com/admin/mailbox/oauth/callback?provider=gmail
• Verifique barras finais ou incompatibilidades HTTP vs HTTPS

"Token expired" após 7 dias:

• Isso é esperado para apps não verificados (política do Google)
• Reautorize clicando em "Connect Gmail" novamente
• Para evitar isso, envie seu app para verificação do Google

Erro "Access blocked":

• Certifique-se de que seu e-mail esteja adicionado à lista "Test users" (para apps não verificados)
• Verifique se a Gmail API está habilitada no seu projeto Google Cloud

Não consegue encontrar Gmail API:

• Certifique-se de estar no projeto Google Cloud correto
• Tente pesquisar por "Gmail" na Biblioteca de APIs

Recursos Adicionais

• Google OAuth 2.0 Documentation
• Gmail API Documentation
• Google Cloud Console

informação

A expiração de token de 7 dias e as restrições de usuários de teste são políticas de segurança do Google para aplicações não verificadas. Essas limitações não são impostas pelo nosso software. Uma vez que seu app seja verificado pelo Google, essas restrições são removidas.