Pular para conteúdo

Manual de implantação — B2B Entra app-only (AUTH-14)

Runbook operacional para habilitar integração machine-to-machine (client_credentials) no perímetro Modo B (AZURE_ENTERPRISE_GATEWAY).

Versão de referência: 0.7.08.202608301 (artefatos Java + starter)
PLANID: AUTH-14 · Homolog formal: AUTH-14.9 (pendente assinatura cliente)

Documentos relacionados

Documento Uso
integracao_b2b_entra_app_only.md Desenho e contrato técnico
checklist_b2b_entra_app_only.md Checklist Entra + gateway
variaveis_autenticacao_baseline.md Catálogo ECOSIF_*
spike_auth14_claims_app_only.md Claims e diagnóstico 403
auth14_entrega_tecnica_b2b_app_only.md O que foi implementado
identity_provider_link_b2b_app.md Modelo BD

1. Pré-requisitos

1.1 Ambiente

  • [ ] Perímetro já em Modo B humano (ECOSIF_API_TOKEN_MODE=AZURE_ENTERPRISE_GATEWAY) — ver gateway_access_token_entra.md
  • [ ] PostgreSQL acessível; Flyway meta-repo ≥ V0.7.00.15 aplicado
  • [ ] Imagens/containers Java na versão 0.7.08.202608301 ou superior compatível AUTH-14

1.2 Artefatos (versão mínima)

Artefato Versão
ecosif-spring-boot-starter-security 0.7.08.202608301
ecosif-database 0.7.08.202608301
ecosif-auth, ecosif-masterdata, ecosif-moviments, ecosif-querys, ecosif-reports 0.7.08.202608301

1.3 Janela e rollback

  • Implantar primeiro em QAS/homolog; produção somente após AUTH-14.9 assinado.
  • Rollback rápido: ECOSIF_ENABLE_AZURE_APP_ONLY=false (desliga ramo app-only; login humano inalterado).
  • Perfil Itaú CC (AUTH-14.10): ver manual_implantacao_b2b_itau_sts_cc.md.
  • Rollback completo: reverter imagens para versão anterior e remover vínculos B2B se necessário.

2. Flyway (banco)

# No pipeline/meta-repo flyway-ecosif — confirmar versão aplicada
# V0.7.00.15__identity_provider_link_b2b_app.sql (comments; sem DDL destrutivo)
  • [ ] Migration V0.7.00.15 aplicada no ambiente alvo
  • [ ] Tabela identity_provider_link operacional (desde V0.7.00.9)

3. Microsoft Entra ID

Seguir checklist_b2b_entra_app_only.md §1.

Resumo:

  1. API eCosif: App role de aplicação (ex.: Ecosif.Api.Access).
  2. App integrador: confidential client + secret/cert no vault do cliente.
  3. Admin consent da application permission.
  4. Anotar oid do service principal do integrador (onboarding eCosif).

Validar STS:

curl -sS -X POST "https://login.microsoftonline.com/${TENANT_ID}/oauth2/v2.0/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=${INTEGRATOR_CLIENT_ID}" \
  -d "client_secret=${INTEGRATOR_CLIENT_SECRET}" \
  -d "grant_type=client_credentials" \
  -d "scope=api://${API_CLIENT_ID}/.default"
  • [ ] HTTP 200 + access_token
  • [ ] Payload jwt.ms: aud, roles, oid, appid/azp; sem scp delegated

4. Variáveis de ambiente (containers Java)

Copiar de env.template e docker-compose.yml.

4.1 Compartilhadas Modo B (já existentes)

ECOSIF_API_TOKEN_MODE=AZURE_ENTERPRISE_GATEWAY
ECOSIF_AZURE_TENANT_ID=<tenant-guid>
ECOSIF_AZURE_API_AUDIENCE=api://<api-client-id>

4.2 Exclusivas app-only (AUTH-14)

# Homolog: true após onboarding; prod: true quando cliente validado
ECOSIF_ENABLE_AZURE_APP_ONLY=true

# CSV — valores exatos das App roles no token
ECOSIF_AZURE_APP_REQUIRED_ROLES=Ecosif.Api.Access

# Produção banco: preencher client id(s) do integrador; homolog pode ficar vazio
ECOSIF_AZURE_APP_ALLOWED_CLIENT_IDS=<appid-integrador>

