Integração SSO — Especificação Técnica

1.1 Objetivo

Este documento especifica como um sistema parceiro deve se integrar ao mecanismo de Single Sign-On (SSO) da Plataforma Semente. O objetivo é permitir que um usuário já autenticado no sistema do parceiro (por exemplo, o sistema de gestão escolar) acesse a Plataforma Semente sem precisar realizar um novo login manual.

A integração é feita através da geração de um token assinado (JWT) pelo parceiro, enviado a um endpoint HTTP da Semente, que valida o token e autentica o usuário correspondente.

1.2 Fluxo Resumido

1. O usuário se autentica normalmente no sistema do parceiro.
2. Em algum momento posterior, o usuário clica em uma opção do tipo "Acessar Plataforma Semente" dentro do sistema do parceiro.
3. Esse clique aciona o sistema do parceiro a gerar um token JWT assinado, identificando o usuário.
4. O parceiro entrega esse token ao navegador do usuário: o back-end do parceiro responde a esse clique devolvendo uma página HTML com o token embutido, que se auto-submete via POST ao endpoint de SSO da Semente (ver seção 4.5).
5. A Semente valida o token.
6. Se válido, a Semente autentica o usuário, define um cookie de sessão no navegador e redireciona o navegador diretamente para a Plataforma Semente, já autenticada.

1.3 Diagrama do Fluxo

O diagrama abaixo ilustra a sequência completa da integração. Note que, a partir do passo 5, quem conversa com a Semente é o navegador do usuário — não o back-end do parceiro:

Caso qualquer validação do passo 6 falhe (assinatura, audience/issuer, expiração ou reuso do jti), a Semente responde com erro diretamente ao navegador do usuário — a página intermediária do parceiro (a mesma que fez o POST no passo 5) precisa estar preparada para tratar essa resposta de erro.

2.1 Dados fornecidos pela Semente

Antes de iniciar a implementação, a Semente fornecerá ao parceiro, por canal seguro, os seguintes dados:

• Client ID: identificador único do parceiro.
• Secret: chave de 256 bits, codificada em Base64, usada para assinar o token (HMAC-SHA256).

2.2 Sobre a Codificação em Base64

O secret é gerado pela Semente como uma sequência de bytes aleatórios e entregue ao parceiro já codificado em Base64 — essa codificação existe apenas para que um valor binário possa ser transmitido e copiado como texto (e-mail, painel, etc.).

O parceiro não precisa gerar nem codificar nada em Base64. O único passo necessário do lado do parceiro é decodificar a string recebida de volta para bytes brutos antes de usá-la como chave de assinatura HMAC — exatamente como mostrado nos exemplos da seção 5 (Convert.FromBase64String, base64.b64decode, Base64.getDecoder().decode, entre outros).

3.1 Claims Obrigatórias

3.2 Algoritmo e Chave

• Algoritmo de assinatura: HS256 (HMAC-SHA256). Nenhum outro algoritmo é aceito.
• Chave de assinatura: o secret fornecido pela Semente, decodificado de Base64 para bytes brutos antes de assinar.

3.3 Regras de Validade

• O token deve ter validade de exatamente 5 minutos entre iat e exp.
• Cada token deve conter um jti único (recomenda-se UUID v4). Um token com o mesmo jti não pode ser reenviado — a segunda tentativa será rejeitada, mesmo dentro da janela de validade.
• O relógio do sistema do parceiro deve estar sincronizado (NTP). Diferenças de horário podem causar rejeição indevida do token.

4.1 URL e Método

A requisição HTTP POST com o token deve ser enviada para:

POST https://integracao.sementeeducacao.com.br/api/v0/accounts/sso_custom

4.2 Formato da Requisição

O corpo da requisição deve conter o token no campo token, como application/x-www-form-urlencoded — o mesmo formato que um <form> HTML nativo envia. Esse formato (em vez de JSON) é proposital: é o que permite que a requisição seja feita por uma navegação real do navegador (um formulário que se auto-submete), sem depender de JavaScript assíncrono (fetch/XHR), que esbarraria em CORS e em restrições de cookie de terceiros. É a mesma técnica do HTTP-POST Binding usado em autenticações SAML 2.0 — a integração da Semente não usa SAML, mas resolve o mesmo problema (entregar uma credencial ao navegador do usuário) da mesma forma consolidada. Veja o exemplo completo na seção 4.4.

POST /api/v0/accounts/sso_custom HTTP/1.1
Host: integracao.sementeeducacao.com.br
Content-Type: application/x-www-form-urlencoded

token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJqb2FvLnNpbHZhIiwi...

4.3 Respostas

Em caso de sucesso, a Semente não retorna um token em JSON — ela autentica o usuário, define um cookie de sessão no navegador e redireciona a resposta para a Plataforma Semente:

HTTP/1.1 302 Found
Location: <URL da Plataforma Semente>
Set-Cookie: <cookie de sessão>

O header Location aponta para a Plataforma Semente e o Set-Cookie estabelece a sessão de acesso — como essa resposta é endereçada ao navegador (não a um caller server-to-server), o próprio navegador segue o redirecionamento automaticamente e chega à Plataforma Semente já autenticado.

Em caso de falha de validação:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "mensagem": "Token expirado ou já utilizado"
}

Códigos de retorno possíveis:

4.4 Página de Redirecionamento (Exemplo)

Abaixo, um exemplo completo da página intermediária que o back-end do parceiro deve gerar e devolver ao navegador do usuário logo após o clique em "Acessar Plataforma Semente" (passo 2 do diagrama). O back-end preenche o campo value com o JWT recém-gerado; o formulário se auto-submete assim que a página carrega, e o <noscript> garante um botão manual como alternativa para o raro caso de JavaScript desabilitado:

