Skip to content

Autenticação

Autenticação

Status: EM REVISÃO (2026-05-04)

Contratos consolidados a partir de UC-001 — Login e Obtenção de Token. Login social via MIDDAG documentado em modo doc-first: o contrato abaixo descreve a resposta esperada; a entrega do wstoken no payload do MIDDAG está em implementação (B-pend-1).

Termos: API REST HÉLICO, Método de Login, Permissão, Perfil do Sistema.

Visão geral

+------------------+
| Frontend NextJS  |
+--------+---------+
         | tipo de login?
   +-----+-----+
   |           |
   v           v
email+senha   social/SSO (Google, ...)
   |           |
   v           v
+----------------------------------+   +-------------------------------------+
| Cenário 1: Moodle nativo         |   | Cenário 2: MIDDAG (social/SSO)      |
| POST /login/token.php            |   | POST /local/middag/api/auth/login   |
|   ?service=moodle_mobile_app         |   |   JSON {provider, code|idtoken} |
|   form: username, password       |   |                                     |
+--------+-------------------------+   +-----------+-------------------------+
         |                                         |
         v                                         v
   200 { token, privatetoken }     200 { token, user{id, fullname, email, ...} }
         |                                         |
         +-----------------+-----------------------+
                           v
              +------------------------------+
              | Authorization: Bearer <token>|
              | OR query: ?wstoken=<token>   |
              +--------------+---------------+
                             v
              +-------------------------------+
              | /local/helico/ajax.php/       |
              |   api/v1/platform/*           |
              |   /local/middag/api/*         |
              +-------------------------------+

A Plataforma HÉLICO suporta dois Métodos de Login complementares: o nativo do Moodle (credenciais do usuário) e o do MIDDAG (provedores externos via SSO). Ambos resultam num wstoken que carrega a sessão para chamadas subsequentes.

Cenário 1 — Login Email/Senha (Moodle nativo)

Usar quando o cliente coleta credenciais diretamente. Padrão para web app HÉLICO, mobile e qualquer integração que controle username + password.

Request

POST /login/token.php
Content-Type: application/x-www-form-urlencoded
Campo Tipo Obrigatório Valor
username string Sim Email ou username Moodle do usuário
password string Sim Senha em texto puro (TLS obrigatório)
service string Sim moodle_mobile_app

Response 200

{
  "token": "abc123def456...",
  "privatetoken": "xyz789..."
}
Campo Tipo Descrição
token string wstoken para usar em chamadas subsequentes da API REST HÉLICO
privatetoken string Token de sessão privado Moodle (uso interno; Frontend pode ignorar)

Não retorna informações do usuário. Para obter dados do usuário, chamar GET /api/v1/platform/me em seguida (ver me.md).

Response 4xx

HTTP Código errorcode Causa Ação Frontend
200 invalidlogin Credenciais erradas Mostrar erro, permitir retry
200 usernotconfirmed Email não confirmado Pedir confirmação por email
200 userdeleted Usuário removido Mostrar suporte
200 usersuspended Conta suspensa Mostrar suporte
403 webservicesdisabled Web services desativado no Moodle Erro infra (ops)
403 webserviceusernotenabled Service moodle_mobile_app não habilitado Erro infra (ops)
429 ratelimited Muitas tentativas de login Backoff exponencial

Erros 200 com errorcode

O Moodle retorna HTTP 200 mesmo em falhas de autenticação. O cliente DEVE inspecionar a presença de errorcode no payload — se presente, a requisição falhou independentemente do status HTTP.

Exemplo cURL

curl -X POST 'https://helico.com.br/login/token.php' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'username=aluno@exemplo.com&password=Senha%40123&service=moodle_mobile_app'

Cenário 2 — Login Social (MIDDAG)

Usar para SSO (Google, Microsoft, …). Frontend não coleta credenciais; usa fluxo OAuth2 do provedor e troca o code ou idtoken por um wstoken HÉLICO via MIDDAG.

Doc-first (CQ3)

Este contrato descreve a resposta esperada do MIDDAG. A inclusão do token no payload é a entrega de B-pend-1 (em desenvolvimento). Até sua conclusão, o Frontend pode precisar combinar o callback OAuth com uma chamada subsequente a POST /login/token.php ou similar — o contrato vigente substituirá esse workaround tão logo a implementação suba.

Request

POST /local/middag/api/auth/login
Content-Type: application/json
{
  "provider": "google",
  "code": "4/0AdQt8q...",
  "redirect_uri": "https://helico.com.br/auth/callback"
}
Campo Tipo Obrigatório Descrição
provider string Sim Identificador do provedor SSO (google, microsoft, …)
code string Condicional Authorization code OAuth2 (fluxo code flow). Mutex com idtoken.
idtoken string Condicional ID Token JWT (fluxo implicit/PKCE). Mutex com code.
redirect_uri string Sim em code URI registrada no provedor; necessária para validação

Response 200

{
  "token": "abc123def456...",
  "user": {
    "id": 42,
    "fullname": "Maria Silva",
    "email": "maria@exemplo.com",
    "avatar_url": "https://helico.com.br/avatar/42.jpg"
  }
}
Campo Tipo Descrição
token string wstoken HÉLICO (idêntico ao do Cenário 1)
user.id integer ID Moodle do usuário
user.fullname string Nome completo
user.email string Email primário
user.avatar_url string URL absoluta do avatar do usuário

Diferente do Cenário 1, o MIDDAG retorna user info na resposta — Frontend pode pular a chamada a /api/v1/platform/me no fluxo pós-login.

Response 4xx

HTTP error Causa
400 invalid_provider provider desconhecido
400 missing_credential Nem code nem idtoken informados
401 provider_token_invalid code/idtoken rejeitado pelo provedor SSO
403 email_not_authorized Email do provedor não tem usuário Moodle
429 ratelimited Muitas tentativas

Exemplo cURL

curl -X POST 'https://helico.com.br/local/middag/api/auth/login' \
  -H 'Content-Type: application/json' \
  -d '{
    "provider": "google",
    "code": "4/0AdQt8q...",
    "redirect_uri": "https://helico.com.br/auth/callback"
  }'

Uso do wstoken nas requisições

Após obter o wstoken, o cliente envia em todas as chamadas a /api/v1/platform/* e /local/middag/api/*. As duas formas são equivalentes do ponto de vista do backend; o cliente escolhe baseado em contexto.

Forma 1 — Header Authorization: Bearer

GET /local/helico/ajax.php/api/v1/platform/me
Authorization: Bearer abc123def456...

Padrão recomendado para chamadas XHR/fetch do Frontend. Não vaza em logs de servidor, histórico de browser, header Referer.

Forma 2 — Query parameter ?wstoken=

GET /local/helico/ajax.php/api/v1/platform/me?wstoken=abc123def456...

Útil quando o cliente não pode controlar headers — download direto via <a href>, iframe legado, EventSource sem proxy, link compartilhado.

Tradeoffs de segurança

Token em query string aparece em access logs do servidor, no histórico do browser e potencialmente no header Referer de navegação subsequente. Usar somente quando a Forma 1 for inviável e o canal estiver protegido por TLS.

Polling assíncrono pós-onboarding {#polling}

Após o cliente submeter o Onboarding (último step), o Plano do Aluno é criado em background. A resposta de POST /api/v1/platform/onboarding/{enrolment_id}/submit retorna student_plan = { id: null, status: "creating" }. O Frontend polleia GET /api/v1/platform/enrolments até student_plan.id aparecer.

Contrato de polling (P1)

Regra Valor
Intervalo inicial 2 segundos
Backoff Exponencial (×1.5), até teto de 30 segundos
Tentativas máximas 60 (~5–10 min totais)
Servidor: rate limit por usuário 30 req/min em /api/v1/platform/enrolments

Estados possíveis de student_plan:

status id Significado Próxima ação Frontend
creating null Handler async em execução Continuar polling
active integer Plano criado com sucesso Redirecionar para Roteiro
failed null Handler async falhou (T3) Mostrar erro + botão “Tentar de novo”

Quando status="failed", o response inclui error_message: string com uma mensagem segura para o usuário. O retry re-emite o onboarding_completed_signal sem reapresentar o questionário.

Erros gerais (qualquer endpoint autenticado)

HTTP error Significado
401 unauthorized wstoken ausente, inválido ou expirado
403 forbidden Token válido mas sem permissão
404 not_found Recurso não existe ou não pertence ao user
409 (depende do recurso) Conflito de estado
422 validation_error Payload inválido. Ver errors[] no body
429 ratelimited Limite de chamadas excedido
500 internal_error Falha não esperada

Fluxo end-to-end

+------------------+
| 1. Login         |  -> wstoken
+--------+---------+
         |
         v
+----------------------------+
| 2. GET /me  (se Cenário 1) |  -> dados do usuário
+----------------------------+
         |
         v
+--------------------------------+
| 3. GET /enrolments?status=...  |
+--------------------------------+
         |
   +-----+-----+--------------+--------------------+
   |           |              |                    |
   v           v              v                    v
sem inscrição  onboarding     onboarding completo  student_plan.status=failed
(catálogo)     pendente       (Área do Aluno)      (mostrar retry)
                |
                v
           +----+----+
           | 4. GET  |  -> steps do questionário
           | /onboar |
           | ding/.. |
           +----+----+
                |
                v
           +----+----+
           | 5. POST |  -> {phase_completed, student_plan: {id:null, status:"creating"}}
           | /submit |
           +----+----+
                |
                v (polling P1)
           +----+----+
           | 6. GET  |  -> aguarda student_plan.id
           | /enrol  |
           | ments   |
           +---------+
                |
                v (id aparecer)
           Área do Aluno (Roteiro)

Pendências externas

ID Descrição Status
B-pend-1 MIDDAG /local/middag/api/auth/login retornar wstoken no payload Em desenvolvimento
B-pend-2 Async student_plan creation: dead letter / retry / alerta operacional Backlog
TODO-1 Documentar precedência quando Bearer + ?wstoken= chegam simultâneos Backlog (edge case)

Referências

Navigation

Type to search…

↑↓ navigate↵ selectEsc close