eCosif — Autenticação

Runbook — Microsoft Entra ID (Azure AD)

Guia operacional para DevOps e clientes que habilitam login Microsoft no eCosif (MVP1 Modo A — ECOSIF_API_TOKEN_MODE=ECOSIF_JWT).

Público: administradores Entra ID, DevOps, integradores.
Pré-requisitos: domínio do SPA Angular publicado (ex. https://app.cliente.com.br/).

Visão geral do fluxo

Usuário → botão Microsoft (Angular/MSAL) → popup Entra ID → id_token
       → POST /api/auth/external-login { provider: "AZURE", token: "<id_token>" }
       → ecosif-auth valida JWKS → JWT ECOSIF
       → APIs /ecosif-* com Authorization: Bearer <JWT_ECOSIF>

O token Microsoft não trafega nas APIs de negócio — apenas o JWT ECOSIF emitido pelo ecosif-auth.

1. Criar App Registration (SPA)

  1. Acesse portal.azure.com → Microsoft Entra ID → App registrations → New registration.
  2. Name: eCosif SPA (ou padrão do cliente).
  3. Supported account types: - Single tenant — uso interno (recomendado para baseline). - Multitenant — somente se o cliente exigir contas externas.
  4. Redirect URI: - Platform: Single-page application (SPA) - URI: https://{dominio}/ (barra final conforme deploy; em local: http://localhost:4200/ ou porta do Nginx)
  5. Registre e anote: - Application (client) ID → ECOSIF_AZURE_CLIENT_ID - Directory (tenant) ID → ECOSIF_AZURE_TENANT_ID

Redirect URIs adicionais (homolog)

Ambiente URI típica
Local Docker http://localhost:8080/
QAS https://qas.{cliente}.com.br/
Produção https://app.{cliente}.com.br/

O MSAL no Angular usa redirectUri: '/' (mesma origem do SPA). Cada origem usada deve estar cadastrada como SPA Redirect URI.

2. Configurar autenticação (OIDC simples — baseline)

Para ECOSIF_AUTH_PROVIDER=AZURE (contas Microsoft, sem API customizada):

  1. Em Authentication → Implicit grant and hybrid flows: não habilitar access tokens implícitos (MSAL v2 usa PKCE).
  2. Em Token configuration (opcional): adicionar claims email, preferred_username se necessário para provisionamento.
  3. Scopes solicitados pelo Angular (via ECOSIF_AZURE_SCOPES):
openid,profile,email

Não incluir User.Read / Microsoft Graph no baseline — o login usa apenas o id_token.

3. Azure Enterprise (opcional — AZURE_ENTERPRISE)

Use quando o cliente exige scope de API exposta (api://{app-id}/access_as_user):

  1. Em Expose an API → Set Application ID URI: api://{client-id}.
  2. Add a scope: access_as_user (admin consent).
  3. Em API permissions → adicionar permissão à própria API → scope access_as_user.
  4. Variáveis adicionais no eCosif:
Variável Valor
ECOSIF_AUTH_PROVIDER AZURE_ENTERPRISE
ECOSIF_AZURE_SCOPES openid,profile,email,api://{client-id}/access_as_user
ECOSIF_AZURE_API_AUDIENCE api://{client-id}

Modo B (gateway valida access token Microsoft): ver gateway_access_token_entra.md (AUTH-09 P7-06).

4. Variáveis de ambiente eCosif

Configure no .env / task ECS / env.template (via ecosif-structure):

Angular (UI + MSAL)

Variável Obrigatória Descrição
ECOSIF_ENABLE_AZURE_AUTH Sim true — exibe botão Microsoft
ECOSIF_AZURE_CLIENT_ID Sim Application (client) ID
ECOSIF_AZURE_TENANT_ID Sim Directory (tenant) ID
ECOSIF_AZURE_AUTHORITY Sim https://login.microsoftonline.com/{tenant-id}
ECOSIF_AZURE_SCOPES Recomendado openid,profile,email

Backend (ecosif-auth)

Variável Obrigatória Descrição
ECOSIF_AUTH_PROVIDER Sim AZURE ou AZURE_ENTERPRISE
ECOSIF_AZURE_CLIENT_ID Sim Mesmo client ID do SPA
ECOSIF_AZURE_TENANT_ID Sim Tenant para derivar issuer JWKS
ECOSIF_AZURE_EXPECTED_AUDIENCE Não Vazio = usa CLIENT_ID
ECOSIF_AZURE_EXPECTED_ISSUER Não Vazio = https://login.microsoftonline.com/{tenant}/v2.0
ECOSIF_AUTH_AUTO_PROVISION Recomendado true — cria usuário no primeiro login
ECOSIF_AUTH_DEFAULT_TENANT Se auto-provision Ex.: TEMP_TENANT
ECOSIF_AUTH_DEFAULT_ROLE Se auto-provision Ex.: STAFF

JWT compartilhado (auth + microsserviços)

Variável Descrição
AUTH_TOKEN_SECRET Mesmo valor em todos os serviços Java
ECOSIF_API_TOKEN_MODE ECOSIF_JWT (padrão MVP1)

Exemplo mínimo:

ECOSIF_ENABLE_LOCAL_AUTH=true
ECOSIF_ENABLE_AZURE_AUTH=true
ECOSIF_AUTH_PROVIDER=AZURE
ECOSIF_AZURE_CLIENT_ID=<application-client-id>
ECOSIF_AZURE_TENANT_ID=<tenant-id>
ECOSIF_AZURE_AUTHORITY=https://login.microsoftonline.com/<tenant-id>
ECOSIF_AZURE_SCOPES=openid,profile,email
ECOSIF_AUTH_AUTO_PROVISION=true
ECOSIF_API_TOKEN_MODE=ECOSIF_JWT

Catálogo completo: variaveis_autenticacao_baseline.md (ecosif-structure).

5. Deploy e validação

Subir ambiente

cd ecosif-structure
docker compose --env-file .env-dev build ecosif-auth ecosif-angular
docker compose --env-file .env-dev up -d

Checklist pós-deploy

Testar id_token com jwt.ms

  1. Faça login Microsoft no ambiente de homolog.
  2. No DevTools → Network, copie o id_token retornado pelo MSAL (ou use jwt.ms com token de teste).
  3. Valide claims:
Claim Esperado
iss https://login.microsoftonline.com/{tenant}/v2.0
aud ECOSIF_AZURE_CLIENT_ID (ou EXPECTED_AUDIENCE)
exp Não expirado
sub / preferred_username Identidade do usuário

Teste direto na API:

curl -s -X POST "https://{host}/ecosif-auth/api/auth/external-login" \
  -H "Content-Type: application/json" \
  -d '{"provider":"AZURE","token":"<id_token>","tokenType":"ID_TOKEN"}'

6. Problemas comuns

Sintoma Causa provável Correção
AADSTS50011 redirect URI mismatch URI não cadastrada no App Registration Adicionar origem exata (com/sem barra) em SPA Redirect URIs
Botão Microsoft não aparece Faltam ECOSIF_AZURE_* no container Angular Verificar config.json gerado pelo entrypoint
401 em external-login aud/iss inválidos ou token expirado Conferir ECOSIF_AZURE_EXPECTED_*; renovar login
APIs retornam 401 após login OK AUTH_TOKEN_SECRET diferente entre serviços Unificar secret no .env de todos os Java
429 em external-login Rate limit (P4-04) Ajustar ECOSIF_AUTH_EXT_LOGIN_RL_* ou aguardar janela

7. Referências