Uma fonte única para dados do Orquestrador

Documento estratégico que estabelece a filosofia de governança de dados do Orquestrador e cria um entendimento comum sobre como os dados devem ser tratados. Os Contratos de Dados (ver Registro de Contratos) são quem a implementa, um por interface. É quem norteia a conformidade das interações que acontecem em todo o sistema, sendo responsável pelos dados, como eles devem ser compartilhados, como se garante privacidade e segurança, como se trata interoperabilidade e como se promove IA responsável.

Conteúdo típico de um Manifesto de Dados

• Princípios de governança e papéis/responsabilidades.
• Classificação dos dados, expressa campo a campo via a coluna PII de cada Contrato de Dados.
• Regras de segurança, regras de LGPD e política de versionamento.
• Política de qualidade, interoperabilidade e metadados.

Segurança e credenciais

• TLS 1.2 ou superior em todo o tráfego; criptografia em repouso para dados pessoais.
• Credenciais de integração distintas por ambiente, armazenadas em cofre de segredos, nunca em código-fonte, logs ou URLs; rotação suportada sem janela de indisponibilidade.

LGPD

• Uso exclusivo para as finalidades do contrato; compartilhamento com terceiros é proibido sem aditivo formal.
• Campos sensíveis definidos em contrato devem ser mascarados em qualquer log (aplicação, requisição, integração, traces de erro).
• Direitos do titular: eliminação/anonimização de dados pessoais sob solicitação, em até 15 dias, preservando registros exigidos por lei.
• Incidentes de segurança ou privacidade devem ser notificados em até 24h pelo canal de incidentes, com relatório de impacto.

Política de mudanças (versionamento)

• Mudanças breaking (remover/renomear campo, mudar tipo, tornar obrigatório, alterar semântica) exigem aviso prévio de no mínimo 30 dias e geram nova versão MAJOR do contrato.
• Mudanças não-breaking (campo opcional novo) exigem aviso de 7 dias e geram versão MINOR. Nenhuma mudança de schema entra em produção sem atualização do contrato correspondente.

SLAs padrão (herdados por todos os Contratos de Dados, salvo desvio declarado)

Um nome por conceito, sem sinônimos, vale para os módulos do Orquestrador.

O Contrato de Dados é operacional: especifica exatamente como um conjunto de dados deve se comportar, um acordo entre quem produz o dado e quem o consome. Ele responde a perguntas como qual o schema, quais campos existem, qual o tipo de cada campo, quais são obrigatórios, qual a frequência de atualização, qual SLA, quem é o owner, como mudanças serão feitas e quais regras de qualidade precisam ser atendidas. As entidades abaixo são, cada uma, um Contrato de Dados nesse sentido.

Definição conforme o Template de Governança de Dados (Manifesto · Contrato · Linhagem) — o Manifesto de Dados (ver Governança Federada) estabelece a política; o Contrato a implementa.

Consiste em uma aplicação para o gerenciamento de identidades no processo de autenticação e autorização de sessões dos usuários no Hub de Integrações. Permite que usuários acessem os aplicativos do ecossistema educacional SESI com um único login, usando o Azure Active Directory como provedor de identidade (IDP), que autentica a sessão do usuário e em seguida autoriza o acesso a múltiplos aplicativos confiáveis, sem necessidade de login adicional. O método de autenticação é moderno: SSO baseado em OAuth/OpenID Connect.

Mecanismos

• SSO (Single Sign-On)
• Controle de sessões
• Controle de tokens
• Coleta de logs para monitoramento
• Autorização
• Autenticação
• Administração de usuários
• Interface para integração
• Single Logout
• Gestão Multi Tenant
• Recuperação de senha

Além do provisionamento automático via integração (ver módulo Integrações), o Hub de Integrações oferece dois caminhos administrativos para cadastrar usuários diretamente:

• Cadastro manual — preenchimento linha a linha em uma tabela na própria interface.
• Upload em lote via CSV — a partir de um template disponibilizado para download, com link direto para a documentação da API.

Taxonomia de status de cadastro

Este documento define o contrato técnico e os requisitos de segurança para o acesso autenticado entre a plataforma Orquestrador/Hub da Big Brain e plataformas de EdTechs, sem que o usuário precise informar novamente suas credenciais.

O contrato é bidirecional e deve atender aos dois cenários:

Responsabilidades por direção:

Em ambos os casos, a plataforma de destino deve:

1. autenticar a aplicação de origem e emitir um token de acesso de curta duração;
2. validar o token e o identificador do usuário;
3. criar uma autorização de uso único; e
4. devolver uma URL temporária que estabeleça a sessão do usuário na plataforma de destino.

