> ## Documentation Index
> Fetch the complete documentation index at: https://docs.easygoal.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# SSO — Visão Geral

> O serviço de autenticação centralizado do ecossistema EasyGoal.

## O que é o SSO EasyGoal?

O SSO (Single Sign-On) é o serviço de autenticação centralizado do ecossistema Easy Goal. Ele:

* Autentica usuários usando **Supabase Auth** (email/senha + OAuth Google, GitHub, Azure/Microsoft)
* Emite um cookie `eg_session` (JWT assinado) compartilhável em subdomínios `.easygoal.com.br`
* Injeta `?eg_session=<token>` nos redirects cross-domain para apps internos autorizados
* Para apps externos: emite um `eg_token` temporário trocável via `POST /auth/verify`
* Recebe webhooks do **app-front** quando um pagamento é confirmado

## Fluxo resumido

```
[Usuário acessa app]
    ↓
App detecta sem sessão → redireciona para SSO /auth/login?redirect_to=<callback>
    ↓
SSO autentica via Supabase (PKCE)
    ↓
/auth/callback: cria/valida perfil, assina eg_session, seta cookie httpOnly
    ↓
/auth/welcome: tela de splash (4s)
    ↓
Redirect para redirect_to com ?eg_session=<token> (se cross-domain autorizado)
    ↓
App /auth/callback: salva eg_session no cookie local → redireciona para destino final
```

<Note>
  O parâmetro de redirect é `redirect_to` (não `redirect_uri`). Use sempre `redirect_to` ao construir URLs de redirecionamento para o SSO. A URL deve estar cadastrada em **Supabase → Auth → URL Configuration**.
</Note>

## Cookie `eg_session`

O `eg_session` é um JWT assinado com `SSO_JWT_SECRET` e setado em:

* **`httpOnly: true`** — não acessível por JavaScript
* **`domain: .easygoal.com.br`** em produção — compartilhado entre todos os subdomínios

Claims do `eg_session`:

| Campo          | Tipo      | Descrição                                                    |
| -------------- | --------- | ------------------------------------------------------------ |
| `sub`          | `string`  | ID do usuário (= `auth.uid()` no Supabase)                   |
| `email`        | `string`  | E-mail do usuário                                            |
| `name`         | `string`  | Nome completo                                                |
| `avatar_url`   | `string`  | URL do avatar                                                |
| `is_producer`  | `boolean` | `true` se o produtor tem status `verified`                   |
| `is_beta`      | `boolean` | `true` se aceitou o NDA do programa beta                     |
| `company_name` | `string`  | Nome da empresa vinculada                                    |
| `rank_name`    | `string`  | Rank atual do usuário                                        |
| `plan_slug`    | `string`  | Plano ativo (`easy-standard`, `easy-pro`, `easy-enterprise`) |
| `provider`     | `string`  | Provider OAuth usado (`google`, `github`, `azure`, `email`)  |

<Note>
  Não há claim `role` ou `discord_id` no `eg_session`. A autorização de administrador é verificada no app-front via `requireAdmin()` que consulta o banco diretamente.
</Note>

## Integração via `@easygoal/packages/auth` (recomendado)

Para conectar um app ao SSO, use o package do monorepo. Ele encapsula o `handleAuthCallback`, `EgSessionProvider` e hook `useEgSession`.

Veja o fluxo completo em [Autenticação Cross-Domain](/sso/autenticacao-cross-domain).

## Variáveis de Ambiente do SSO

```env theme={null}
# Supabase (mesma instância compartilhada com o app-front)
NEXT_PUBLIC_SUPABASE_URL=https://your-project-ref.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

# URL pública do SSO
NEXT_PUBLIC_APP_URL=https://sso.easygoal.com.br

# Segredo para assinar eg_session JWT
SSO_JWT_SECRET=your-jwt-secret

# Webhook — DEVE ser idêntico ao SSO_WEBHOOK_SECRET do app-front
WEBHOOK_SECRET=your-webhook-secret-key

# Domínio do cookie (produção)
COOKIE_DOMAIN=.easygoal.com.br

# Email
RESEND_API_KEY=your-resend-api-key
```

<Warning>
  `WEBHOOK_SECRET` (SSO) e `SSO_WEBHOOK_SECRET` (app-front) devem ser **idênticos**. Qualquer divergência fará com que todos os webhooks sejam rejeitados com status 401.
</Warning>

## Endpoints do SSO

| Método | Endpoint                | Descrição                                                          |
| ------ | ----------------------- | ------------------------------------------------------------------ |
| `GET`  | `/auth/login`           | Formulário de login — aceita `?redirect_to=<url>`                  |
| `GET`  | `/auth/signup`          | Criar conta                                                        |
| `GET`  | `/auth/forgot-password` | Solicitar reset de senha                                           |
| `GET`  | `/auth/reset-password`  | Redefinir senha (via link de email)                                |
| `GET`  | `/auth/callback`        | Callback OAuth do Supabase — cria perfil + emite eg\_session       |
| `GET`  | `/auth/welcome`         | Tela de splash (4s) exibida após login — redireciona para destino  |
| `GET`  | `/auth/check`           | Verifica se o `eg_session` cookie é válido — retorna JSON          |
| `POST` | `/auth/verify`          | Valida `eg_token` temporário de app externo — retorna `eg_session` |
| `POST` | `/auth/signout`         | Logout — invalida cookie `eg_session`                              |
| `GET`  | `/auth/error`           | Página de erro de autenticação                                     |
| `GET`  | `/complete-profile`     | Completar perfil após OAuth                                        |
| `GET`  | `/api/me`               | Retorna perfil do usuário via `Bearer <supabase_token>`            |
| `POST` | `/api/webhook/payment`  | Recebe notificação de compra (HMAC SHA256)                         |
| `GET`  | `/api/webhook/payment`  | Health check do endpoint                                           |
| `GET`  | `/api/plans/public`     | Planos disponíveis (público)                                       |

## Checklist do SSO

<Check>Configurar `SSO_JWT_SECRET` para assinar o `eg_session`</Check>
<Check>Configurar `WEBHOOK_SECRET` (= `SSO_WEBHOOK_SECRET` do app-front)</Check>
<Check>Configurar `NEXT_PUBLIC_SUPABASE_URL` e `NEXT_PUBLIC_SUPABASE_ANON_KEY`</Check>
<Check>Adicionar URLs de redirect em Supabase → Auth → URL Configuration</Check>
<Check>Registrar URLs de callback em Supabase → Auth → Redirect URLs</Check>
<Check>Implementar `POST /api/webhook/payment` com verificação HMAC SHA256</Check>
<Check>Testar webhook com o botão "Testar Webhook" no admin do app-front</Check>