Pular para o conteúdo principal

Configurando Autenticação OAuth do Outlook/Microsoft 365

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

Pré-requisitos​

  • Uma conta Microsoft (pessoal ou Microsoft 365/Office 365)
  • Acesso ao Azure Portal
  • URL da sua instalação Perfex CRM (para configuração do URI de redirecionamento)
informação

Para organizações Microsoft 365, pode ser necessária aprovação de administrador.

Configuração Passo a Passo​

Passo 1: Registrar um Aplicativo no Azure Portal​

  1. Acesse o Azure Portal
  2. Entre com sua conta Microsoft
  3. Navegue para "Azure Active Directory" (ou pesquise por ele)
  4. Clique em "App registrations" no menu à esquerda
  5. Clique em "+ New registration"
  6. Preencha os detalhes do aplicativo:
    • Name: Insira um nome (por exemplo, "Perfex CRM Mailbox")
    • Supported account types: Escolha "Accounts in any organizational directory and personal Microsoft accounts" para máxima compatibilidade
    • Redirect URI:
      • Platform: Web
      • URI: https://your-domain.com/admin/mailbox/oauth/callback?provider=outlook
      • Substitua your-domain.com pelo seu domínio real do Perfex CRM
  7. Clique em "Register"

Passo 2: Configurar Permissões da API​

  1. No registro do seu app, clique em "API permissions" no menu à esquerda
  2. Clique em "+ Add a permission"
  3. Selecione "Microsoft Graph"
  4. Selecione "Delegated permissions"
  5. Adicione as seguintes permissões:
    • Mail.Read - Ler e-mail em todas as caixas de correio
    • Mail.ReadWrite - Ler e escrever e-mail em todas as caixas de correio
    • Mail.Send - Enviar e-mail como o usuário
    • offline_access - Manter acesso aos dados que você concedeu (para atualização de token)
  6. Clique em "Add permissions"
  7. IMPORTANTE: Clique em "Grant admin consent for [Your Organization]" se você vir este botão
aviso

Isso é necessário para contas organizacionais. Requer privilégios de administrador.

Passo 3: Criar Client Secret​

  1. No registro do seu app, clique em "Certificates & secrets" no menu à esquerda
  2. Clique em "+ New client secret"
  3. Insira uma descrição (por exemplo, "Perfex Mailbox Secret")
  4. Escolha um período de expiração: 24 months (recomendado para produção)
  5. Clique em "Add"
  6. IMPORTANTE: Copie o Value imediatamente (você não poderá vê-lo novamente) - este é seu Client Secret

Passo 4: Obter Application (Client) ID​

  1. No registro do seu app, vá para "Overview"
  2. Copie o Application (client) ID - este é seu Client ID

Passo 5: Verificar Redirect URI​

  1. No registro do seu app, clique em "Authentication" no menu à esquerda
  2. Em "Redirect URIs", verifique se seu URI de redirecionamento está listado:
https://your-domain.com/admin/mailbox/oauth/callback?provider=outlook
  1. Se não estiver presente, clique em "+ Add a platform" > "Web" e adicione-o
  2. Em "Implicit grant and hybrid flows", certifique-se de que "Access tokens" está marcado (se disponível)
  3. Clique em "Save"

Passo 6: 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 "Outlook" como seu provedor
  5. Insira seu Client ID (Application ID do Azure)
  6. Insira seu Client Secret (o valor do secret que você copiou)
  7. Para organizações Microsoft 365: Insira seu Tenant ID (encontrado em Azure AD > Overview). Deixe em branco para contas Microsoft pessoais.
  8. Clique em "Save Configuration"
  9. Clique no botão "Connect Outlook"
  10. Autorize o aplicativo na janela popup da Microsoft
  11. Você deve ver uma mensagem de sucesso confirmando a conexão

Limitações e Considerações Importantes​

Restrições do App Microsoft Azure​

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

  1. Requisitos de Consentimento Admin - Contas organizacionais (Microsoft 365/Office 365) requerem consentimento de administrador para certas permissões. O admin deve aprovar o app antes que os usuários possam usá-lo.

  2. Restrições de Tipo de Conta:

    • "Accounts in this organizational directory only" - Apenas usuários da sua organização
    • "Accounts in any organizational directory" - Usuários de qualquer organização Microsoft 365
    • "Accounts in any organizational directory and personal Microsoft accounts" - Máxima compatibilidade
    • "Personal Microsoft accounts only" - Apenas contas pessoais @outlook.com, @hotmail.com

  3. Requisitos de Tenant ID - Contas organizacionais requerem Tenant ID para autenticação adequada. Contas pessoais podem deixar em branco.

Verificação e Publicação do App​

  • Apps não verificados podem ser usados imediatamente para contas pessoais, mas podem mostrar mensagens de aviso aos usuários.
  • Apps verificados requerem envio para a Microsoft App Store (opcional) e fornecem melhor experiência do usuário (sem avisos).
  • Fluxo de Consentimento Admin - Para contas organizacionais, o admin deve conceder consentimento. O admin vê quais permissões o app solicita.

Atualização de Token​

Nosso módulo lida automaticamente com a atualização de tokens:

  • Refresh tokens: Obtidos automaticamente com permissão offline_access
  • Expiração de token: Tipicamente 1 hora para tokens de acesso, 90 dias para tokens de atualização
  • Atualização automática: Nosso módulo atualiza tokens automaticamente antes da expiração

Multi-Tenant vs. Single-Tenant​

  • Multi-Tenant: App pode ser usado por qualquer conta Microsoft (requer consentimento admin por organização)
  • Single-Tenant: App só pode ser usado dentro da sua organização

Notas​

  • O URI de redirecionamento deve corresponder exatamente ao que você configurou no Azure Portal
  • Mantenha seu Client Secret seguro - nunca o compartilhe publicamente
  • Se você alterar seu domínio, atualize o URI de redirecionamento no Azure Portal
  • Para contas organizacionais, certifique-se de que o consentimento admin foi concedido
  • Tenant ID é necessário apenas para contas Microsoft 365/Office 365
  • O fluxo OAuth é tratado inteiramente pela Microsoft - nosso módulo apenas inicia e recebe o callback

Solução de Problemas​

Erro "AADSTS50011: Redirect URI mismatch":

  • Certifique-se de que o URI de redirecionamento no Azure Portal corresponde exatamente: https://your-domain.com/admin/mailbox/oauth/callback?provider=outlook
  • Verifique barras finais ou incompatibilidades HTTP vs HTTPS
  • Verifique se o URI está listado sob o tipo de plataforma "Web"

Erro "Admin consent required":

  • Isso é esperado para contas organizacionais (política da Microsoft)
  • Entre em contato com seu administrador Microsoft 365 para conceder consentimento
  • O admin pode conceder consentimento no Azure Portal > Enterprise applications

Erro "Invalid client secret":

  • Client secrets expiram - crie um novo no Azure Portal
  • Certifique-se de ter copiado o "Value" (não o Secret ID)
  • Verifique se o secret não expirou

Erro "AADSTS700016: Application not found":

  • Verifique se o Client ID está correto
  • Certifique-se de estar usando o Application (client) ID, não o Object ID
  • Verifique se o registro do app existe no tenant Azure AD correto

Erro "Token refresh failed":

  • Certifique-se de que a permissão offline_access foi concedida
  • Verifique se o consentimento admin foi concedido (para contas organizacionais)
  • Verifique se o client secret não expirou

Recursos Adicionais​

informação

Requisitos de consentimento admin, restrições de tipo de conta e políticas de token são políticas de segurança da Microsoft para aplicações Azure. Essas limitações não são impostas pelo nosso software.