eCosif — Structure

Gateway e backends — modo híbrido ECOSIF_JWT + Azure

Documentação de operação para ECOSIF_API_TOKEN_MODE=HYBRID_ECOSIF_AZURE (P7-E).

Objetivo

No mesmo ambiente, permitir:

Origem do login Token nas APIs (Authorization) Algoritmo
Formulário local (signin) JWT ECOSIF HS256
Microsoft (AZURE) id_token Azure RS256
Microsoft (AZURE_ENTERPRISE) access_token Azure RS256

O token enviado é fixo à origem do login — não há troca de ECOSIF ↔ Azure na mesma sessão.

Variáveis obrigatórias

Angular + backends (5 serviços Java)

ECOSIF_API_TOKEN_MODE=HYBRID_ECOSIF_AZURE
ECOSIF_ENABLE_LOCAL_AUTH=true
ECOSIF_ENABLE_AZURE_AUTH=true
ECOSIF_AZURE_CLIENT_ID=<app-registration-spa>
ECOSIF_AZURE_TENANT_ID=<tenant-id>
ECOSIF_AZURE_AUTHORITY=https://login.microsoftonline.com/<tenant-id>
ECOSIF_AUTH_PROVIDER=AZURE              # cenário 2
# ou ECOSIF_AUTH_PROVIDER=AZURE_ENTERPRISE   # cenário 3

Cenário 2 (AZURE — id_token)

ECOSIF_AUTH_PROVIDER=AZURE
ECOSIF_AZURE_SCOPES=openid,profile,email
ECOSIF_AZURE_EXPECTED_AUDIENCE=         # vazio = client-id (validação em external-login)
# Backends: ecosif.security.azure.api-audience vazio ou client-id conforme decoder

Cenário 3 (AZURE_ENTERPRISE — access token)

ECOSIF_AUTH_PROVIDER=AZURE_ENTERPRISE
ECOSIF_AZURE_SCOPES=openid,profile,email,api://<client-id>/access_as_user
ECOSIF_AZURE_API_AUDIENCE=api://<client-id>

Backends validam aud via ecosif.security.azure.api-audience (ECOSIF_AZURE_API_AUDIENCE).

Fluxo

sequenceDiagram
  participant U as Usuário
  participant A as Angular
  participant Auth as ecosif-auth
  participant API as Microsserviço

  alt Login local
    U->>A: usuário/senha
    A->>Auth: POST /signin
    Auth-->>A: JWT ECOSIF
    A->>A: session origin = LOCAL
    A->>API: Bearer JWT ECOSIF (HS256)
  else Login Microsoft
    U->>A: MSAL popup
    A->>Auth: POST /external-login (id_token)
    Auth-->>A: JWT ECOSIF (sessão/guard)
    A->>A: session origin = AZURE_ID ou AZURE_ENTERPRISE
    A->>API: Bearer token Azure cru (RS256)
  end

Backend (starter 0.7.07.202607081+)

Angular (P7-23)

Gateway (cenário 4 — follow-up)

Sem API Gateway na frente (cenários 2 e 3), a validação é direta nos microsserviços.

Quando houver gateway (Traefik, APIM, ALB), ele deve aceitar ambos os formatos na mesma rota — ou delegar validação ao backend. Caso contrário, um dos tokens será barrado antes do Java.

Flags sugeridas (documentação):

ECOSIF_GWVAL_JWT_ECOSIF=true
ECOSIF_GWVAL_ACCESSTOKEN_MS=true   # quando o gateway também validar RS256

Checklist E2E (QAS)

  1. [ ] ECOSIF_API_TOKEN_MODE=HYBRID_ECOSIF_AZURE em Angular + 5 backends
  2. [ ] Login local → Authorization com JWT HS256 → API 200
  3. [ ] Login Microsoft → external-login 200 → APIs com token RS256 → 200
  4. [ ] Usuário Azure sem vínculo → 401 até external-login concluir
  5. [ ] Logout limpa ecosif_session_login_origin e tokens IdP
  6. [ ] Logs backend indicam ramo ecosif_jwt ou azure (sem imprimir token)

Troubleshooting

Sintoma Causa provável Ação
401 após login Microsoft OK aud divergente Cenário 2: aud = client-id; cenário 3: ECOSIF_AZURE_API_AUDIENCE
APIs ainda enviam JWT ECOSIF após Azure Origem de sessão não persistida Conferir sessionStorage.ecosif_session_login_origin
Botão Azure ausente ECOSIF_ENABLE_AZURE_AUTH=false Habilitar ou usar modo híbrido com vars Azure no env-map
401 login local Modo não híbrido no backend Conferir ECOSIF_API_TOKEN_MODE nos containers Java

Referências