Crie já

Microsoft Graph OAuth: Autentique Caixas de Correio do Outlook e Microsoft 365 (Guia 2026)

Microsoft Graph OAuth 2026

Microsoft Graph OAuthAutenticar caixas de correio do Outlook e do Microsoft 365

Guia completo de 2026 para OAuth do Microsoft Graph para desenvolvedores de SaaS. Abrange registro de aplicativo do Microsoft Entra, endpoints de autoridade, escopos de email, permissões delegadas vs. de aplicativo, consentimento do administrador, código de autorização + PKCE, rotação de token de atualização, códigos de erro AADSTS e como o Unipile elimina 5 semanas de encadeamento de OAuth em 5 minutos.

Construa com Unipile Guia do MS Graph
link_conta_outlook.py
import solicitações # Etapa 1: Gerar um link de autenticação hospedado response = requests.postagem( "https://apiXXX.unipile.com:XXX `/api/v1/hosted/accounts/link"`", cabeçalhos={"X-API-KEY": chave_api}, json={ "tipo": "criar", "fornecedores": ["MICROSOFT"], "url_da_api": seu_dsn, "expiraEm": "31/12/2026 23:59:59" } ) # Etapa 2: Redirecione o usuário para a URL auth_url = resposta.json()["url"] O # Unipile gerencia todo o fluxo OAuth #, incluindo Entra, escopos, tokens e atualização
Microsoft OAuth manipulado. Caixa de correio pronta.
Contexto 2026

Por que o OAuth do Microsoft Graph é Inegociável em 2026

Se o seu aplicativo SaaS lê, envia ou sincroniza emails do Outlook ou Microsoft 365, o Microsoft Graph OAuth não é mais opcional. Três descontinuações importantes tornaram a autenticação básica, protocolos legados e senhas de aplicativos obsoletos. O OAuth 2.0 via API do Microsoft Graph é o único caminho suportado.

Autenticação Básica - Totalmente Desativada
A Microsoft desativou a autenticação básica para o Exchange Online em outubro de 2022. Isso afeta IMAP, POP3, SMTP, EWS, MAPI, OAB, Outlook Anywhere e RPC sobre HTTP. Sem exceções, sem extensões de período de carência restantes.
Desativado em Outubro de 2022
EWS - Cronograma do Pôr do Sol
O Exchange Web Services (EWS) está em modo de manutenção. A Microsoft anunciou que não haverá novos recursos e recomenda a migração para o Microsoft Graph. Embora ainda não esteja totalmente desativado, criar novas integrações no EWS em 2026 será uma dívida técnica da qual você se arrependerá.
Modo de Manutenção
OAuth 2.0 - O Padrão Necessário
O Microsoft Graph OAuth via Microsoft Entra ID (anteriormente Azure AD) é o único método de autenticação oficialmente suportado para aplicações SaaS em produção que acessam caixas de correio do Outlook e Microsoft 365 em 2026. Este guia abrange a implementação completa.
Padrão Exigido
O que o Microsoft Graph OAuth desbloqueia
Ler, enviar e sincronizar caixas de correio do Outlook em nome de usuários autenticados
Acesse caixas de correio do Microsoft 365 e do Outlook.com pessoal com um único registro de aplicativo
Tokens de atualização de longa duração com rotação automática (sem reautenticação para usuários ativos)
Controle granular de escopo: solicite apenas as permissões que seu aplicativo realmente precisa
Suporte multi-tenant: um registro de aplicativo atende a todos os tenants de clientes
Conformidade com as políticas corporativas de Acesso Condicional e MFA
Fluxos OAuth

Os 3 Fluxos OAuth Suportados pela Microsoft (e Qual o SaaS Precisa)

A plataforma de identidade da Microsoft suporta vários tipos de concessão OAuth 2.0. Escolher o errado é uma causa comum de tempo de engenharia desperdiçado. Aqui está o detalhamento para aplicativos SaaS que acessam e-mail em nome de seus usuários.

Recomendado para SaaS
Código de Autorização + PKCE
RFC 6749 Seção 4.1 + RFC 7636
O usuário é redirecionado para a página de login da Microsoft, autentica-se e concede consentimento. Seu aplicativo troca o código de autorização retornado por tokens de acesso e atualização. O PKCE (Proof Key for Code Exchange) impede ataques de interceptação de código e é obrigatório para clientes públicos e recomendado para todos os clientes em 2026.
Use isto para aplicativos SaaS que acessam caixas de correio de usuários
Credenciais do cliente
OAuth 2.0 Seção 4.4 (apenas aplicativo)
Nenhuma interação do usuário. Seu aplicativo se autentica como ele mesmo usando um ID de cliente e segredo (ou certificado). Requer permissões de aplicativo (não delegadas), o que significa que um administrador de locatário deve conceder consentimento para acessar todas as caixas de correio na organização. Nenhuma tela de consentimento do usuário.
Apenas para ferramentas internas com acesso concedido por administrador
Fluxo de Código do Dispositivo
OAuth 2.0 Device Authorization Grant
Projetado para dispositivos sem navegador (CLIs, IoT, smart TVs). O usuário visita um URL em outro dispositivo para autenticar. Não é relevante para aplicações web SaaS onde um redirecionamento é possível.
Não aplicável a aplicativos web SaaS padrão
Comece a construir seu fluxo de OAuth da Microsoft
Unipile - Registro de Aplicativos do Microsoft Entra
Configuração Passo a Passo

Registro de Aplicativo no Microsoft Entra: 7 Passos

Antes que seu aplicativo possa solicitar tokens OAuth, você precisa de um aplicativo registrado no Microsoft Entra ID (anteriormente Azure Active Directory). Aqui estão os passos exatos, incluindo quais valores de campo são importantes e quais são cosméticos.

