Desmistificando o OAuth 2.0 no Microsoft Graph: permissões delegadas versus permissões de aplicativo

By Mirko Peters · 2026-08-11 · Updated 2026-08-28

Automatically translated with AI from the original post. Read the English original

Titelbild: Demystifying OAuth 2.0 in Microsoft Graph: Delegated vs. Application Permissions

Bem-vindo de volta ao blog! Se você tem se aprofundado na automação do Microsoft 365, provavelmente já esbarrou nas limitações dos conectores nativos e dos scripts tradicionais. Lidar com a complexidade da autenticação pode ser complicado ao automatizar o M365, especialmente quando é preciso equilibrar segurança robusta com funcionamento sem atritos. Seja você um desenvolvedor de aplicativos corporativos personalizados ou alguém que está configurando processos automatizados em segundo plano, dominar os modelos de autenticação é essencial. Este post explica tokens, escopos e fluxos de consentimento para ajudar você a escolher o modelo certo, seja para tarefas centradas no usuário ou para processos não assistidos em segundo plano. Vamos direto ao ponto e entender como o OAuth 2.0 viabiliza a API do Microsoft Graph.

Introdução à autenticação no Microsoft Graph

O Microsoft Graph é o gateway unificado para todo o ecossistema do Microsoft 365. Em vez de interagir com APIs separadas e fragmentadas para Exchange, SharePoint, Teams e Azure Active Directory (agora Microsoft Entra ID), desenvolvedores e administradores de TI podem acessar todos esses serviços por meio de um único endpoint. No entanto, como o Graph controla o acesso a dados corporativos sensíveis, proteger esse gateway exige um framework de autenticação rigoroso. Entender como identidade, tokens de acesso e permissões se relacionam é o primeiro passo para criar automações confiáveis e seguras, que não se quebrem sob pressão nem disparem alertas de segurança.

Entendendo o OAuth 2.0 no contexto do Microsoft 365

Na essência, o Microsoft Graph depende do protocolo OAuth 2.0 para autorização. Quando sua aplicação ou script quer se comunicar com o Graph, não pode simplesmente enviar credenciais em texto puro pela rede. Em vez disso, ele precisa solicitar um token de acesso à plataforma de identidade da Microsoft (Entra ID). Esse token de acesso funciona como um passaporte digital seguro. Ele informa ao Microsoft Graph quem está fazendo a solicitação, qual aplicativo está sendo usado e, o mais importante, quais permissões específicas (escopos) foram concedidas a esse token. Sem um token válido, o Graph rejeitará imediatamente a solicitação com um erro padrão de não autorizado.

Permissões delegadas: quando executar como o usuário

A escolha do modelo de permissões depende totalmente da natureza da sua carga de trabalho. As permissões delegadas são feitas para aplicativos que funcionam com o respaldo de um usuário conectado. Quando um aplicativo usa permissões delegadas, ele age em nome do usuário que está conectado naquele momento. Se um usuário executar um script para ler o próprio calendário ou atualizar a foto de perfil, o Graph avalia a solicitação não só com base no que o aplicativo tem permissão para fazer, mas também no que o próprio usuário tem permissão para acessar. Se o usuário não tiver permissão para visualizar uma caixa de correio específica, o token delegado também não a concederá. Esse modelo é ideal para aplicativos voltados ao usuário, ferramentas interativas e scripts de produtividade pessoal.

Permissões de aplicativo: viabilizando processos não assistidos em segundo plano

Por outro lado, o que acontece quando você precisa executar um script ou serviço à meia-noite sem nenhum usuário diante do teclado? Para processos não assistidos em segundo plano, serviços daemon e ferramentas de relatório em todo o locatário, você precisa de permissões de aplicativo. Nesse modelo, o aplicativo opera de forma independente de qualquer contexto de usuário: ele roda com identidade própria. Como não há um usuário humano para entrar e conceder consentimento de forma interativa, as permissões de aplicativo exigem pré-autorização explícita de um administrador do locatário. Uma vez concedidas, o aplicativo pode acessar dados de toda a organização, o que torna esse modelo extremamente poderoso para automação administrativa, scripts de onboarding e monitoramento de conformidade, mas também exige supervisão de segurança rigorosa.

Navegando por escopos, tokens e fluxos de consentimento

O vocabulário de autenticação e autorização às vezes pode parecer avassalador, mas dividir o fluxo de trabalho deixa o processo mais claro. Escopos são as permissões específicas que o seu aplicativo solicita, como User.Read.All ou Mail.Read. Quando um usuário ou administrador autoriza um app, ele está revisando e aprovando esses escopos. Depois de aprovados, a plataforma de identidade emite um JSON Web Token (JWT). Seu código inclui esse token no cabeçalho HTTP Authorization de cada requisição enviada ao Microsoft Graph. Gerenciar o consentimento corretamente garante que seu app consiga obter esses tokens sem problemas e sem esbarrar em obstáculos inesperados.

Evitando o purgatório do consentimento de administrador

