OAuth2 no Moodle 5.3: Como Migrar as Integrações do Seu AVA

O OAuth2 no Moodle chegou de verdade com o Moodle 5.3 LTS, lançado em 5 de outubro de 2026, e muda a forma de autenticar ERP, sistema acadêmico, CRM e apps que conversam com o seu AVA. Em vez de um token estático que vive anos colado num arquivo de configuração, você passa a ter tokens que expiram em uma hora, segredos com validade e revogação imediata. Este guia mostra o que mudou, o que ainda não mudou e como planejar a migração sem quebrar nenhuma integração.

TL;DR

• O Moodle 5.3 trouxe um servidor OAuth 2 próprio, gerenciador de clientes, tokens pessoais de acesso e endpoints de revogação (notas oficiais da versão).
• Esses tokens valem só para a nova REST API (/api/rest/v2). Os web services clássicos continuam usando o token estático de sempre. São sistemas separados.
• A nova REST API ainda cobre poucas partes do Moodle. Matrícula, cadastro e notas seguem nos web services clássicos em 2026.
• O certo agora não é "migrar tudo", e sim inventariar, isolar a autenticação e migrar por função, à medida que a REST API cresce.
• Armadilha nova: por padrão, todo usuário autenticado pode criar token pessoal. Revise essa permissão no dia do upgrade.

O que é OAuth2 no Moodle 5.3 (e o que ele não é)

Até o 5.2, quem integrava um sistema externo com o Moodle tinha basicamente um caminho: os web services clássicos. Você habilita os web services, ativa o protocolo REST, cria um serviço externo com as funções liberadas e gera um token para um usuário técnico. Esse token vai na URL (wstoken=...) de cada chamada a webservice/rest/server.php. Ele não expira sozinho, a menos que alguém preencha o campo "válido até".

O OAuth 2 é um protocolo padrão de autorização (RFC 6749, da IETF). Em vez de uma senha fixa, o sistema cliente troca credenciais por um access token de vida curta e pede outro quando ele vence. Quem manda no que o token pode fazer são os escopos (scopes), uma lista de permissões explícitas.

No Moodle 5.3, isso aparece em uma lista de tickets de desenvolvimento que vale conhecer, porque cada um vira uma tela ou um comportamento novo no seu site:

• MDL-89251: implementação do servidor OAuth 2 no backend
• MDL-89181: gerenciador de clientes OAuth 2
• MDL-88473: endpoints e lógica de revogação de token
• MDL-88468 e MDL-88472: telas de gestão de clientes e dos fluxos de login OAuth 2
• MDL-87706: interface de tokens pessoais de acesso

Agora o ponto que quase todo anúncio de lançamento pula: o OAuth2 no Moodle 5.3 não substitui o token dos web services clássicos. A documentação oficial de REST API tokens é explícita: os tokens novos funcionam só com a nova REST API, têm páginas próprias de criação e gestão, e a opção "Habilitar web services" nem afeta eles. O token clássico continua lá, gerenciado em Administração do site > Servidor > Web services > Gerenciar tokens.

Se você quer o panorama geral de integração antes de entrar nos detalhes de autenticação, comece pelo nosso guia sobre como integrar Moodle com outros sistemas. Este post é o aprofundamento da parte de OAuth 2.

Token estático vs OAuth2 no Moodle: a comparação que importa

Antes de comparar, uma definição prática: adotar OAuth2 no Moodle significa trocar credenciais permanentes por credenciais temporárias e com escopo. O token estático tem uma vantagem real: é simples. Uma linha de configuração e o ERP fala com o Moodle. O problema é o que acontece depois. Em auditorias de ambientes que assumimos, é comum achar token criado anos atrás, ligado a uma conta de administrador, sem restrição de IP e sem data de validade. Se vazou num repositório, num log ou num e-mail, ele vale até alguém lembrar de revogar.

A tabela resume as três formas de autenticar uma integração no Moodle 5.3:

Critério	Token de web service (clássico)	Token pessoal de acesso (novo)	Cliente OAuth 2 (novo)
Onde funciona	Funções dos web services clássicos	Só a nova REST API	Só a nova REST API
Quem cria	Administrador ou usuário com permissão	O próprio usuário, em Preferências	Administrador registra o app
Validade	Indefinida, se ninguém preencher "válido até"	7 dias a 1 ano (padrão: 1 mês)	Access token de 1 hora
Renovação	Manual	Criar outro token	Refresh token (1 mês) ou novo pedido
Limite de permissão	Funções do serviço + permissões do usuário	Escopos + permissões do usuário	Escopos (+ usuário, no fluxo com login)
Revogação	Apagar o token	Imediata, pela tela do usuário	Imediata; desativar o cliente corta tudo
Melhor uso hoje	ERP, matrícula, notas, catálogo	Scripts e automações pontuais	Apps e integrações novas na REST API