1
Criar um Registro de Aplicativo no Portal do Azure
Navegar para portal.azure.com, vá para Microsoft Entra ID (pesquisar na barra superior), depois Registros de aplicativos, então clique em + Novo cadastro. Veja a documentação completa do Microsoft OAuth para contexto adicional.
Nome
Nome do seu aplicativo. É isso que os usuários verão na tela de consentimento da Microsoft. Use o nome do seu produto, não um identificador técnico.
Tipos de conta suportados
Para um SaaS multi-tenant atendendo usuários empresariais e pessoais: selecione Contas em qualquer diretório organizacional (qualquer locatário do Microsoft Entra ID - multilocatário) e contas pessoais da Microsoft. Isto corresponde ao /comum endpoint de autoridade.
Dica: Se você atende apenas contas corporativas do Microsoft 365 (não contas pessoais do Outlook.com), selecione apenas "Multitenant". Isso usa /organizações autoridade e reduz sua área de superfície de consentimento. Mais sobre pontos de extremidade de autoridade na seção 4.
2
Configurar URIs de Redirecionamento
Após o registro, vá para Autenticação no painel esquerdo. Adicionar uma plataforma: selecionar Web. Adicione seu(s) URI(s) de redirecionamento, a URL para onde a Microsoft redirecionará o usuário com o código de autorização.
Tipo de plataforma
Web para aplicativos do lado do servidor. Use Aplicação de Página Única (SPA) para fluxos do lado do cliente (habilita automaticamente PKCE).
URI de redirecionamento
Deve ser HTTPS em produção. Exemplo: https://app.yourproduct.com/auth/microsoft/callback. Correspondência exata necessária, qualquer desvio causa AADSTS50011.
URL de logout (opcional)
A Microsoft chamará esta URL quando o usuário sair de qualquer aplicativo em seu locatário. Opcional para integrações apenas de email.
Erro comum: URIs localhost são permitidas durante o desenvolvimento (http://localhost:3000/callback) mas URIs de produção devem usar HTTPS. Registre ambos separadamente.
3
Adicionar permissões de API do Microsoft Graph
Ir Permissões de API. Clicar + Adicionar uma permissão, Selecionar Microsoft Graph, então Permissões delegadas. Adicione os escopos que seu aplicativo precisa.
Mínimo para ler
Mail.Read, acesso_offline, openid, perfil
Para ler + enviar
Mail.ReadWrite, Mail.Send, acesso_offline, openid, perfil
acesso_offline
Crítico. Sem esse escopo, a Microsoft não emite um token de atualização. Seus usuários precisarão se autenticar novamente a cada 60-90 minutos.
Observação: Adicionar permissões aqui não as concede, mas declara sua intenção. O usuário consente ao concluir o fluxo OAuth. O consentimento do administrador é necessário para alguns escopos de maior privilégio (consulte a seção 7).
4
Gerar um segredo do cliente
Ir Certificados e segredos. Clicar + Novo segredo do cliente. Defina uma descrição e expiração.
Recomendação de expiração
730 dias (24 meses) é o máximo. Defina um lembrete no calendário 60 dias antes do vencimento; rotacionar um segredo expirado causa falhas de autenticação imediatas em todos os usuários.
Copie o valor imediatamente
O valor secreto é mostrado apenas uma vez. Armazene-o no seu gerenciador de segredos (por exemplo, AWS Secrets Manager, HashiCorp Vault, Azure Key Vault). Ele nunca mais será exibido depois que você sair desta página.
Alternativa recomendada: Para produção, use um certificado em vez de um segredo do cliente. Certificados são mais seguros (chave assimétrica), nunca expiram por acidente e são preferidos pela Microsoft para aplicativos de nível empresarial.
5
Copie seu ID do cliente e ID do locatário
Do Visão geral página de registro do seu aplicativo, copie dois valores que você precisará em todas as requisições OAuth:
ID do aplicativo (cliente)
Um UUID que identifica unicamente o registro do seu aplicativo. Usado como o id_cliente parâmetro em todas as requisições de autenticação.
ID do diretório (inquilino)
O ID do tenant da sua organização. Usado em URLs de autoridade de tenant único. Para aplicativos com vários tenants, você usa /comum em vez disso, mas mantenha este valor para as URLs de consentimento do administrador.
6
Habilitar Tokens de Identidade (Opcional, mas recomendado)
De volta em Autenticação, sob Fluxos implícito e híbrido, você pode habilitar Tokens de ID. Isso permite que você receba um JWT com declarações de identidade do usuário (nome, e-mail, ID do locatário) junto com o token de acesso, útil para fluxos de integração onde você deseja preencher previamente os dados do perfil do usuário.
Previsão para 2026: Para fluxos de auth-code puro + PKCE, os tokens de ID são retornados via endpoint de token, não pela concessão implícita. Você não precisa habilitar a concessão implícita. Habilite-a apenas se você tiver um SPA legado que não pode usar PKCE.
7
Opcional: Verifique seu domínio de editor
Em Marca e propriedades, defina o domínio do seu publicador para o domínio do seu produto. Isso substitui o rótulo "não verificado" na tela de consentimento pelo nome do seu domínio. Para aplicativos multilocatários direcionados a clientes corporativos, a conclusão da verificação da Microsoft Partner Network e a obtenção do status de "editor verificado" removem o aviso proeminente "Este aplicativo não é usado com frequência".
Domínio da editora
Um domínio que você possui e verificou via registro TXT ou via o fluxo de validação de domínio do Serviço de Aplicativo.
Editora verificada
Requer ID da Microsoft Partner Network (MPN) vinculado a uma identidade comercial verificada. Leva de 1 a 5 dias úteis. Melhora significativamente a conversão de clientes empresariais em telas de consentimento.
Pule a configuração: Construa com a Unipile em vez disso
Endpoints de Autoridade

Escolhendo o Ponto de Extremidade Correto da Autoridade da Microsoft

A URL de autoridade que você usa nas suas requisições OAuth determina quais tipos de contas da Microsoft podem se autenticar e quais tokens você recebe. Errar isso causa falhas silenciosas onde alguns usuários não conseguem se autenticar.

URL de Autoridade Aceita Caso de uso Ressalvas
/comumA MAIORIA DE SAAS Tanto as contas Microsoft Entra (trabalho/escola) quanto contas Microsoft pessoais (Outlook.com, Hotmail, Live) SaaS multilocatário atendendo a todos os usuários da Microsoft. Um único endpoint gerencia toda a sua base de usuários. Os tokens são emitidos pelo tenant de origem de cada usuário, não pelo seu. A validação do token deve usar o emissor específico do tenant ou aceitar múltiplos emissores. Não é possível impor políticas de Acesso Condicional.
/organizações Contas do Microsoft Entra ID somente (trabalho/escola). Não são aceitas contas pessoais da Microsoft. SaaS B2B voltado apenas para clientes corporativos, nunca para usuários consumidores do Outlook.com. Usuários com contas pessoais da Microsoft receberão um erro. Validação de token mais simples (padrão de emissor único aceitável).
/consumidores Apenas contas Microsoft pessoais (Outlook.com, Hotmail, Live). Aplicativos para consumidores focados em caixas de entrada pessoais. Raro para SaaS B2B. Contas do Microsoft 365 corporativas são rejeitadas. Não é útil para SaaS que atende usuários empresariais.
/{tenant-id} Contas em um locatário específico do Microsoft Entra apenas. Ferramentas internas de locatário único (aplicativo da sua própria empresa). Fluxos de consentimento do administrador direcionados a um locatário específico. Também usado no padrão de URL de redirecionamento de consentimento do administrador. Todos os usuários de outros inquilinos são rejeitados. Adequado apenas para aplicativos internos ou quando deliberadamente restrito a um inquilino de cliente.
/comum A MAIORIA DE SAAS
Aceita Tanto as contas Microsoft Entra (trabalho/escola) quanto contas Microsoft pessoais (Outlook.com, Hotmail, Live)
Caso de uso SaaS multilocatário atendendo a todos os usuários da Microsoft. Um único endpoint gerencia toda a sua base de usuários.
Ressalvas Os tokens são emitidos pelo tenant de origem de cada usuário, não pelo seu. A validação do token deve usar o emissor específico do tenant ou aceitar múltiplos emissores. Não é possível impor políticas de Acesso Condicional.
/organizações
Aceita Contas do Microsoft Entra ID somente (trabalho/escola). Não são aceitas contas pessoais da Microsoft.
Caso de uso SaaS B2B voltado apenas para clientes corporativos, nunca para usuários consumidores do Outlook.com.
Ressalvas Usuários com contas pessoais da Microsoft receberão um erro. Validação de token mais simples (padrão de emissor único aceitável).
/consumidores
Aceita Apenas contas Microsoft pessoais (Outlook.com, Hotmail, Live).
Caso de uso Aplicativos para consumidores focados em caixas de entrada pessoais. Raro para SaaS B2B.
Ressalvas Contas do Microsoft 365 corporativas são rejeitadas. Não é útil para SaaS que atende usuários empresariais.
/{tenant-id}
Aceita Contas em um locatário específico do Microsoft Entra apenas.
Caso de uso Ferramentas internas de locatário único (aplicativo da sua própria empresa). Fluxos de consentimento do administrador direcionados a um locatário específico. Também usado no padrão de URL de redirecionamento de consentimento do administrador.
Ressalvas Todos os usuários de outros inquilinos são rejeitados. Adequado apenas para aplicativos internos ou quando deliberadamente restrito a um inquilino de cliente.
Observação de validação de token para /common: Ao usar o /comum endpoint, o se (issuer) o claim no JWT será https://login.microsoftonline.com/{tenantId}/v2.0 onde {tenantId} varia por usuário. Configure sua biblioteca de validação JWT para aceitar qualquer emissor correspondente https://login.microsoftonline.com/{tenantId}/v2.0 em vez de uma string de emissor fixa.
Escopos de E-mail

Microsoft Graph Escopos de E-mail: Detalhamento Granular

O Microsoft Graph usa escopos de permissão para controlar o que seu aplicativo pode fazer. Solicitar muitos escopos aumenta o atrito na tela de consentimento e reduz a conversão. Solicitar poucos causa erros de tempo de execução. Aqui estão todos os escopos de Mail que você precisa saber.

Escopo Tipo O que ele permite Consentimento do administrador?
Mail.Read Delegado Ler todas as mensagens na caixa de correio do usuário autenticado. Inclui cabeçalhos, corpo, anexos. Somente leitura - não pode modificar ou enviar. Usuário
Mail.ReadBasic Delegado Ler propriedades limitadas da mensagem: assunto, remetente, destinatários, data. Não é possível ler o corpo da mensagem ou anexos. Útil para listagem leve de caixa de entrada sem acesso ao conteúdo completo. Usuário
Mail.ReadWrite Delegado Ler e modificar todas as mensagens. Inclui criar, atualizar, excluir mensagens e pastas. Superconjunto de Mail.Read - não solicite ambos. Usuário
Mail.Send Delegado Envie e-mails como o usuário autenticado. Necessário, mesmo que você também tenha Mail.ReadWrite - o envio é uma permissão separada no Microsoft Graph. Usuário
Mail.Read.Shared Delegado Ler e-mails em caixas de correio compartilhadas ou de outros usuários às quais o usuário autenticado recebeu acesso. Não para ler a caixa de correio do próprio usuário. Usuário
Mail.ReadWrite.Shared Delegado Ler e modificar e-mails em caixas de correio compartilhadas às quais o usuário tem acesso. Usuário
Mail.Send.Shared Delegado Enviar e-mail de caixas de correio compartilhadas ou "enviar em nome de" outro usuário (se esse usuário tiver concedido acesso). Usuário
acesso_offline Delegado Instrui a Microsoft a emitir um token de atualização. Sem isso, você recebe apenas um token de acesso de curta duração sem forma de renová-lo. Sempre obrigatório para aplicações SaaS. Usuário
openid Delegado Retorna um token de ID com a identidade básica do usuário. Necessário se você quiser saber quem se autenticou sem fazer uma chamada separada à API /me. Usuário
perfil Delegado Adiciona os campos "name" e "preferred_username" ao ID token. Geralmente incluído com "openid". Usuário
Mail.Read (App) Aplicativo Ler todos os e-mails em todas as caixas de correio no locatário sem interação do usuário. Usado por serviços de daemon. Requer consentimento do administrador do locatário. Administrador necessário
Mail.ReadWrite (Aplicativo) Aplicativo Ler e escrever em todas as caixas de correio de todos os inquilinos. Permissão muito ampla. Apenas para ferramentas internas confiáveis com aprovação explícita do administrador do inquilino. Administrador necessário
Mail.Read Delegado
Ler todas as mensagens na caixa de correio do usuário autenticado. Inclui cabeçalhos, corpo, anexos. Somente leitura - não pode modificar ou enviar.
Consentimento do usuário
Mail.ReadBasic Delegado
Ler propriedades limitadas da mensagem: assunto, remetente, destinatários, data. Não é possível ler o corpo da mensagem ou anexos. Útil para listagem leve de caixa de entrada sem acesso ao conteúdo completo.
Consentimento do usuário
Mail.ReadWrite Delegado
Ler e modificar todas as mensagens. Inclui criar, atualizar, excluir mensagens e pastas. Superconjunto de Mail.Read - não solicite ambos.
Consentimento do usuário
Mail.Send Delegado
Envie e-mails como o usuário autenticado. Necessário, mesmo que você também tenha Mail.ReadWrite - o envio é uma permissão separada no Microsoft Graph.
Consentimento do usuário
Mail.Read.Shared Delegado
Ler e-mails em caixas de correio compartilhadas ou de outros usuários às quais o usuário autenticado recebeu acesso. Não para ler a caixa de correio do próprio usuário.
Consentimento do usuário
Mail.ReadWrite.Shared Delegado
Ler e modificar e-mails em caixas de correio compartilhadas às quais o usuário tem acesso.
Consentimento do usuário
Mail.Send.Shared Delegado
Enviar e-mail de caixas de correio compartilhadas ou "enviar em nome de" outro usuário (se esse usuário tiver concedido acesso).
Consentimento do usuário
acesso_offline Delegado
Instrui a Microsoft a emitir um token de atualização. Sem isso, você recebe apenas um token de acesso de curta duração sem forma de renová-lo. Sempre obrigatório para aplicações SaaS.
Consentimento do usuário
openid Delegado
Retorna um token de ID com a identidade básica do usuário. Necessário se você quiser saber quem se autenticou sem fazer uma chamada separada à API /me.
Consentimento do usuário
perfil Delegado
Adiciona os campos "name" e "preferred_username" ao ID token. Geralmente incluído com "openid".
Consentimento do usuário
Mail.Read (App) Aplicativo
Ler todos os e-mails em todas as caixas de correio no locatário sem interação do usuário. Usado por serviços de daemon. Requer consentimento do administrador do locatário.
Administrador necessário
Mail.ReadWrite (Aplicativo) Aplicativo
Ler e escrever em todas as caixas de correio de todos os inquilinos. Permissão muito ampla. Apenas para ferramentas internas confiáveis com aprovação explícita do administrador do inquilino.
Administrador necessário
Escopo mínimo definido: leitor de caixa de entrada
scope=Mail.Readacesso_offlineopenidperfil
Ler mensagens, atualizar tokens, identidade do usuário. Sem capacidade de escrita ou envio.
Escopo padrão definido: integração completa de e-mail
scope=Mail.ReadWriteMail.Sendoffline_accessopenidprofile
Ler, escrever, enviar. O conjunto mais comum para integrações de CRM e ferramentas de vendas.
Veja o guia completo da API de E-mail
Modelo de Permissão

Permissões Delegadas vs. Permissões de Aplicativo: Quando Cada Uma se Aplica

O Microsoft Graph usa dois modelos de permissão fundamentalmente diferentes. A maioria dos desenvolvedores de SaaS acaba optando pelo modelo errado, o que leva a requisitos desnecessários de consentimento do administrador e a uma experiência de usuário prejudicada. Veja exatamente quando usar cada um.

Permissões Delegadas
Agir em nome do usuário conectado
O aplicativo acessa o Microsoft Graph usando a identidade do usuário autenticado. O aplicativo só pode fazer o que o próprio usuário poderia fazer. Se o usuário não puder ler uma pasta, seu aplicativo também não poderá.
Usuário concorda durante o fluxo OAuth - nenhum administrador necessário para escopos padrão
O acesso é limitado a cada caixa de correio individual do usuário
Os usuários podem revogar o acesso a qualquer momento nas configurações da conta Microsoft.
Respeita permissões de nível de usuário, atribuições de função e políticas de acesso a caixas de correio
Use isto para aplicações SaaS onde cada usuário se autentica individualmente
Permissões de Aplicativo
Aja como o próprio aplicativo
O aplicativo acessa o Microsoft Graph sem que nenhum usuário esteja presente. Usado para serviços em segundo plano, daemons e fluxos de trabalho automatizados. O aplicativo se autentica usando suas próprias credenciais (fluxo de credenciais do cliente).
Requer consentimento do administrador do tenant - uma barreira significativa para usuários externos
O acesso é para todo o tenant - pode ler TODAS as caixas de correio uma vez que o administrador conceda consentimento
Não é necessário login interativo do usuário - funciona para automação sem interface gráfica
Adequado para ferramentas internas de TI onde o administrador da sua organização controla a implantação
Apenas para ferramentas internas onde o administrador da sua organização concede acesso total ao tenant.
A Regra de Decisão de SaaS
Se você está construindo uma produto usado por clientes externos quem assina individualmente, usa Permissões delegadas. Cada cliente se autentica com sua própria conta Microsoft, consente com os escopos do seu aplicativo, e seu aplicativo opera em nome de esse usuário autenticado. As permissões do aplicativo exigem que um administrador do tenant aprove previamente seu aplicativo para toda a organização deles – uma etapa que prejudica a conversão em um funil de SaaS de autoatendimento. A única exceção é se você estiver criando uma ferramenta corporativa interna implantada pela sua própria equipe de TI no seu próprio tenant.
Guia Completo

Código de Autorização + PKCE: Exemplos Passo a Passo com Curl

Aqui está o fluxo completo de código de autorização OAuth 2.0 do Microsoft Graph com PKCE, desde a geração do code verifier até a troca de tokens. Estes são exemplos de nível de produção que você pode adaptar diretamente à sua stack.

Etapa 1 de 4 - Gerar Parâmetros PKCE
Gerar code_verifier e code_challenge
O PKCE funciona gerando um segredo aleatório (code_verifier), em seguida, um hash SHA-256 dele (code_challenge). Você envia o desafio na etapa 2 e o verifier na etapa 4. A Microsoft verifica se eles correspondem, impedindo a interceptação do código.
pkce_generate.py
import os, base64, hashlib # 1. Gerar code_verifier (43-128 caracteres, base64 compatível com URL) verifier_de_codigo = base64.urlsafe_b64encode( os.urandom(32) ).decodificar('utf-8').rstrip('=') # 2. Gerar code_challenge = BASE64URL(SHA256(code_verifier)) desafio_de_codigo = base64.urlsafe_b64encode( hashlib.sha256verificador_de_código.codificar('utf-8')).digest() ).decodificar('utf-8').rstrip('=') # Armazene o code_verifier na sessão — você precisará dele na etapa 4 # Enviar o código_desafio na URL de autorização
Passo 2 de 4 - Solicitação de Autorização
Crie o URL /authorize e redirecione o usuário
Redirecione o navegador do usuário para o ponto de extremidade de autorização da Microsoft. O usuário visualiza a página de login da Microsoft, se autentica e concede consentimento para os escopos do seu aplicativo. A Microsoft, então, redireciona de volta para o seu redirect_uri com um código de autorização.
id_cliente
Seu ID de aplicativo (cliente) do registro do aplicativo Entra
tipo_de_resposta
código solicita um código de autorização
redirect_uri
Deve corresponder exatamente a um URI registrado no seu aplicativo Entra. Codificado em URL.
escopo
Lista separada por espaços. Sempre inclua acesso_offline para tokens de atualização.
estado
Valor opaco que você gera. Retornado inalterado no callback. Use-o para prevenir CSRF e restaurar o estado da UI.
desafio_de_codigo
O valor BASE64URL(SHA256(code_verifier)) da etapa 1.
método_desafio_código
S256 - sempre use SHA-256, nunca plano
authorize_url.sh
# Construir a URL de autorização (formato para facilitar a leitura) URL_DE_AUTENTICACAO="https://login.microsoftonline.com/common/oauth2/v2.0/authorize ?client_id=SEU_CLIENT_ID &response_type=code &redirect;_uri=https://app.com/auth/ms/cb &scope;=Mail.ReadWriteMail.Sendoffline_access &estado=VALOR_ALEATÓRIO_DO_ESTADO &desafio_de_codigo=SEU_DESAFIO_DE_CODIGO &code_challenge_method=S256" # Redirecionar o usuário para $AUTH_URL # A Microsoft lida com o login, a autenticação multifatorial (MFA) e a tela de consentimento # Em caso de sucesso: redirect_uri?code=AUTH_CODE&state;=...
Passo 3 de 4 - Manipular o Callback
Receba o código de autorização em seu redirect_uri
A Microsoft redireciona para o seu redirect_uri com um código parâmetro de consulta. Valide o estado o parâmetro corresponde ao que você enviou. O código expira em 10 minutos - troque-o imediatamente na etapa 4.
Etapa 4 de 4 - Troca de Tokens
Troque o código de autorização por tokens de acesso + refresh
POST para o endpoint do token com o código e seu code_verifier. A Microsoft retorna um token de acesso (válido por ~60-90 minutos) e um token de atualização (longa duração). Armazene ambos com segurança.
token_exchange.sh
Código de autorização da # Exchange para tokens curl -X POST "https://login.microsoftonline.com/common/oauth2/v2.0/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "client_id=SEU_CLIENT_ID" \ -d "client_secret=SEU_CLIENT_SECRET" \ -d "grant_type=authorization_code" \ -d "código=AUTH_CODE_FROM_CALLBACK" \ -d "redirect_uri=https://app.com/auth/ms/cb" \ -d "code_verifier=SEU_CODE_VERIFIER" \ -d "scope=Mail.ReadWrite Mail.Send offline_access"
Retorna: access_token, refresh_token, expires_in, scope
token_resposta.json
{ "tipo_token": "Portador", "escopo": "Mail.ReadWrite Mail.Send offline_access", "expira_em": 3600, "token_de_acesso": "eyJ0eXAiOiJKV1Qi...", "token_de_atualização": "0.ARoAi7W...", "id_token": "eyJ0eXAi..." }
Ciclo de Vida do Token

Tratamento de Token de Atualização: Rotação, Expiração e Acesso Condicional

Os tokens de atualização do Microsoft Graph são de longa duração, mas não permanentes. Várias condições podem invalidá-los silenciosamente. Entender esses casos extremos é o que separa uma integração Microsoft OAuth de nível de produção daquelas que falham aleatoriamente para usuários corporativos.

Expiração por inatividade de 90 dias
Tokens de atualização da Microsoft expiram após 90 dias de inatividade. Se um usuário não usar seu aplicativo por 90 dias, seu token de atualização se tornará inválido e ele deverá se reautenticar. Não há como estender isso sem interação do usuário. Sempre lide concessão_inválida Tratar erros graciosamente e solicitar reautenticação.
Alterações na política de Acesso Condicional
Tenants corporativos usam políticas de Acesso Condicional (requisitos de MFA, conformidade do dispositivo, restrições de localização). Se uma política for alterada após um usuário se autenticar, seu token de atualização pode ser invalidado na próxima vez que for usado. Esta é uma decisão do lado do cliente – você não pode controlá-la ou prevê-la. Sempre propague erros de autenticação de volta para os usuários com um prompt claro de reautenticação.
Rotação de token de atualização
Ao usar um token de atualização para obter um novo token de acesso, a Microsoft pode emitir um novo token de atualização. Sempre salve o novo token de atualização da resposta, substituindo o antigo. Se você continuar a usar o token de atualização antigo após ele ter sido rotacionado, eventualmente você atingirá um concessão_inválida erro.
Revogação de administrador
Um administrador tenant pode revogar todos os tokens de atualização para um usuário ou para toda a organização a qualquer momento (por exemplo, quando um funcionário sai ou durante um incidente de segurança). Seu aplicativo recebe concessão_inválida. Este é o comportamento esperado - lide com isso marcando a conta vinculada como precisando de reautorização.
refresh_token.sh
# Atualizar o token de acesso usando o token de atualização armazenado curl -X POST "https://login.microsoftonline.com/common/oauth2/v2.0/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "client_id=SEU_CLIENT_ID" \ -d "client_secret=SEU_CLIENT_SECRET" \ -d "grant_type=refresh_token" \ -d "refresh_token=TOKEN_DE_ATUALIZAÇÃO_ARMAZENADO" \ -d "scope=Mail.ReadWrite Mail.Send offline_access" #: SEMPRE verifique se há um novo refresh_token na resposta. # Se estiver presente, substitua o armazenado imediatamente. # Se ocorrer o erro invalid_grant, solicite ao usuário que se autentique novamente.
Solução de problemas

Erros Comuns do AADSTS Decodificados

Os erros do Microsoft Graph OAuth seguem um padrão consistente de códigos de erro AADSTS. Estes são os mais comuns que você encontrará durante o desenvolvimento e a produção, com causas raiz e correções exatas.

Código de erro O que isso significa Causa raiz e correção
AADSTS65001 O consentimento não foi concedido para um ou mais dos escopos solicitados O usuário não consentiu com os escopos do seu aplicativo, ou um administrador de locatário bloqueou o consentimento do usuário para o seu aplicativo. Correção: Inclua consentimento em sua URL de autorização para forçar uma tela de consentimento nova, ou envie a URL de consentimento do administrador para o administrador do tenant.
Adicionar prompt=consentimento ou solicitar consentimento do administrador
AADSTS50011 Erro de conflito de URI de redirecionamento O redirect_uri Na sua solicitação, o URI de redirecionamento não corresponde exatamente a nenhum URI de redirecionamento registrado no seu registro de aplicativo Entra. Até mesmo uma diferença na barra final causa isso. Correção: Copie o URI exato do seu registro de aplicativo Entra e use-o literalmente.
Correção: correspondência exata de URI no registro de aplicativo do Entra
AADSTS700016 Aplicativo não encontrado no tenant O id_cliente não existe no tenant contra o qual está sendo autenticado. Comum ao usar uma autoridade específica para o tenant (/{tenant-id}) para um aplicativo multi-inquilino. Correção: Use /comum ou /organizações autoridade para aplicativos multilocatário.
Corrigir: mudar para a autoridade /common ou /organizations
AADSTS90099 O aplicativo não foi autorizado neste tenant (consent_required) O aplicativo existe, mas não foi consentido no tenant do usuário. Difere do AADSTS65001 no sentido de que o aplicativo inteiro é bloqueado, não apenas escopos específicos. Correção: Envie a URL de consentimento do administrador para o administrador de TI do cliente.
Corrigir: URL de consentimento do administrador para administrador do locatário do cliente
AADSTS70011 Concessão fornecida é inválida ou expirada O token de atualização ou o código de autorização expirou ou foi revogado. Os códigos de autorização expiram em 10 minutos. Os tokens de atualização expiram após 90 dias de inatividade ou revogação pelo administrador. Correção: Solicitar ao usuário que se reautentique desde o início do fluxo OAuth.
Correção: solicitar reautenticação completa
AADSTS50076 Autenticação multifator é exigida pela política de Acesso Condicional O tenant do usuário exige autenticação multifator para seu aplicativo. Esta é uma decisão do lado do cliente imposta pelo administrador do tenant. Seu aplicativo não pode contorná-la. O usuário precisa concluir o MFA. Se estiver usando o fluxo de código de autenticação, a Microsoft exibirá automaticamente o prompt de MFA no navegador. Problemas surgem em fluxos automatizados (credenciais de cliente) que não conseguem concluir o MFA.
Esperado: o usuário deve completar a MFA
AADSTS50020 Conta de usuário do provedor de identidade externo não existe no locatário O usuário está tentando se autenticar com uma conta pessoal da Microsoft em um locatário que permite apenas contas organizacionais, ou vice-versa. Correção: Verifique seu endpoint de autoridade - se estiver usando /organizações, contas pessoais não conseguem autenticar. Mude para /comum se você precisar de ambos.
Corrigir: mudar autoridade para /common
AADSTS53003 Acesso bloqueado pela política de Acesso Condicional A política de Acesso Condicional do locatário bloqueou completamente esta tentativa de autenticação (por exemplo, país bloqueado, dispositivo não gerenciado, aplicativo bloqueado). Esta é uma decisão do lado do cliente. Você não pode substituí-la. Apresente o erro ao usuário e aconselhe-o a contatar o administrador de TI.
Lado do cliente: orientar o usuário a entrar em contato com o administrador de TI
Deixe a Unipile cuidar de tudo para você
A Alternativa Unipile

Pule 5 Semanas de Trabalho com OAuth com Unipile

Tudo neste guia - registro de aplicativo Entra, endpoints de autoridade, seleção de escopo, PKCE, rotação de token, tratamento de erros AADSTS - é tempo de engenharia que não impulsiona seu produto. O Unipile lida com toda a pilha OAuth do Microsoft Graph como um serviço gerenciado, para que sua equipe escreva uma chamada de API em vez de 500 linhas de código OAuth complexo.

Construir você mesmo
Registro e configuração do aplicativo Entra
Implementação e geração de código de desafio PKCE
Armazenamento, rotação e tratamento de expiração de refresh tokens
Fluxo de consentimento do administrador para clientes empresariais
Tratamento de erros do AADSTS e prompts de reautenticação
Rotação do segredo do cliente antes do vencimento
Tratamento de ressalvas de Acesso Condicional por locatário
Separar pilhas OAuth para provedores Gmail e IMAP
Usando Unipile
Um POST para gerar um link de autenticação hospedado
Unipile gerencia PKCE, tokens e refresh automaticamente
Tokens nunca armazenados em seu banco de dados - Unipile cuida disso
Mesma API para contas Microsoft, Gmail e IMAP
Notificações de webhook quando as contas precisam de reautenticação
Tela de consentimento com a marca com suas próprias credenciais de aplicativo Entra
Envie sua integração de e-mail em horas, não em semanas
Como o OAuth do Microsoft no Unipile funciona
Seu backend chama um endpoint para gerar um link de autenticação hospedado. Seu usuário clica nele, autentica-se com a Microsoft e a Unipile gerencia o fluxo OAuth completo - redirecionamento Entra, tratamento de escopo, troca de tokens e atualização. A conta vinculada fica então disponível através da API unificada de e-mail da Unipile.
unipile_microsoft_oauth.py
import solicitações UNIPILE_API_URL = "https://apiXXX.unipile.com:XXX" UNIPILE_API_KEY = "your-api-key" # Etapa 1: Gerar um link de autenticação hospedado para a Microsoft response = requests.postagem( "{UNIPILE_API_URL}/api/v1/hosted/accounts/link", cabeçalhos={ "X-API-KEY": UNIPILE_API_KEY, "Tipo-de-Conteúdo": "application/json" }, json={ "tipo": "criar", "fornecedores": ["MICROSOFT"], "url_da_api": UNIPILE_API_URL, "expiraEm": "31/12/2026 23:59:59", # Opcional: vincule este link a um usuário específico "nome": "id_do_usuário_123", # Opcional: receber uma notificação quando a conta for vinculada "url_de_notificacao": "https://app.yourproduct.com/webhooks/account-linked" } ) # Etapa 2: Redirecione o usuário para esta URL url_autenticacao_hospedada = resposta.json()["url"] Exemplo de #: https://account.unipile.com/[encoded-token] # Unipile lida com: redirecionamento Entra, tela de consentimento, PKCE, Troca de tokens #, atualização do armazenamento de tokens, gerenciamento de escopo # Etapa 3: Após a autenticação, use a API de e-mail da Unipile para ler/enviar emails = requisições.obter( f"{UNIPILE_API_URL}/api/v1/emails", cabeçalhos={"X-API-KEY": UNIPILE_API_KEY}, parâmetros={"id_da_conta": "id-conta-vinculada"} )
Microsoft OAuth completo. Caixa de correio disponível via API unificada.
Fluxo de autenticação hospedado
Unipile hospeda a tela de consentimento OAuth. Seus usuários veem um fluxo limpo e com sua marca. Sem manutenção de URI de redirecionamento, sem problemas de CORS, sem malabarismos com URLs de localhost versus produção.
Gerenciamento de tokens
Unipile armazena e rotaciona tokens OAuth da Microsoft em seu nome. Rotação de token de atualização, monitoramento de inatividade de 90 dias e notificações de reautenticação são tratados automaticamente.
API de e-mail unificada
Após a vinculação, as caixas de correio Microsoft, Gmail e IMAP respondem aos mesmos endpoints de e-mail do Unipile. Uma integração atende aos três provedores.
Suas próprias credenciais do Entra
Configure suas credenciais de aplicativo do Microsoft Entra no painel Unipile. Seus usuários verão o nome do seu aplicativo na tela de consentimento da Microsoft, não o da Unipile.
Notificações por webhook
Receba um webhook quando uma conta vinculada precisar de reautenticação (token de atualização expirado, revogação de administrador, alteração de Acesso Condicional). Exiba o prompt de reautenticação imediatamente em seu produto.
Ler, enviar e sincronizar
Após o OAuth do Microsoft via Unipile, você pode ler e-mails, enviar e-mails, sincronizar conversas, gerenciar pastas e lidar com anexos - tudo através da API unificada de e-mail da Unipile. Nenhum cliente Microsoft Graph separado é necessário.
Como a Unipile opera
Unipile é um intermediário técnico independente que atua em nome de cada usuário autenticado via tokens OAuth emitidos pela Microsoft. Quando um usuário vincula sua caixa de correio do Outlook ou Microsoft 365, a Unipile opera exclusivamente utilizando as permissões delegadas desse usuário. A Unipile não é afiliada, endossada ou patrocinada pela Microsoft. Utilizamos a API pública Microsoft Graph em nome dos usuários finais autenticados. Cada conta opera dentro da identidade Microsoft Entra própria desse usuário e das políticas de Acesso Condicional de sua organização.
Comece a construir seu fluxo de OAuth da Microsoft Guia de E-mail do MS Graph
PERGUNTAS FREQUENTES

Perguntas frequentes

As perguntas mais comuns sobre o OAuth do Microsoft Graph para integração de e-mail, desde a seleção de escopos até o ciclo de vida do token e os fluxos de consentimento corporativo.

01
O Microsoft Graph OAuth funciona para contas do Outlook.com e do Microsoft 365?
Sim. Usando o /comum endpoint de autoridade, um único registro de aplicativo do Microsoft Entra lida com a autenticação para contas pessoais do Outlook.com e contas corporativas/escolares do Microsoft 365. A chave é selecionar "Contas em qualquer diretório organizacional e contas pessoais da Microsoft" ao registrar seu aplicativo no portal do Azure.
02
Quando um usuário do Microsoft 365 deixa sua empresa, os tokens do OAuth associados à sua conta geralmente são revogados ou expiram. Isso ocorre porque esses tokens concedem acesso a recursos em nome do usuário, e quando o usuário não faz mais parte da organização, esse acesso precisa ser desativado por segurança. Aqui está um detalhamento mais específico: * **Revogação pela organização:** A organização (através de seus administradores do Microsoft 365/Azure AD) tem a capacidade de revogar ativamente as permissões e sessões de qualquer usuário. Quando um usuário é removido da organização, políticas de segurança geralmente entram em vigor para revogar todos os tokens de acesso e atualização associados a essa conta. * **Expiração de tokens de atualização:** Os tokens de atualização, que são usados para obter novos tokens de acesso sem que o usuário precise fazer login novamente, têm um tempo de vida definido. Mesmo que não sejam revogados ativamente, eles eventualmente expirarão. * **Revogação de tokens de acesso:** Os tokens de acesso, que são usados para acessar APIs e recursos, têm um tempo de vida muito mais curto. Eles expiram rapidamente e precisam ser substituídos por novos tokens usando os tokens de atualização. * **Exclusão da conta do usuário:** Quando a conta do usuário é excluída, todos os dados e permissões associados a ela, incluindo quaisquer tokens pendentes, são removidos. **Em resumo:** A segurança da organização dita que o acesso concedido por tokens OAuth seja desativado quando um usuário deixa a empresa. Isso é feito principalmente através da revogação ativa pela administração ou pela expiração natural dos tokens, agravada pela exclusão da conta do usuário.
Quando um administrador de TI desabilita ou exclui uma conta de usuário no Microsoft Entra ID, todos os tokens de atualização desse usuário são revogados imediatamente. Sua próxima tentativa de atualizar o token retorna um concessão_inválida erro. Lide com isso de forma elegante: marque a conta vinculada como necessitando de reautenticação e apresente um prompt de reautenticação claro em seu produto. Este é o comportamento esperado - uma decisão do lado do cliente além do seu controle.
03
O consentimento do administrador é necessário para ler e-mails do Outlook via Microsoft Graph OAuth?
Não, para permissões Delegadas padrão. Mail.Read, Mail.ReadWritee Mail.Send são escopos de consentimento do usuário - usuários individuais podem aprová-los durante o fluxo OAuth. O consentimento do administrador é necessário apenas para permissões de aplicativo ou escopos de alto privilégio como User.Read.All. Alguns locatários empresariais configuram políticas que bloqueiam todo o consentimento de aplicativos de terceiros - essa é uma decisão do lado do cliente.
04
Os tokens de atualização do Microsoft Graph duram 90 dias.
Tokens de atualização expiram após 90 dias de inatividade. Contanto que seu aplicativo use o token de atualização regularmente (o que acontece automaticamente ao atualizar tokens de acesso antes que expirem a cada 60-90 minutos), o token de atualização permanecerá ativo. Mudanças na política de Acesso Condicional, redefinições de senha ou revogação por um administrador podem invalidá-los mais cedo. Sempre trate concessão_inválida erros e substituir tokens de atualização antigos pelos novos retornados em cada resposta do token.
05
Qual é a diferença entre AADSTS65001 e AADSTS90099?
AADSTS65001: O usuário ainda não consentiu com um ou mais escopos específicos. Corrigir: adicionar consentimento para a sua URL de autorização para forçar uma tela de consentimento renovada. AADSTS90099Toda a aplicação não foi autorizada nesse inquilino - o administrador do inquilino precisa pré-aprovar seu aplicativo. Envie a URL de consentimento do administrador para o administrador de TI do cliente. Ambos os erros são comuns em cenários corporativos onde os inquilinos restringem o consentimento do usuário.
06
Posso usar o mesmo registro de aplicativo Entra para ler e enviar e-mails?
Sim. Solicitar ambos Mail.ReadWrite e Mail.Send no mesmo escopo string. Note que Mail.ReadWrite e Mail.Send são escopos separados - ter acesso de leitura/gravação não concede automaticamente permissão de envio. Inclua sempre acesso_offline para garantir que você receba um token de atualização. Veja a Página da API de e-mail para detalhes de implementação.
07
A Unipile armazena tokens OAuth da Microsoft no meu banco de dados?
Não. Ao usar o fluxo de autenticação Microsoft hospedado da Unipile, a Unipile gerencia todos os tokens OAuth em seu nome. Sua aplicação nunca lida diretamente com tokens de acesso ou tokens de atualização da Microsoft. Você interage com contas vinculadas exclusivamente através da API unificada de e-mail da Unipile usando sua chave de API da Unipile. Isso elimina requisitos de armazenamento, rotação e segurança de tokens da sua própria infraestrutura.
08
A Unipile é afiliada à Microsoft?
Não. A Unipile não é afiliada, endossada ou patrocinada pela Microsoft. A Unipile é um intermediário técnico independente que utiliza a API pública do Microsoft Graph em nome de usuários finais autenticados. Cada integração opera por meio de tokens OAuth emitidos pela Microsoft sob a própria identidade do usuário e as políticas de Acesso Condicional de sua organização. Microsoft Graph e Microsoft Entra são marcas registradas da Microsoft Corporation.
Ainda tem dúvidas? Nossa equipe pode te guiar pelo OAuth do Microsoft Graph para o seu caso de uso específico.
pt_BRBR
en_USEN fr_FRFR es_ESES de_DEDE it_ITIT nl_NLNL pl_PLPL tr_TRTR pt_BRBR