Skip to content

Sincronização de arquivos Word via OneDrive

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/callback

Criaçã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:

  1. Acesse o Portal Azure com uma conta corporativa (ex.: EVT ou HÉLICO): https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps

  2. Clique em Nova Registração.

  3. 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)
  4. Após criar:

    • Copie o Application (client) ID
    • Copie o Directory (tenant) ID
  5. Em Certificados e segredos, envie o certificado (recomendado; veja Credenciais do Moodle no Microsoft Graph) ou, no modo legado, gere um Client Secret.

  6. Em Permissões de API → Microsoft Graph → Application permissions, adicione:

    • Files.Read.All
    • (opcional) Sites.Read.All
  7. Clique em Conceder consentimento do administrador.

  8. 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:

  1. Acesse o Portal Azure com uma conta pessoal Microsoft (@outlook.com, @hotmail.com, etc.) ou via https://apps.dev.microsoft.com

  2. 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
  3. Gere um Client Secret.

  4. Em Permissões de API → Microsoft Graph → Delegated permissions, adicione:

    • Files.Read
    • User.Read
    • offline_access
  5. Salve e copie:

    • Application (client) ID
    • Client Secret
  6. 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/callback

O 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.AAAAaExampleAuthCode123456789

Esse 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.json e não será necessário repetir o login enquanto o refresh_token estiver 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 0600 e 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 moodledata compartilhado. 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=10

A 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 (certificate ou secret) 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.pem e private_key.pem, a permissão atual (esperado 0600) 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:

  1. Gere o novo par (certificado + chave) e envie o novo certificado ao app em Certificados e segredos, mantendo o antigo.
  2. Atualize o certificado e a chave no cofre (1Password MSGRAPH-HELICO27) e faça o deploy; o plugin regrava os arquivos no moodledata ao detectar o novo hash.
  3. Valide com php local/helico/cli/msgraph_check.php (o thumbprint exibido deve ser o do novo certificado).
  4. 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 categoria DISCIPLINAS no 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.docx

    Assim, o sistema entenderá como uma nova sincronização de conteúdo.


Fluxo resumido de sincronização

  1. O app obtém o token de acesso do Microsoft Graph (conforme o modo configurado).
  2. O Moodle lê a URL informada da disciplina ou da pasta raiz no OneDrive.
  3. O sistema baixa o arquivo .docx e o armazena localmente.
  4. O plugin do Moodle (local/helico) processa o conteúdo do Word (via módulo mod_unidade).
  5. O usuário responsável executa manualmente o processamento da disciplina no Moodle.
  6. 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.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close