Os números das duas últimas colunas vêm da documentação oficial de clientes OAuth 2 e de tokens pessoais de acesso.

Por que o OAuth 2 reduz o estrago de um vazamento

Com OAuth2 no Moodle, um access token roubado vale no máximo uma hora. O segredo do cliente expira em um ano. E, se algo parecer errado, desativar o cliente invalida na hora os tokens emitidos e impede o uso dos segredos. Para quem precisa responder a um questionário de segurança ou de LGPD no Moodle, isso troca "temos uma chave eterna em algum lugar" por "temos credenciais com prazo, escopo e trilha".

Onde o token estático ainda vence

Simplicidade operacional. Implantar OAuth2 no Moodle pressupõe que o sistema do outro lado saiba pedir e renovar token. O ERP legado que só sabe mandar um parâmetro fixo na URL não vai aprender a renovar token sozinho. Nesse caso, migrar exige uma peça no meio (falo dela adiante), e isso tem custo.

Os dois fluxos do OAuth 2 no 5.3: qual serve para cada integração

Quem configura OAuth2 no Moodle precisa decidir duas coisas logo no começo. Ao registrar um cliente em Administração do site > Servidor > OAuth 2 clients, você escolhe o tipo de cliente e o fluxo principal. As duas escolhas não podem ser alteradas depois. Errou, cria outro cliente.

Authorization Code: quando existe um usuário do outro lado

É o fluxo do "entrar com o Moodle". O usuário faz login no Moodle, vê os escopos que o app pede e aprova ou cancela. O app recebe um access token de 1 hora e um refresh token de 1 mês. Se o usuário já aprovou todos os escopos antes, o Moodle não pergunta de novo.

Serve para:

• App mobile próprio da instituição. Como o app roda no celular do aluno, ele é um cliente público: não consegue guardar segredo. Nesse caso o Moodle exige PKCE (RFC 7636), uma proteção que impede o uso de um código de autorização interceptado.
• Portal do aluno ou painel que mostra dados do próprio usuário.
• Ferramentas de professor que agem em nome de quem está logado.

O endereço de retorno (callback) precisa ser HTTPS, com exceção de localhost para desenvolvimento.

Client Credentials: máquina falando com máquina

Sem usuário logado. O sistema servidor troca ID e segredo do cliente por um access token. Não existe refresh token: quando o token vence, a integração pede outro. Só clientes confidenciais (que rodam num servidor que você controla) podem usar esse fluxo.

É o candidato natural para ERP, sistema acadêmico e CRM quando a operação já existe na REST API. Também é onde o OAuth2 no Moodle exige mais disciplina. Mas leia o alerta da própria documentação com atenção: no Client Credentials, o app age como o administrador principal do site, limitado apenas pelos escopos. Qualquer pessoa com o ID e um segredo válido consegue usar. Escopo largo aqui é uma chave mestra com prazo de validade.

O limite real do OAuth2 no Moodle em 2026: a REST API ainda é parcial

A nova REST API é construída sobre o subsistema de roteamento do Moodle (baseado no Slim Framework), disponível desde o 4.5. As rotas do grupo api ficam sob o prefixo /api/rest/v2, segundo a documentação de roteamento para desenvolvedores. Administradores navegam pelos endpoints e pelos escopos exigidos em Administração do site > Desenvolvimento > Moodle REST API UI, uma interface Swagger.

O problema é a cobertura. A documentação do 5.3 diz que apenas algumas partes do Moodle estão disponíveis pela REST API e que mais virão em versões futuras. Na prática, para quem integra ERP e sistema acadêmico, isso significa:

1. Criar usuário, matricular, desmatricular e devolver nota continuam dependendo das funções clássicas, como core_user_create_users e enrol_manual_enrol_users.
2. Um token OAuth 2 não chama essas funções. Não existe ponte entre os dois mundos.
3. Os escopos disponíveis variam por site, porque plugins podem acrescentar os seus. Não confie em lista genérica: confira no Swagger do seu Moodle.

