ADR-0001: SSO/JWT Federation — Platform como Identity Provider

Status

Accepted (Phase 1 — 2026-04-12)

Contexto

A In All Web opera 3 produtos (platform, booking-system, virtual-stores-system). Cada um gere autenticação independentemente com JWTs isolados — secrets separados, payloads incompatíveis, zero federação.

Resultado: utilizadores precisam de login separado em cada produto. Integração inter-produto (e.g. platform provisiona tenant em booking) usa credenciais sysadmin hardcoded em vez de delegação JWT.

Decisão

O iaw-platform será o identity provider central. Todos os JWTs são emitidos pelo platform; booking e virtual-stores tornam-se resource servers que validam tokens do platform.

Implementação em 3 fases

Phase 1 — Standard Claims (Actual)

• Adicionar iss, aud, jti, iat a todos os tokens emitidos pelo platform
• iss: "https://platform.inallweb.com"
• aud: ["platform", "booking", "stores"]
• jti: UUID v4 (preparação para revogação futura)
• Manter HS256 com secret partilhado via Vault
• Período de transição: 24h sem verify_iss/aud, depois activar
• Sem breaking changes — claims são adicionados, não removidos

Phase 2 — Role Alignment + Validation

• Standardizar role hierarchy: owner=5, admin=4, collaborator=3, staff=2, client=1
• Booking/stores adicionam verificação de iss e aud no decode
• Migrar todos os secrets JWT para Vault path partilhado: secret/data/products/shared/jwt
• Adicionar tenant_id ao platform JWT (null para admins platform)
• Standardizar sub como string em todos os produtos

Phase 3 — Asymmetric Signing (Futuro)

• Platform gera par de chaves RSA
• Publica chave pública em /.well-known/jwks.json
• Migrar de HS256 para RS256
• Booking/stores buscam chave pública para validação (sem shared secret)
• Eliminar credenciais sysadmin — usar JWT do utilizador directamente

JWT Payload Standard

{
  "iss": "https://platform.inallweb.com",
  "sub": "123",
  "aud": ["platform", "booking", "stores"],
  "email": "user@example.com",
  "role": "admin",
  "user_type": "admin",
  "tenant_id": null,
  "permissions": {},
  "exp": 1700000000,
  "iat": 1699900000,
  "jti": "550e8400-e29b-41d4-a716-446655440000",
  "type": "access"
}

Role Mapping Unificado

Platform	Booking	Virtual-Stores	Nível
owner	sysadmin	sysadmin	5
admin	admin	admin	4
tester	—	—	4
support	manager	manager	3
—	staff	staff	2
client	client	customer	1

Consequências

Positivas

• SSO real: login único no platform, acesso a todos os produtos
• Eliminação de credenciais sysadmin hardcoded
• Audit trail unificado (jti em todos os tokens)
• Preparação para RS256 e zero-trust

Negativas

• Dependência: se platform estiver em baixo, nenhum produto pode autenticar novos utilizadores
• Migração gradual: período de transição com backward compatibility
• Complexidade: role mapping entre 3 produtos com hierarquias diferentes

Riscos

• Secret compartilhado (Phase 1/2): compromisso de um produto compromete todos
• Clock skew entre servidores: exp e iat podem divergir
• Token revogação: sem jti blacklist, tokens emitidos são válidos até expirarem

Alternativas Consideradas

1. OAuth2/OIDC completo — demasiado complexo para 3 produtos internos
2. Token exchange (RFC 8693) — mais correcto mas requer infra adicional
3. Manter isolamento — status quo, bloqueia integração inter-produto
4. API Gateway central — single point of failure, overhead operacional

Referências

• JWT RFC 7519
• /opt/contracts/roles-permissions.md
• /opt/contracts/platform-hub-vision.md
• /opt/contracts/iaw-platform-api.md