OAuth2 / OIDC — conectar um serviço ao Omniscol

O que o Omniscol faz como servidor OAuth2

Um serviço externo — um agente IA, um conector, um painel de controle — torna-se um cliente declarado na sua conta; um usuário da escola aprova o seu acesso por meio de uma tela de consentimento; o serviço recebe então um token de acesso de curta duração, cujo perímetro é limitado aos escopos concedidos e aos direitos do usuário.

Este mecanismo é distinto do SSO de usuário descrito em OIDC / SSO, onde o Omniscol é, ao contrário, cliente do seu provedor de identidade para conectar os seus usuários. Aqui, o Omniscol está do lado servidor: são serviços que se conectam a ele.

Duas integrações Omniscol consomem este servidor:

• MCP — a autenticação padrão de um agente IA passa por este servidor OAuth2 (veja MCP — conectar um agente IA externo);
• OneRoster — o produtor OneRoster autentica-se por um token OAuth2 de máquina a máquina emitido por este mesmo servidor (veja OneRoster).

Qualquer outro serviço conforme a OAuth2 / OIDC pode conectar-se da mesma maneira.

Descoberta e pontos de acesso do protocolo

O Omniscol publica os seus metadados de descoberta nos endereços padrão .well-known, servidos na raiz do domínio da sua conta (por exemplo https://sua-escola.omniscol.com). Um cliente conforme ali encontra sozinho todos os pontos de acesso, sem configuração manual:

• /.well-known/oauth-authorization-server — metadados do servidor de autorização (RFC 8414);
• /.well-known/openid-configuration — metadados OpenID Connect (conteúdo idêntico ao anterior);
• /.well-known/jwks.json — chaves públicas de verificação (JWKS), que permitem verificar a assinatura dos id_token;
• /.well-known/oauth-protected-resource — metadados de recurso protegido (RFC 9728).

Esses metadados anunciam os pontos de acesso do protocolo:

• /oauth/authorize — pedido de autorização (tela de conexão depois de consentimento);
• /oauth/token — troca do código por um token, e renovação;
• /oauth/register — registro dinâmico de clientes (RFC 7591);
• /oidc/userinfo — informações sobre o usuário conectado (OIDC);
• /oauth/revoke — revogação de um token (RFC 7009).

Esses pontos de acesso do protocolo são públicos: eles não são reservados às contas Premium e não precisam ser abertos manualmente. Apenas a tela de gestão dos clientes descrita mais abaixo faz parte do Premium.

Os fluxos de autorização

O Omniscol suporta três fluxos OAuth2:

• Código de autorização com PKCE — o fluxo por padrão para um serviço que age em nome de um usuário. O serviço redireciona o usuário para /oauth/authorize; após conexão e consentimento, o Omniscol devolve um código de autorização (válido por 5 minutos) que o serviço troca em /oauth/token. O método PKCE adotado é o S256, e o único response_type aceito é o code.
• Renovação (refresh_token) — para prolongar um acesso delegado sem repassar pelo consentimento.
• Client credentials — fluxo de máquina a máquina, sem usuário, utilizado em particular pelos consumidores OneRoster. O cliente autentica-se diretamente e recebe um token de acesso.

Na troca, o servidor emite um token de acesso (Bearer, válido por 1 hora) e, para os fluxos de usuário, um token de renovação (válido por 30 dias). Quando o escopo openid é solicitado, um id_token OIDC assinado é também emitido; a sua assinatura verifica-se via /.well-known/jwks.json. O fluxo client_credentials só emite um token de acesso, sem renovação nem id_token.

O token de acesso apresenta-se em seguida no cabeçalho HTTP Authorization: Bearer <token>. A cada chamada, o Omniscol verifica a sua assinatura, controla que o cliente continua ativo, que o usuário ainda existe e possui o papel exigido, e que os escopos do token cobrem bem o ponto de acesso chamado — sem o que a chamada é recusada.

Os escopos e o consentimento

Os escopos que você gerencia num cliente são:

• read:basic — leitura dos horários, painéis de controle e consultas (módulos Página inicial, Horário, Painel, Gestão de horários letivos);
• read:user — leitura da lista dos usuários;
• write:data — escrita nesses mesmos módulos de consulta;
• admin — acesso de administração (módulos Administração, Gestão de ausências, Gestão de horários letivos).

O servidor conhece também os escopos OIDC (openid, email, profile) e os escopos OneRoster em leitura apenas (prefixo imsglobal.org). Esses últimos são privilegiados: um cliente não pode autoatribuí-los pelo registro dinâmico; eles devem ser provisionados por um administrador na ficha do cliente.

O escopo efetivamente concedido é a interseção daquilo que o cliente solicita e daquilo que lhe está registrado: um cliente nunca obtém mais do que o que consta na sua ficha. Durante o fluxo de usuário, a tela de consentimento (/oauth/consent) exibe o nome e o logotipo do serviço solicitante bem como a lista legível dos escopos solicitados, com os botões Aceitar e Recusar. Aprovar emite o código de autorização e devolve o usuário ao serviço; recusar o devolve com um erro access_denied.

O registro dinâmico de clientes

O ponto de acesso /oauth/register implementa o registro dinâmico (Dynamic Client Registration, RFC 7591): um serviço conforme pode declarar-se sozinho como cliente, sem intervenção manual prévia. É isso que permite a um agente MCP configurar-se a partir apenas da URL do servidor.

O registro dinâmico não pode atribuir-se escopo privilegiado (os escopos OneRoster): esses são silenciosamente descartados, e se nenhum escopo válido subsistir, o read:basic é concedido por padrão. Os escopos privilegiados permanecem reservados a um provisionamento por um administrador.

A tela de gestão dos clientes OAuth2

Nas contas Premium, você administra os clientes a partir de Administração → Importação / Exportação, seção OAuth2, com o botão OAuth2. O acesso exige primeiro a senha de administrador — uma confirmação suplementar antes de abrir a tela.

A tela lista os clientes registrados e, para cada um, exibe o seu estado (ativo / inativo), o seu nome, os seus escopos, os seus contatos e as suas URIs (site, logotipo, URIs de redirecionamento). Você pode:

• Registrar um cliente — informe o nome, um software_id facultativo, os escopos, os contatos, o site, o logotipo e as URIs de redirecionamento. Na criação, o Omniscol exibe uma única vez o client_id e o client_secret.
• Modificar um cliente — apenas campos seguros são modificáveis: nome, escopos, contatos, site e logotipo. As URIs de redirecionamento, o software_id e o segredo não se modificam aqui.
• Ativar ou desativar um cliente — um cliente desativado vê os seus tokens recusados já na chamada seguinte.
• Excluir um cliente — a exclusão é definitiva.

O segredo do cliente

O client_secret é exibido uma única vez, no registro. O Omniscol conserva ao seu lado apenas uma impressão do segredo, nunca o segredo em claro: ele não pode ser reexibido nem recuperado depois. Copie-o imediatamente para um gerenciador de segredos.

O client_id, por sua vez, é determinístico: ele deriva do nome da conta, do nome do cliente e de uma impressão dos seus metadados técnicos. Dois registros estritamente idênticos recaem assim sobre o mesmo identificador.

Renovar o segredo (rotação)

A rotação do segredo existe: ela emite um novo segredo, conserva apenas a nova impressão, e só devolve esse novo segredo uma vez. Ela efetua-se via o ponto de acesso de gestão do registro dinâmico (/oauth/register/<client_id>/rotation) e supõe apresentar o token de registro entregue ao cliente no seu registro dinâmico. Ela não é, portanto, acionada a partir da tela de gestão acima, que não manipula esse token.

OAuth2 ou chave de API: qual escolher

O Omniscol propõe dois mecanismos de acesso de máquina, com modelos de confiança diferentes:

• OAuth2 (esta página) — um terceiro registrado obtém, após consentimento de um usuário, um token de curta duração (1 h), limitado aos escopos concedidos, renovável e revogável (ao desativar o cliente). O fluxo client_credentials cobre além disso a máquina a máquina sem usuário. É o modo adaptado a um serviço terceiro identificado, ao MCP e ao OneRoster.
• Chave de API (veja API Omniscol) — um token autônomo assinado pelo servidor, que embarca uma lista de pontos de acesso autorizados e que você mesmo entrega ao sistema externo: sem terceiro registrado, sem tela de consentimento, sem renovação. É uma delegação, pelo administrador, dos seus próprios direitos a um sistema que ele domina.

Em resumo: a chave de API convém quando você mesmo entrega um acesso a um sistema que você controla; o OAuth2 convém quando um serviço terceiro identificado deve obter um acesso delegado, com escopo e revogável, ou quando o protocolo o impõe (MCP, OneRoster).