Ou seja: hoje, o OAuth2 no Moodle resolve bem apps e leituras que já estão cobertas pela REST API. A integração pesada de secretaria acadêmica ainda roda no token clássico. Quem vende "migração completa para OAuth 2" neste momento está vendendo algo que o próprio Moodle ainda não entrega.

Como planejar a migração das integrações para OAuth2 no Moodle

A migração boa é gradual e começa antes de mudar qualquer token. Planejar OAuth2 no Moodle é, antes de tudo, um trabalho de inventário. Este é o roteiro que usamos.

1. Inventarie todo token que existe hoje

Abra Gerenciar tokens e liste cada token: usuário, serviço, funções liberadas, restrição de IP, data de validade e quem usa. Em quase todo inventário aparece pelo menos um token que ninguém sabe a quem pertence. Esse é o primeiro a investigar.

2. Classifique cada integração

Para cada sistema, responda três perguntas:

• Existe usuário humano no fluxo? Se sim, o alvo é Authorization Code. Se não, Client Credentials.
• As operações que ele faz já existem na REST API? Confira no Swagger. Se não existem, ele fica no token clássico por enquanto.
• O sistema do outro lado consegue renovar token? ERP fechado que não aceita lógica de renovação vai precisar de um intermediário.

3. Isole a autenticação numa camada intermediária

É a decisão que mais economiza dinheiro a longo prazo. O código de negócio do ERP não deveria chamar o Moodle direto. Ele chama um pequeno serviço de integração, que sabe se autenticar, renovar token, registrar log e repetir chamadas com segurança. Quando a função de matrícula migrar para a REST API, você troca um módulo, não reescreve a integração. Descrevemos esse desenho no guia técnico do SGA conectado ao Moodle.

4. Endureça o que fica no token clássico

Enquanto a função não migra, reduza o risco do token estático: usuário técnico dedicado (nunca o administrador), serviço com só as funções necessárias, restrição de IP e data de validade. Tudo isso já existe nos web services clássicos e quase ninguém usa.

5. Pilote com um caso pequeno e de leitura

O primeiro teste de OAuth2 no Moodle em produção deve ser algo que só lê dados e cujo erro não tranca aluno do lado de fora: um painel, um relatório, uma tela do app. Teste a renovação de token, a expiração do segredo e a revogação antes de colocar escrita em produção.

6. Rode em paralelo e só então revogue

Mantenha a integração antiga ativa até a nova passar por um ciclo completo (um fechamento de período, por exemplo). Depois revogue o token clássico. Não antes.

Armadilhas que vão aparecer no upgrade para o 5.3

Todo usuário pode criar token pessoal por padrão

A capacidade moodle/api:createtoken vem concedida ao papel "Usuário autenticado". Na prática, qualquer aluno pode gerar um token para a REST API, dentro das próprias permissões e escopos. Para a maioria das instituições isso não faz sentido. Decida conscientemente: remova a capacidade do papel padrão e conceda só a quem precisa.

A tela de clientes OAuth 2 some sem as dependências do Composer

Os clientes OAuth 2 só aparecem se as dependências do Composer do site estiverem instaladas. Instalação feita "descompactando o zip" em hospedagem compartilhada costuma não ter isso, e a tela simplesmente não existe. Não é bug. É requisito.

Segredo que vence em um ano derruba integração

Segredos de cliente confidencial expiram em um ano e aparecem só uma vez, na criação. O Moodle permite até dois segredos ativos ao mesmo tempo exatamente para você rotacionar sem parada: gera o novo, troca no sistema cliente, revoga o antigo. Coloque a data de expiração no calendário de operação no dia em que criar o cliente.

Plugins de web service antigos vão quebrar

O 5.3 deprecou as antigas classes \external_* (MDL-81225). Plugin próprio ou de terceiro que ainda usa essas classes funciona hoje com aviso e tende a quebrar numa versão seguinte. Inclua isso no inventário.

O próprio upgrade tem pré-requisitos pesados

O Moodle 5.3 exige PHP 8.3 ou superior (64 bits, com a extensão sodium e max_input_vars de pelo menos 5000), PostgreSQL 17, MySQL 8.4 ou MariaDB 11.4, e só atualiza a partir do Moodle 4.4. Se o seu AVA está no 4.1 ou 4.3, há uma etapa intermediária. Detalhei o caminho no checklist para atualizar o Moodle 4.5 para o 5.