Um dos pontos de atrito mais comuns para desenvolvedores e administradores é ficar preso aguardando a aprovação administrativa. Quando um aplicativo solicita escopos de aplicativo com privilégios elevados ou escopos delegados sensíveis, o Microsoft Entra ID pode exigir que um administrador consinta com o aplicativo antes que qualquer token possa ser emitido. Se o seu pipeline de implantação pressupõe que os usuários podem consentir por conta própria e, de repente, eles são bloqueados por políticas do locatário, sua automação para por completo. Para evitar o purgatório do consentimento de administrador, mapeie sempre as permissões necessárias antecipadamente, documente a justificativa de negócio e coordene com seus administradores globais ou de aplicativos para pré-configurar o consentimento em todo o locatário, sempre que necessário.

Armadilhas comuns e como corrigi-las

Mesmo desenvolvedores experientes às vezes encontram obstáculos de autorização frustrantes ao trabalhar com o Microsoft Graph. Vamos ver alguns problemas comuns e como resolvê-los:

Funciona para mim, falha para os outros: geralmente causado por consentimento ausente ou escopos incorretos. Correção: documente claramente os escopos necessários e configure o consentimento de administrador em todo o locatário, quando apropriado.
Overfetching de payloads gigantes: buscar listas inteiras de usuários sem filtrar leva a timeouts e throttling. Correção: use $select, $top, paginação e consultas delta.
Loops infinitos de 401/403: causados por um token expirado ou pelo uso de um tipo de permissão delegada em um trabalho sem usuário. Correção: implemente renovação de token robusta e mude para permissões de aplicativo em tarefas em segundo plano.
Atingindo limites de taxa: receber respostas 429 significa que você está enviando requisições rápido demais. Correção: implemente backoff exponencial, respeite o cabeçalho Retry-After e agrupe operações em lote.
Proliferação de segredos: codificar segredos de cliente diretamente em scripts é um risco de segurança enorme. Correção: utilize o Azure Key Vault, identidades gerenciadas ou variáveis de ambiente seguras.

Melhores práticas de segurança e governança

Ao abrir a porta do seu locatário do Microsoft 365 por meio de API, a segurança deve ser sua prioridade máxima. Seguir o princípio do menor privilégio significa solicitar apenas o mínimo absoluto de escopos necessários para o seu aplicativo funcionar — nunca solicite Directory.AccessAsUser.All apenas para ler o nome de exibição de um usuário. Mantenha um registro claro de consentimentos detalhando quais apps têm acesso ao seu locatário, isole completamente os registros de aplicativos de desenvolvimento, teste e produção, e estabeleça uma programação rigorosa para a rotação de segredos de cliente e certificados.

Suas primeiras consultas reais (exemplos)

Quando a sua modelagem de autenticação estiver resolvida, você pode começar a executar consultas na API do Graph. Aqui estão alguns exemplos práticos que você pode adaptar:

Novos contratados desde uma data:
GET /users?$filter=createdDateTime ge 2025-10-01T00:00:00Z&$select=id,displayName,mail,department
Minhas próximas reuniões:
GET /me/events?$top=10&$select=subject,start,end,organizer,webLink
Membros de um grupo:
GET /groups/{group-id}/members?$select=id,displayName,mail
Usuários alterados (delta):
GET /users/delta?$select=id,displayName,mail

Ferramentas recomendadas

Usar as ferramentas certas facilita muito a criação e a depuração de consultas do Microsoft Graph. O Graph Explorer é um playground web indispensável para testar endpoints e verificar dicas de consentimento. Para escrever código, os SDKs do Microsoft Graph (.NET, JavaScript, Python) abstraem grande parte da infraestrutura HTTP subjacente. Extensões como Postman ou REST Client no seu IDE são excelentes para gerenciar coleções e ambientes, enquanto Power Automate, Logic Apps e PowerShell cuidam brilhantemente da automação de fluxos visuais e operacionais.

Perguntas frequentes

Delegado ou Aplicativo: como escolher?

Tarefas centradas no usuário são mais bem mapeadas para permissões delegadas. Tarefas não supervisionadas, daemons em segundo plano e tarefas administrativas amplas exigem permissões de aplicativo, combinadas com o consentimento de administrador adequado.

Como evito o throttling?

Use $select para limitar o tamanho das cargas, implemente paginação e consultas delta, agrupe solicitações em lote sempre que possível e crie seus scripts para tratar com elegância os códigos de status 429, com lógica de nova tentativa.

Dá para usar o Graph sem programar?

Sim! Você pode prototipar endpoints no Graph Explorer e orquestrar fluxos de trabalho usando o Power Automate. Para lógicas mais complexas, passe a usar os SDKs oficiais ou scripts do PowerShell.

O Graph é seguro o bastante para relatórios de conformidade?

Com certeza. Quando implementado com o princípio do privilégio mínimo, registro de logs centralizado, fluxos de consentimento auditados e gerenciamento seguro de segredos, o Microsoft Graph atende a rigorosos padrões de conformidade corporativa.

Conclusão

Dominar a autenticação no Microsoft Graph é o grande diferencial para qualquer administrador, arquiteto ou desenvolvedor que queira realmente aproveitar o potencial do Microsoft 365. Ao entender a distinção fundamental entre permissões delegadas e de aplicativo, gerenciar com cuidado seus escopos e tokens e seguir uma governança de segurança rigorosa, você pode criar automações ao mesmo tempo poderosas e seguras. Para aprofundar ainda mais o tema, explorar exemplos de código e conhecer estratégias avançadas de tratamento de erros e throttling, não deixe de conferir o episódio de podcast relacionado: Automate Microsoft 365 with Microsoft Graph API. Boas automações!