O fluxo definido neste documento é um SSO por integração de API e URL de acesso único. Ele utiliza conceitos e formatos consolidados de autenticação HTTP e OAuth 2.0.

As chamadas aos endpoints são server-to-server. API key, Basic Auth e Bearer Token não devem ser expostos ao navegador, ao código JavaScript do cliente ou a aplicações móveis sem backend confiável.

Para que o serviço de integração da EdTech parceira se conecte com a plataforma Orquestrador e seja disponibilizada no módulo Hub para os respectivos usuários, a sincronização das identidades deverá ocorrer, seja inserido da plataforma Orquestrador para a EdTech (configurado através do módulo de integração) ou consumido da Edtech para a plataforma Orquestrador através do barramento de dados.

Cada provedor deve informar uma URL base por ambiente durante o onboarding.

Rotas canônicas propostas:

Transporte e conteúdo

• Todas as requisições devem utilizar HTTPS, com TLS 1.2 ou superior; recomenda-se TLS 1.3.
• Requisições HTTP devem ser redirecionadas para HTTPS somente em páginas públicas. Os endpoints de autenticação não devem aceitar credenciais por HTTP nem depender de redirecionamento para protegê-las.
• Corpos de requisição e resposta devem utilizar UTF-8.
• O formato de dados deve ser JSON, exceto quando o endpoint não possuir corpo de requisição.
• O cliente deve enviar Accept: application/json.
• Quando houver corpo JSON, o cliente deve enviar Content-Type: application/json.
• Datas e horários devem utilizar UTC no formato ISO 8601, por exemplo, 2026-07-20T20:30:00Z.
• Nomes de propriedades JSON devem utilizar camelCase.

Finalidade

Autenticar a aplicação cliente por meio da combinação de:

• uma API key; e
• credenciais de aplicação no formato HTTP Basic Auth.

Após validação das duas credenciais, o provedor retorna um access token do tipo Bearer, limitado à criação de sessões SSO.

Requisição

POST /api/v1/auth/token HTTP/1.1
Host: api.exemplo.com
Accept: application/json
Authorization: Basic <base64(clientId:clientSecret)>
X-API-Key: <api-key>

Este endpoint não exige corpo de requisição.

Cabeçalhos

Resposta de sucesso

HTTP 200 OK

{
  "success": true,
  "result": {
    "accessToken": "eyJhbGciOiJSUzI1NiIs...",
    "tokenType": "Bearer",
    "expiresIn": 300,
    "expiresAt": "2026-07-20T20:35:00Z",
    "scope": "sso:session:create"
  },
  "errors": null
}

Regras do token

• O token deve possuir vida curta. Recomenda-se 5 minutos, com limite máximo recomendado de 15 minutos.
• O endpoint não deve emitir refresh token para este fluxo.
• O token deve ser restrito ao provedor, ambiente, cliente e finalidade para os quais foi emitido.
• O token não deve conceder acesso a APIs de negócio, dados educacionais ou funções administrativas.
• O token não deve ser incluído em query string, fragmento de URL, logs ou mensagens de erro.

Exemplo com cURL

curl --request POST \
  --url 'https://api.exemplo.com/api/v1/auth/token' \
  --user '<clientId>:<clientSecret>' \
  --header 'X-API-Key: <api-key>' \
  --header 'Accept: application/json'

Finalidade

Validar o access token, localizar e autorizar o usuário e criar uma URL temporária de uso único para acesso à plataforma de destino.

Requisição

POST /api/v1/sso/sessions HTTP/1.1
Host: api.exemplo.com
Accept: application/json
Content-Type: application/json
Authorization: Bearer <access-token>
X-Correlation-Id: 42e3da7c-63e9-46ec-9fd3-10e1ef8b9321

{
  "userId": "7d3cce21-8412-4f1e-a9f5-0f893fa35c91"
}

Cabeçalhos

Corpo

Regras do identificador:

• deve corresponder ao identificador acordado e provisionado entre as partes;
• deve ser único dentro do contexto identificado pelas credenciais da integração;
• e-mail, CPF, nome, matrícula mutável ou outro dado pessoal não deve ser adotado como chave canônica quando existir um identificador técnico estável;
• o provedor deve confirmar que o usuário pertence à instituição e ao contexto do cliente autenticado;
• receber um userId válido não é suficiente: o provedor deve verificar se o usuário está ativo e autorizado a acessar a plataforma;
• o endpoint não deve permitir que credenciais de uma instituição criem sessões para usuários de outra instituição.

Resposta de sucesso

HTTP 200 OK

