Sincronização de arquivos Word via OneDrive
Objetivo
Permitir que o Moodle baixe automaticamente os arquivos Word cadastrados em cada disciplina, via URL do OneDrive ou por sincronização de pastas no OneDrive.
O objetivo é facilitar o fluxo de atualização dos conteúdos, permitindo que o time de conteúdo continue trabalhando diretamente no Word, como já faz hoje, e que os arquivos possam ser processados manualmente no Moodle quando necessário.
Como funciona
- Ao criar o registro da Disciplina, basta cadastrar a URL do arquivo Word no OneDrive.
- Quando for necessário atualizar o conteúdo, basta executar manualmente o processamento no Moodle.
- Também é possível configurar a leitura automática de arquivos dentro de uma pasta do OneDrive (com suporte opcional a subpastas), para gerar automaticamente os registros “Disciplina → Word” por sincronização.
- Em todos os casos, a execução final do processamento no Moodle deve permanecer manual, para melhor controle do responsável pelo conteúdo.
Formas de integração com o OneDrive
Existem duas opções de autenticação para acessar os arquivos via API do Microsoft Graph (cada uma requer um aplicativo diferente criado no Portal Azure).
| Tipo de Integração | Modo Corporativo (Client / API) | Modo Pessoal (OAuth2) |
|---|---|---|
| Descrição | Usa autenticação de aplicativo (App-only / Client Credentials Flow). | Usa autenticação de usuário (OAuth2 Authorization Code Flow). |
| Tipo de conta | Microsoft 365 / SharePoint / OneDrive corporativo | OneDrive pessoal (conta Microsoft comum) |
| Login manual | Não necessário | Apenas na primeira vez |
| Renovação de token | Automática no servidor | Automática via refresh token (dura cerca de 90 dias) |
| Permissões | Files.Read.All (Application) |
Files.Read, offline_access, User.Read (Delegated) |
| Escopo de acesso | Arquivos do tenant corporativo | Arquivos do usuário logado |
| Criação do App | Criado no Portal Azure da EVT (ou tenant corporativo) | Criado no Portal Azure logado com conta pessoal Microsoft |
| Dependência de usuário real | Não | Sim |
| Ideal para | Ambientes corporativos, automações servidoras | Contas pessoais, testes e conteúdo individual |
Configuração resumida
# Configurações comuns
MS_GRAPH_API_BASE_URL=https://graph.microsoft.com/v1.0
# Modo corporativo (Client / API)
MS_GRAPH_CLIENT_ID=<id-do-app-corporativo>
MS_GRAPH_CLIENT_SECRET=<segredo-do-app>
MS_GRAPH_TENANT_ID=<tenant-id>
MS_GRAPH_SCOPE=https://graph.microsoft.com/.default
MS_GRAPH_TOKEN_URL=https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token
# Modo pessoal (OAuth2)
MS_GRAPH_OAUTH2_CLIENT_ID=<id-do-app-pessoal>
MS_GRAPH_OAUTH2_CLIENT_SECRET=<segredo-do-app-pessoal>
MS_GRAPH_REDIRECT_URI=http://localhost:5000/callbackCriação dos aplicativos no Portal Azure
A integração requer dois aplicativos distintos, um para cada modo de operação.
1. Modo Corporativo – Client / API (Microsoft 365 / SharePoint)
Objetivo: permitir acesso direto do Moodle a arquivos corporativos sem intervenção de usuário.
Passo a passo:
-
Acesse o Portal Azure com uma conta corporativa (ex.: EVT ou HÉLICO): https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps
-
Clique em Nova Registração.
-
Configure:
- Nome:
OfficeReaderAPI - Tipos de conta com suporte: apenas Contas neste diretório organizacional (single tenant)
- URI de redirecionamento: (não necessário para este modo)
- Nome:
-
Após criar:
- Copie o Application (client) ID
- Copie o Directory (tenant) ID
-
Em Certificados e segredos, envie o certificado (recomendado; veja Credenciais do Moodle no Microsoft Graph) ou, no modo legado, gere um Client Secret.
-
Em Permissões de API → Microsoft Graph → Application permissions, adicione:
Files.Read.All- (opcional)
Sites.Read.All
-
Clique em Conceder consentimento do administrador.
-
Atualize as variáveis de ambiente conforme o exemplo acima.
Resultado esperado: O Moodle poderá autenticar-se automaticamente usando o Client ID e o certificado (ou o Client Secret), acessando arquivos do SharePoint/OneDrive corporativo sem necessidade de login manual.
2. Modo Pessoal – OAuth2 (OneDrive pessoal)
Objetivo: permitir que o usuário logue manualmente com sua conta Microsoft e autorize o acesso.
Passo a passo:
-
Acesse o Portal Azure com uma conta pessoal Microsoft (
@outlook.com,@hotmail.com, etc.) ou via https://apps.dev.microsoft.com -
Crie um novo app:
- Nome:
OfficeReaderPersonal - Tipos de conta com suporte: Contas em qualquer diretório organizacional e contas pessoais da Microsoft
- Redirect URI:
http://localhost:5000/callback
- Nome:
-
Gere um Client Secret.
-
Em Permissões de API → Microsoft Graph → Delegated permissions, adicione:
Files.ReadUser.Readoffline_access
-
Salve e copie:
- Application (client) ID
- Client Secret
-
Atualize as variáveis de ambiente conforme o exemplo acima.
Resultado esperado:
O sistema abrirá o navegador na primeira execução. Após o login e autorização do usuário, o token será salvo em
token.json e usado automaticamente nas execuções futuras.
Autorização e código de retorno (redirect_uri)
Durante o primeiro login no modo OAuth2 (OneDrive pessoal), o aplicativo abre o navegador para o usuário autorizar o acesso à conta Microsoft.
Após a autorização, o usuário é redirecionado para a URL definida em:
MS_GRAPH_REDIRECT_URI=http://localhost:5000/callbackO retorno inclui um parâmetro code na própria URL, contendo o código de autorização temporário usado para
completar a autenticação.
Exemplo de retorno:
http://localhost:5000/callback?code=0.AAAAaExampleAuthCode123456789Esse code é utilizado pelo script para solicitar o access token e o refresh token, concluindo a autenticação
inicial com a Microsoft Graph API.
Esse código de autorização é válido apenas por alguns minutos e pode ser usado uma única vez. Após trocá-lo pelos tokens, o sistema salva os dados em
token.jsone não será necessário repetir o login enquanto orefresh_tokenestiver válido.
Credenciais do Moodle no Microsoft Graph
O plugin (microsoft_graph_service) acessa o SharePoint em modo App-only (Client Credentials Flow) e aceita dois
modos de autenticação do aplicativo Entra. O modo é escolhido a cada criação do cliente Graph, a partir das
configurações do plugin:
| Configuração preenchida | Modo usado | Observação |
|---|---|---|
| Certificado e chave privada | Certificado | Recomendado. Obrigatório para o app do tenant HÉLICO (sem secret). |
| Apenas Client Secret | Secret (legado) | Comportamento anterior, sem mudança. |
| Certificado + chave privada e Client Secret | Certificado | Emite aviso (debugging, sem valores) para remover o secret. |
| Nenhum dos dois (ou só um entre certificado/chave) | — | Erro ms_graph_auth_not_configured, sem expor valores. |
Configurações do plugin
Em Administração do site → HÉLICO → Microsoft Graph:
Configuração (local_helico/…) |
Conteúdo | Exibição no painel |
|---|---|---|
ms_graph_tenant_id |
Directory (tenant) ID | Texto |
ms_graph_client_id |
Application (client) ID | Texto |
ms_graph_sharepoint_site_id |
ID do site SharePoint | Texto |
ms_graph_certificate |
Certificado X.509 público, PEM (-----BEGIN CERTIFICATE-----) |
Texto (é público) |
ms_graph_private_key |
Chave privada PEM, de preferência PKCS#8 | Nunca exibida; campo vazio mantém a atual |
ms_graph_private_key_passphrase |
Senha da chave (opcional; só para chave criptografada) | Campo de senha |
ms_graph_client_secret |
Client Secret (modo legado) | Texto |
Quando os valores são forçados pelo config.php (caso da produção), os campos ficam somente leitura e a chave privada e
a senha continuam sem ser exibidas. Para apagar a chave privada salva pelo painel, use a CLI:
php admin/cli/cfg.php --component=local_helico --name=ms_graph_private_key --unset.
Variáveis de ambiente (deploy)
Em produção, o repositório docker-moodle-helico (src/MoodleDocker/ConfigExtras.php) força estas configurações a
partir de variáveis de ambiente:
| Variável de ambiente | Configuração do plugin | Modo |
|---|---|---|
HELICO_MSGRAPH_TENANT_ID |
ms_graph_tenant_id |
ambos |
HELICO_MSGRAPH_CLIENT_ID |
ms_graph_client_id |
ambos |
HELICO_MSGRAPH_SHAREPOINT_SITE_ID |
ms_graph_sharepoint_site_id |
ambos |
HELICO_MSGRAPH_CERTIFICATE |
ms_graph_certificate |
certificado |
HELICO_MSGRAPH_PRIVATE_KEY |
ms_graph_private_key |
certificado |
HELICO_MSGRAPH_PRIVATE_KEY_PASSPHRASE |
ms_graph_private_key_passphrase |
certificado, opcional |
HELICO_MSGRAPH_CLIENT_SECRET |
ms_graph_client_secret |
secret (legado) |
Os PEMs podem chegar com quebras de linha reais, com CRLF ou com \n literal (valor achatado em uma linha); o plugin
normaliza os três formatos.
Arquivos do certificado no moodledata
O SDK do Microsoft Graph só aceita caminhos de arquivo para o certificado e a chave. Por isso o plugin grava os PEMs
em $CFG->dataroot/local_helico/msgraph/ (certificate.pem e private_key.pem):
- o caminho é montado em tempo de execução; nenhum caminho absoluto é salvo na configuração;
- os arquivos têm permissão
0600e são gravados de forma atômica (arquivo temporário +rename); - a configuração é a fonte de verdade: o arquivo só é regravado quando não existe ou quando o hash do conteúdo difere da
configuração. Isso cobre migração de servidor, restauração de backup, renovação do certificado e vários nós web com
moodledatacompartilhado. Apagar a pasta é seguro: ela é recriada no próximo uso; - nada é gravado em
dirroot, em cache purgável (localcachedir/MUC) ou em log.
Como os arquivos ficam com 0600, o cron e o servidor web devem rodar com o mesmo usuário do sistema (requisito padrão
do Moodle para o moodledata).
Verificação de conexão (CLI)
Para validar a configuração sem esperar a sincronização, rode no servidor do Moodle, com o mesmo usuário do servidor web
(por causa dos arquivos 0600):
php local/helico/cli/msgraph_check.php # lista até 5 itens da raiz
php local/helico/cli/msgraph_check.php --limit=10A CLI usa o mesmo caminho do plugin (escolha do modo, gravação dos PEMs no moodledata, contexto de token e cliente
Graph) e é somente leitura: lista as bibliotecas do site e os primeiros itens da raiz da biblioteca padrão; nada é
gravado no SharePoint. Ela mostra:
- o modo em uso (
certificateousecret) e o aviso quando os dois estão configurados; - tenant ID e client ID mascarados (8 primeiros caracteres +
…) e o ID do site; - no modo certificado: thumbprint SHA-1 (o mesmo exibido no Entra em Certificados e segredos e registrado no cofre
em
certificate_thumbprint), CN do certificado, data de expiração e dias restantes; - o caminho de
certificate.pemeprivate_key.pem, a permissão atual (esperado0600) e se foram recriados agora.
Nunca imprime secret, token, PEM ou passphrase. Em caso de falha, mostra só códigos:
| Código de saída | Significado | Exemplo de mensagem |
|---|---|---|
0 |
Conexão OK | OK: conexão com o Microsoft Graph funcionando (modo …) |
1 |
Configuração ausente ou inválida | FALHA: ms_graph_auth_not_configured — … |
2 |
Falha ao obter o token | FALHA: token request, error invalid_client AADSTS7000222 |
2 |
Falha na chamada ao Graph | FALHA: Graph HTTP 403, code accessDenied |
Os códigos AADSTS… são do Entra (ex.: AADSTS7000222 = client secret expirado; AADSTS700027 = certificado não
cadastrado no app). accessDenied indica que o app não tem permissão no site.
Renovação do certificado
O Entra aceita mais de um certificado por aplicativo, o que permite trocar sem indisponibilidade:
- Gere o novo par (certificado + chave) e envie o novo certificado ao app em Certificados e segredos, mantendo o antigo.
- Atualize o certificado e a chave no cofre (1Password
MSGRAPH-HELICO27) e faça o deploy; o plugin regrava os arquivos nomoodledataao detectar o novo hash. - Valide com
php local/helico/cli/msgraph_check.php(o thumbprint exibido deve ser o do novo certificado). - Remova o certificado antigo do app no Entra.
A validade do certificado em uso fica registrada no cofre (MSGRAPH-HELICO27/certificate_expires).
Referência técnica (exemplos em Python)
Os arquivos de exemplo estão disponíveis em:
docs/plataforma/api-integracoes/exemplos-python/
├── word_api.py
└── word_oauth.py| Arquivo | Descrição |
|---|---|
word_api.py |
Exemplo de autenticação via Client Credentials (OneDrive corporativo). Demonstra como obter o access_token diretamente e baixar arquivos via Graph API. |
word_oauth.py |
Exemplo de autenticação via OAuth2 Authorization Code Flow (OneDrive pessoal). Simula o login do usuário, armazenamento de token.json e renovação automática do token. |
Esses arquivos podem ser utilizados para:
- Testar a autenticação e o acesso a arquivos do OneDrive via Microsoft Graph;
- Validar o funcionamento das permissões e tokens antes da integração final no Moodle;
- Servir como referência técnica para a implementação em PHP dentro do plugin Moodle.
A aplicação real (Moodle / PHP) não utiliza esses arquivos Python. Eles são apenas exemplos e provas de conceito para referência técnica.
Como o ambiente final é em PHP, as credenciais podem ser configuradas diretamente via painel administrativo do Moodle,
sem necessidade de arquivo .env.
Nome dos arquivos Word
Os arquivos Word devem seguir o padrão de nomenclatura:
[IDNUMBER_123] Nome da Disciplina.docx-
IDNUMBER_123é o identificador único da subcategoria da categoriaDISCIPLINASno Moodle. -
Nome da Disciplinaé o nome visível do conteúdo. -
Em caso de grandes modificações, use uma nova versão, por exemplo:
[IDNUMBER_123_V2] Nome da Disciplina.docxAssim, o sistema entenderá como uma nova sincronização de conteúdo.
Fluxo resumido de sincronização
- O app obtém o token de acesso do Microsoft Graph (conforme o modo configurado).
- O Moodle lê a URL informada da disciplina ou da pasta raiz no OneDrive.
- O sistema baixa o arquivo
.docxe o armazena localmente. - O plugin do Moodle (
local/helico) processa o conteúdo do Word (via módulomod_unidade). - O usuário responsável executa manualmente o processamento da disciplina no Moodle.
- A sincronização pode ocorrer:
- Manualmente (via botão “Sincronizar Word”); ou
- Automaticamente (via tarefa cron agendada).
Confirmações necessárias
- Confirmar se a integração usará SharePoint / OneDrive corporativo (modo Client) ou OneDrive pessoal (modo OAuth2).
- Confirmar se o time de conteúdo continuará trabalhando diretamente no Word, como já vem fazendo.
- Caso seja o modo corporativo, criar o App no Portal Azure da EVT (até que a HÉLICO possua conta Microsoft própria).
Observação: O processamento do arquivo Word no Moodle deve continuar sendo executado manualmente, garantindo que o responsável pelo conteúdo revise e confirme as atualizações antes da publicação.