<!DOCTYPE html>
<html lang="pt-BR">
<head>
  <meta charset="UTF-8">
  <title>Redirecionando para a Plataforma Semente...</title>
</head>
<body>
  <p>Redirecionando, aguarde…</p>

  <form id="sso-form" method="POST" action="https://integracao.sementeeducacao.com.br/api/v0/accounts/sso_custom">
    <input type="hidden" name="token" value="SEU_JWT_GERADO_AQUI">
    <noscript>
      <button type="submit">Clique aqui para continuar</button>
    </noscript>
  </form>

  <script>
    document.getElementById('sso-form').submit();
  </script>
</body>
</html>

4.5 Gerando e Devolvendo a Página no Back-end (Exemplo Completo)

O exemplo da seção 4.4 mostra apenas o HTML final — o que falta é o código do back-end do parceiro que responde ao clique em "Acessar Plataforma Semente" (passo 2 do diagrama) gerando o JWT (seção 5), embutindo-o nesse template e devolvendo o resultado como resposta HTTP com Content-Type: text/html. É esse handler que fecha o ciclo entre "gerar o token" e "entregar a página" ao navegador.

using System.Net;

// GET /sso/iniciar — chamado quando o usuário clica em "Acessar Plataforma Semente"
app.MapGet("/sso/iniciar", () =>
{
    string jwt = GerarJwt(); // ver seção 5.1
    string tokenEscapado = WebUtility.HtmlEncode(jwt);

    string html = $@"<!DOCTYPE html>
<html lang=""pt-BR"">
<head>
  <meta charset=""UTF-8"">
  <title>Redirecionando para a Plataforma Semente...</title>
</head>
<body>
  <p>Redirecionando, aguarde…</p>
  <form id=""sso-form"" method=""POST"" action=""https://integracao.sementeeducacao.com.br/api/v0/accounts/sso_custom"">
    <input type=""hidden"" name=""token"" value=""{tokenEscapado}"">
    <noscript><button type=""submit"">Clique aqui para continuar</button></noscript>
  </form>
  <script>document.getElementById('sso-form').submit();</script>
</body>
</html>";

    return Results.Content(html, "text/html");
});

from flask import Flask, Response
from markupsafe import escape

app = Flask(__name__)

@app.route("/sso/iniciar")
def sso_iniciar():
    jwt_token = gerar_jwt()  # ver seção 5.2

    html = f"""<!DOCTYPE html>
<html lang="pt-BR">
<head>
  <meta charset="UTF-8">
  <title>Redirecionando para a Plataforma Semente...</title>
</head>
<body>
  <p>Redirecionando, aguarde…</p>
  <form id="sso-form" method="POST" action="https://integracao.sementeeducacao.com.br/api/v0/accounts/sso_custom">
    <input type="hidden" name="token" value="{escape(jwt_token)}">
    <noscript><button type="submit">Clique aqui para continuar</button></noscript>
  </form>
  <script>document.getElementById('sso-form').submit();</script>
</body>
</html>"""

    return Response(html, mimetype="text/html")

import org.springframework.web.util.HtmlUtils;

@GetMapping("/sso/iniciar")
public ResponseEntity<String> ssoIniciar() {
    String jwt = gerarJwt(); // ver seção 5.3
    String tokenEscapado = HtmlUtils.htmlEscape(jwt);

    String html = """
        <!DOCTYPE html>
        <html lang="pt-BR">
        <head>
          <meta charset="UTF-8">
          <title>Redirecionando para a Plataforma Semente...</title>
        </head>
        <body>
          <p>Redirecionando, aguarde…</p>
          <form id="sso-form" method="POST" action="https://integracao.sementeeducacao.com.br/api/v0/accounts/sso_custom">
            <input type="hidden" name="token" value="%s">
            <noscript><button type="submit">Clique aqui para continuar</button></noscript>
          </form>
          <script>document.getElementById('sso-form').submit();</script>
        </body>
        </html>
        """.formatted(tokenEscapado);

    return ResponseEntity.ok().contentType(MediaType.TEXT_HTML).body(html);
}

const express = require("express");
const escapeHtml = require("escape-html");

const app = express();

app.get("/sso/iniciar", (req, res) => {
  const jwt = gerarJwt(); // ver seção 5.4

  const html = `<!DOCTYPE html>
<html lang="pt-BR">
<head>
  <meta charset="UTF-8">
  <title>Redirecionando para a Plataforma Semente...</title>
</head>
<body>
  <p>Redirecionando, aguarde…</p>
  <form id="sso-form" method="POST" action="https://integracao.sementeeducacao.com.br/api/v0/accounts/sso_custom">
    <input type="hidden" name="token" value="${escapeHtml(jwt)}">
    <noscript><button type="submit">Clique aqui para continuar</button></noscript>
  </form>
  <script>document.getElementById('sso-form').submit();</script>
</body>
</html>`;

  res.set("Content-Type", "text/html");
  res.send(html);
});

<?php
// GET /sso/iniciar
$jwt = gerarJwt(); // ver seção 5.5
$tokenEscapado = htmlspecialchars($jwt, ENT_QUOTES, 'UTF-8');

header("Content-Type: text/html; charset=UTF-8");
?>
<!DOCTYPE html>
<html lang="pt-BR">
<head>
  <meta charset="UTF-8">
  <title>Redirecionando para a Plataforma Semente...</title>
</head>
<body>
  <p>Redirecionando, aguarde…</p>
  <form id="sso-form" method="POST" action="https://integracao.sementeeducacao.com.br/api/v0/accounts/sso_custom">
    <input type="hidden" name="token" value="<?= $tokenEscapado ?>">
    <noscript><button type="submit">Clique aqui para continuar</button></noscript>
  </form>
  <script>document.getElementById('sso-form').submit();</script>
</body>
</html>