{
  "success": true,
  "result": {
    "launchUrl": "https://app.exemplo.com/sso/consume?code=H1p3F5m7...",
    "expiresIn": 60,
    "expiresAt": "2026-07-20T20:31:00Z"
  },
  "errors": null
}

Regras da URL de acesso

• A URL deve utilizar HTTPS.
• Recomenda-se validade de 60 segundos, com limite máximo recomendado de 5 minutos.
• A URL deve ser invalidada imediatamente após o primeiro uso bem-sucedido.
• O código presente na URL deve ser aleatório, imprevisível, de alta entropia e armazenado de forma protegida pelo provedor.
• O código deve estar associado ao usuário, cliente, instituição, ambiente, expiração e finalidade.
• A URL não deve carregar API key, Basic Auth, access token, e-mail, CPF, nome, matrícula ou outros dados pessoais.
• Após consumir o código, a aplicação deve criar sua sessão normal por cookie seguro e redirecionar o navegador para uma URL limpa, sem o código temporário.
• Uma tentativa de reutilização, expiração ou adulteração da URL deve falhar de forma segura e pode direcionar o usuário para a autenticação convencional ou para uma página de erro controlada.
• A URL não deve ser enviada automaticamente por e-mail, mensageria ou outro canal sem proteção adicional.
• A resposta que contém a URL não deve ser armazenada em cache nem registrada integralmente em logs.

Redirecionamento do usuário

A plataforma de origem pode:

• executar um redirecionamento HTTP para a launchUrl; ou
• abrir a launchUrl após uma ação explícita do usuário.

O backend da plataforma de origem deve obter a URL.

Exemplo com cURL

curl --request POST \
  --url 'https://api.exemplo.com/api/v1/sso/sessions' \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{"userId":"7d3cce21-8412-4f1e-a9f5-0f893fa35c91"}'

Todas as respostas com corpo devem seguir o envelope:

{
  "success": true,
  "result": {},
  "errors": null
}

Regras do envelope

• Em respostas 2xx, success deve ser true, result deve conter o resultado e errors deve ser null.
• Em respostas 4xx ou 5xx, success deve ser false, result deve ser null e errors deve ser um array com pelo menos um erro.
• A API não deve retornar HTTP 200 com success: false.
• Mensagens de erro não devem revelar credenciais, tokens, existência de segredos, detalhes internos, stack traces, consultas ou componentes de infraestrutura.

Estrutura de erro

{
  "success": false,
  "result": null,
  "errors": [
    {
      "code": "AUTH_INVALID_CREDENTIALS",
      "message": "Não foi possível autenticar a aplicação cliente.",
      "target": null,
      "details": null
    }
  ]
}

Credenciais e segregação

• Cada direção da integração deve possuir credenciais próprias.
• Cada instituição, EdTech e ambiente deve possuir credenciais segregadas.
• Credenciais de homologação não devem acessar dados ou usuários de produção.
• API keys e segredos devem ser gerados com entropia adequada, armazenados em cofre de segredos e nunca mantidos em código-fonte, arquivos de configuração versionados, tickets ou documentação pública.
• Deve existir processo seguro de emissão, ativação, rotação, revogação e substituição de credenciais.
• A rotação deve permitir transição controlada quando necessária e deve ser imediata em caso de suspeita de comprometimento.
• Credenciais não devem ser compartilhadas por e-mail ou mensageria aberta. O canal de entrega deve ser acordado no onboarding.
• O provedor pode adotar allowlist de IP como defesa adicional, sem substituir autenticação e TLS.

Privilégio mínimo

• O token deve possuir apenas o escopo necessário para criar uma sessão SSO.
• O cliente deve conseguir criar sessões somente para as instituições e os usuários associados ao seu contrato.
• A plataforma de origem deve obter o userId da própria sessão autenticada e de dados confiáveis no backend. O navegador não deve conseguir substituir livremente o identificador do usuário enviado ao provedor.
• Perfis, papéis e permissões do usuário devem ser resolvidos e aplicados pela plataforma de destino.
• O fluxo não deve elevar permissões nem permitir que o cliente informe livremente papéis administrativos.
• Criação automática de usuário, atualização cadastral e atribuição de papéis ficam fora deste contrato.

Proteção contra abuso

• Os endpoints devem possuir rate limiting e monitoramento de tentativas inválidas.
• Repetidas falhas de autenticação, acessos entre instituições, reuso de URL e padrões anômalos devem gerar eventos de segurança.
• Respostas de autenticação devem evitar diferenças que permitam descobrir qual parte da credencial está correta.
• O provedor deve proteger o endpoint de consumo contra replay, força bruta e manipulação do código.
• Relógios dos servidores devem ser sincronizados para validar expirações corretamente.

O provedor deve registrar, no mínimo:

• data e hora UTC;
• X-Request-Id e X-Correlation-Id;
• cliente, instituição, direção da integração e ambiente;
• operação solicitada;
• resultado e status HTTP;
• código de erro, quando houver;
• identificador técnico pseudonimizado do usuário, quando necessário;
• emissão, consumo, expiração, revogação ou tentativa de reuso da autorização de acesso;
• origem técnica da requisição, conforme políticas de privacidade e segurança.

Não devem ser registrados:

• API key;
• clientSecret;
• valor integral do cabeçalho Authorization;
• access token;
• URL de acesso completa ou seu código;
• cookies de sessão;
• dados pessoais sem necessidade operacional.

Tokens, chaves e códigos podem ser correlacionados por hash não reversível ou identificador interno seguro, desde que isso não permita sua reutilização.

• Recomenda-se timeout de conexão de até 5 segundos e timeout total de até 15 segundos por chamada, ajustável por acordo de nível de serviço.
• O cliente deve aplicar backoff exponencial com jitter nas falhas transitórias.
• O cliente deve limitar o número de tentativas para evitar tempestades de requisições.
• A plataforma de origem deve apresentar erro controlado quando não for possível obter a URL.
• Falha na criação do SSO não deve resultar em acesso anônimo ou em sessão com usuário diferente.
• O provedor deve informar janelas planejadas de manutenção conforme os canais e prazos acordados.

Cada parte deve fornecer, por ambiente e direção:

Observação: exemplos de hosts, identificadores, chaves, tokens, códigos e datas apresentados nesta especificação são ilustrativos e não devem ser reutilizados em qualquer ambiente.

A integração segue o padrão de portas governadas por contrato: o Orquestrador é a única origem de provisionamento (fluxo outbound Orquestrador → EdTech) e a única consumidora oficial de resultados (fluxo inbound EdTech → Orquestrador). A EdTech não consome dados diretamente do sistema acadêmico de origem nem de outras EdTechs, todo tráfego passa pelas interfaces contratadas.

Premissas

• Fonte autoritativa: o cadastro (usuários, turmas, matrículas, vínculos) é sempre do Orquestrador. A EdTech não cria, altera ou reativa usuários provisionados por conta própria.
• Identidade federada: a autenticação do usuário final ocorre por SSO no provedor de identidade do Orquestrador (ver módulo Identidade). A EdTech não mantém senhas próprias para usuários provisionados.
• Contrato antes de tráfego: nenhum dado trafega sem Contrato de Dados assinado pelas duas partes, em homologação e em produção.

Granularidade por tipo de dado

Na prática, uma integração com uma EdTech não é monolítica: cada conexão é dividida em "produtos" de dados independentes, por exemplo, Tarefas, Usuários, Turmas e Notificações, cada um habilitado ou desabilitado separadamente para aquela EdTech. Isso permite religar só um tipo de dado sem afetar os demais em caso de incidente ou mudança de escopo.

Entidades e campos mínimos que toda integração deve enviar e aceitar. O schema exato (tipos físicos, tamanhos, enums) é formalizado no Contrato de Dados de cada interface.

APIs mínimas que toda EdTech deve expor. Os nomes de endpoints abaixo são ilustrativos; o que é obrigatório é a capacidade — a EdTech pode expor nomes próprios desde que o Contrato de Dados os formalize.

Padrões técnicos

Idempotência e reprocessamento

Processamento em lote e janelas

Tratamento e taxonomia de erros

As respostas de erro alimentam a observabilidade do Orquestrador (logs de sumário e detalhe por execução). Erros são classificados em duas famílias, e a resposta da EdTech deve permitir essa classificação automática:

Formalização obrigatória de cada interface, as regras gerais de contrato herdadas de todo o Orquestrador estão no Manifesto de Dados (ver Governança Federada); aqui ficam as obrigações específicas de Integrações.

Os valores mínimos por padrão são os do Manifesto de Dados (availability, latency, freshness, retention, support, backup). Cada interface de Integrações pode declarar desvios específicos no seu próprio Contrato de Dados, incluindo um objeto adicional não coberto pelo padrão-base:

Os requisitos gerais de segurança e LGPD herdados de todo o Orquestrador estão no Manifesto de Dados (ver Governança Federada). Específico de Integrações:

O Orquestrador registra, para cada execução, um log de sumário (totais processados, sucesso, atenção, erro) e logs de detalhe por item. Para que isso funcione, a EdTech deve:

Fases e critérios de aceite para uma nova EdTech se conectar ao Orquestrador.

Preenchido pela EdTech e verificado pelo Orquestrador na fase 4 do onboarding. Cada item referencia o requisito correspondente.