Quando NÃO migrar para OAuth2 no Moodle agora

Há cenários em que adiar o OAuth2 no Moodle é a decisão certa:

• Seu AVA ainda não está no 5.3. Primeiro o upgrade, com homologação. Misturar as duas mudanças multiplica o risco.
• A integração faz só operações que a REST API ainda não cobre. Não existe para onde migrar. Endureça o token clássico e espere.
• O sistema do outro lado não suporta renovação de token e não há orçamento para a camada intermediária neste ciclo.
• Volume baixo e processo manual estável. Se a secretaria importa um CSV por semana sem erro, a prioridade provavelmente é outra.

E há o cenário oposto, em que vale começar já: app mobile novo, portal do aluno em desenvolvimento ou qualquer projeto que nasce agora. Construir hoje em cima do token clássico é criar a dívida que você vai pagar daqui a duas versões. Para quem está avaliando app próprio, o OAuth 2 com PKCE muda a conta de segurança, e escrevi sobre o investimento em app próprio de Moodle.

Sobre prazo: o 5.3 é LTS, com suporte geral até 4 de outubro de 2027 e correções de segurança até 1º de outubro de 2029, segundo o calendário oficial de versões. Há tempo para fazer a migração em etapas, sem pressa e sem improviso.

Quanto custa e quanto tempo leva

Não existe preço de tabela para migrar integrações para OAuth2 no Moodle, porque o custo depende do número de integrações e do que cada sistema do outro lado aceita. Mas dá para saber onde o dinheiro vai:

• Inventário e classificação: é a etapa mais barata e a que mais evita desperdício. Em geral, poucos dias.
• Camada intermediária: é o investimento real. Uma vez feita, ela serve a todas as integrações.
• Migração por função: cada fluxo migrado exige teste de renovação, expiração e revogação, além de homologação com cópia do Moodle.
• Sustentação: o Moodle lança versões em abril e outubro. A cada uma, a REST API pode ganhar endpoints e escopos novos, e vale reavaliar o que pode sair do token clássico.

Se o orçamento que você recebeu não prevê ambiente de homologação nem revisão a cada versão, ele não é mais barato. É incompleto.

Como a Agathas Web resolve isso

A Agathas Web trabalha com Moodle há mais de 15 anos. Nosso time tem a Moodle Developer Certification pela Moodle Academy e opera AVAs em produção, do servidor ao app. Somos uma empresa independente, não um Moodle Partner. Planejar e executar a adoção de OAuth2 no Moodle faz parte do nosso serviço de desenvolvimento e sustentação de Moodle.

O que entra no projeto:

• Inventário de tokens e integrações, com classificação do que migra agora, do que espera e do que precisa ser endurecido
• Upgrade para o 5.3 LTS com homologação, incluindo os requisitos de PHP, banco e Composer que fazem a tela de clientes OAuth 2 existir
• Camada de integração com renovação de token, log, fila e idempotência, para ERP, sistema acadêmico (inclusive o nosso SGA), CRM e gateway de pagamento
• Configuração de clientes OAuth 2 com escopos mínimos, rotação de segredo agendada e revisão da permissão de token pessoal
• App mobile e WhatsApp pela API Oficial, disparados por eventos do Moodle e autenticados do jeito certo
• Hospedagem gerenciada dedicada a Moodle, com monitoramento e backup verificado

Como funciona: começamos por uma conversa de diagnóstico para entender os sistemas, o volume e onde dói. Depois vem uma proposta técnica com arquitetura, cronograma e investimento. A execução é feita em ambiente separado, homologada com a sua equipe, e só então vai para produção. O código das integrações fica com você.

Para contratar, fale com a gente pela página de serviços de Moodle da Agathas Web ou pelo WhatsApp que aparece nela.

Conclusão: OAuth2 no Moodle é o destino, não um interruptor

O OAuth2 no Moodle 5.3 é a melhor notícia de segurança para integrações em anos: tokens de uma hora, segredos com validade, escopos explícitos e revogação imediata. Mas ele vive na nova REST API, que ainda cobre só parte do Moodle. Quem tenta trocar tudo de uma vez descobre que matrícula e notas não têm para onde ir.

O caminho que funciona é inventariar, isolar a autenticação, endurecer o token clássico e migrar função por função conforme a REST API cresce. Se você quer esse plano feito por quem opera Moodle em produção, conheça o serviço de Moodle da Agathas Web e peça um diagnóstico das suas integrações.