Skip to main content

​
Visão Geral

O SSO distribui autenticação para apps em outros domínios de duas formas:
CenárioMecanismoQuando usar
App interno (subdomínio .easygoal.com.br)?eg_session=<token> no redirectapp-front, club LP, sites internos
App externo (domínio externo, API key obrigatória)?eg_token=<token> + POST /auth/verifyparceiros, integrações terceiras
O browser envia o cookie eg_session (setado em .easygoal.com.br) naturalmente para todos os subdomínios — o SSO apenas replica o token para apps que não alcançam o cookie.

​
App Interno — Fluxo com eg_session

[App] → SSO /auth/login?redirect_to=https://app.easygoal.com.br/auth/callback
    ↓
SSO autentica → seta cookie eg_session em .easygoal.com.br
    ↓
SSO /auth/welcome → redirect para https://app.easygoal.com.br/auth/callback?eg_session=<token>
    ↓
App /auth/callback: handleAuthCallback → salva eg_session no cookie local → redirect
Setup mínimo: 
// src/app/auth/callback/route.ts
import { createCallbackRoute } from '@easygoal/packages/auth/server';

export const GET = createCallbackRoute({
  ssoUrl: process.env.NEXT_PUBLIC_SSO_URL,
  appUrl: process.env.NEXT_PUBLIC_APP_URL,
});

// layout.tsx
import { EgSessionProvider } from '@easygoal/packages/auth/client';

export default function RootLayout({ children }) {
  return <EgSessionProvider>{children}</EgSessionProvider>;
}
O EgSessionProvider lê /api/auth/session (rota gerada pelo package) que retorna os claims do eg_session cookie.

​
App Externo — Fluxo com eg_token

Para apps em domínios externos (sem acesso ao cookie .easygoal.com.br): 
[App Externo] → SSO /auth/login?redirect_to=<callback>&api_key=<chave>
    ↓
SSO autentica → redirect_to?eg_token=<token_temporário_5min>
    ↓
App /auth/callback (server-side):
  POST /auth/verify (Authorization: Bearer <api_key>, body: { token: eg_token })
  → retorna eg_session JWT
  → salva eg_session no cookie local
    ↓
Redirect para destino final
Setup: 
// src/app/auth/callback/route.ts
import { createCallbackRoute } from '@easygoal/packages/auth/server';

export const GET = createCallbackRoute({
  ssoUrl: process.env.NEXT_PUBLIC_SSO_URL,
  appUrl: process.env.NEXT_PUBLIC_APP_URL,
  apiKey: process.env.EG_API_KEY, // obrigatório para apps externos
});

NEXT_PUBLIC_SSO_URL=https://sso.easygoal.com.br
NEXT_PUBLIC_APP_URL=https://meuapp.com
EG_API_KEY=eg_live_sua_chave_aqui
EG_API_KEY é usada server-side em POST /auth/verify. Nunca exponha como NEXT_PUBLIC_. Para apps que precisam iniciar o login via client, use apenas a URL pública do SSO — o api_key só é necessário no callback server-side.

​
Pré-requisitos para apps externos

  1. Produto registrado no SSO com status: approved
  2. URL do callback cadastrada em saas_products.redirect_urls
  3. API key ativa para o produto

​
Verificar sessão server-side

Para proteger rotas ou verificar autenticação em Server Components/middleware: 
// Opção A: via GET /auth/check (lê cookie eg_session da requisição)
const res = await fetch(`${SSO_URL}/auth/check`, {
  headers: { cookie: request.headers.get('cookie') ?? '' },
  cache: 'no-store',
});
const { authenticated, session } = await res.json();

// Opção B: via EgSessionProvider (client-side)
const { user, isReady } = useEgSession();
O /auth/check é ideal para middleware de proteção de rotas — não redireciona, apenas retorna JSON com { authenticated, session }.

​
Proteção de páginas admin via auth/check

Funcionalidade planejada. Para proteger páginas da documentação (ou qualquer app) exclusivamente para administradores, seria necessário adicionar is_super_admin ao EgSessionClaims no SSO. O campo existe em AuthUser do monorepo mas ainda não é injetado no eg_session JWT. Após essa adição, o middleware pode verificar session.is_super_admin === true via /auth/check.
Fluxo planejado: 
// middleware.ts
const { authenticated, session } = await checkSession(request);

if (pathname.startsWith('/admin')) {
  if (!authenticated || !session?.is_super_admin) {
    return NextResponse.redirect('/');
  }
}

​
Checklist de Integração

Produto registrado no SSO (apenas para apps externos)
URL do callback cadastrada em saas_products.redirect_urls
Callback route implementado com createCallbackRoute
EgSessionProvider adicionado ao layout raiz
URL do callback cadastrada em Supabase → Auth → Redirect URLs
Variáveis NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY, NEXT_PUBLIC_SSO_URL configuradas