# Default — não alterar salvo convenção ops
ECOSIF_AZURE_APP_LINK_PROVIDER=AZURE_ENTERPRISE_APP

Aplicar nos 6 serviços Java do compose: ecosif-auth, ecosif-masterdata, ecosif-moviments, ecosif-querys, ecosif-reports (+ auth para API admin).

Não reutilizar para app-only: ECOSIF_AUTH_PROVIDER, ECOSIF_AZURE_SCOPES, ECOSIF_AZURE_EXPECTED_AUDIENCE.

4.3 Ordem de deploy

  1. Flyway V0.7.00.15
  2. Publicar imagens 0.7.08.202608301
  3. Subir containers com vars acima (app-only ainda false se quiser smoke de regressão humano primeiro)
  4. Onboarding (§5)
  5. ECOSIF_ENABLE_AZURE_APP_ONLY=true
  6. Testes §7

5. Onboarding no eCosif

5.1 Usuário técnico

  1. Criar conta em gr_user (conta de serviço — username convencionado pelo cliente).
  2. Associar empresa/filial em gr_filial_usuario via masterdata (ACL contábil).

5.2 Vínculo app → usuário (recomendado — API)

Autentique com JWT ECOSIF (POST /api/auth/signin) e chame ecosif-auth:

curl -sS -X POST "${AUTH_BASE}/api/admin/b2b-app-links" \
  -H "Authorization: Bearer ${JWT_ECOSIF}" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "<service-principal-oid>",
    "userId": <gr_user.id>
  }'
Operação Método Path
Criar POST /api/admin/b2b-app-links
Listar GET /api/admin/b2b-app-links
Detalhe GET /api/admin/b2b-app-links/{id}
Por oid GET /api/admin/b2b-app-links/by-external-id/{oid}
Remover DELETE /api/admin/b2b-app-links/{id}

Documentação integrador: autenticacao.md (seção B2B).

5.3 Alternativa SQL (homolog)

Script comentado: seed-b2b-app-link-homolog.sql.

6. API Gateway

Seguir checklist_b2b_entra_app_only.md §3 e integracao_b2b_entra_app_only.md §10.

  • [ ] validate-jwt: iss, aud, assinatura — sem exigir scp
  • [ ] Allowlist appid/azp recomendada em produção
  • [ ] JWT ECOSIF (HS256) continua barrado nas rotas /ecosif-*

7. Validação pós-implantação

7.1 Regressão humano (obrigatório)

  • [ ] Login Azure Enterprise → APIs 200 (mesmo gateway)

7.2 App B2B

# Token app-only (§3)
curl -sS -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  "${GATEWAY}/ecosif-masterdata/actuator/health"
Caso Esperado
App vinculado + role OK 200 em endpoint piloto acordado
App sem vínculo 401 backend (AUTH_IDP_NOT_LINKED ou AUTH_UNAUTHORIZED)
aud/role inválidos 401 gateway ou backend
JWT ECOSIF no gateway 401 gateway

7.3 Logs (sem Bearer completo)

ecosif.auth.m2m outcome=success appId=… spOid=… userId=…
ecosif.auth.b2b_onboarding outcome=created linkId=…
ecosif.auth.m2m outcome=denied reason=no_identity_provider_link …

8. Offboarding

  1. DELETE /api/admin/b2b-app-links/{id} (ou remover SQL).
  2. Revogar secret/consent do app no Entra (lado cliente).
  3. Opcional: desativar usuário técnico em gr_user.

9. Troubleshooting

Sintoma Causa provável Ação
403 no gateway Policy exige scp ou allowlist Ajustar APIM/AWS; ver spike
401 + AUTH_IDP_NOT_LINKED Sem vínculo AZURE_ENTERPRISE_APP Onboarding §5
401 + log app_only_disabled Flag desligada ECOSIF_ENABLE_AZURE_APP_ONLY=true
401 role/client Vars ECOSIF_AZURE_APP_* Conferir jwt.ms vs env
403 pós-auth ACL empresa/filial gr_filial_usuario do usuário técnico
Humano quebrou Improvável se só B2B vars Confirmar ECOSIF_AUTH_PROVIDER humano intacto

10. Referências de implementação

Detalhamento técnico completo: auth14_entrega_tecnica_b2b_app_only.md.