AUTH-14 — Entrega técnica: B2B Entra app-only¶

Documento descritivo do que foi implementado no plano AUTH-14 (integração back-to-back com token de aplicação Entra).

Versão de referência: 0.7.08.202608301
Branch de desenvolvimento: feature/auth-14-entra-app-only-b2b
Status: desenvolvimento concluído (14.1–14.8); homolog E2E AUTH-14.9 pendente

1. Problema e solução¶

Problema¶

Cliente em AZURE_ENTERPRISE_GATEWAY obtém access token via client_credentials e recebia 403/401: o gateway validava JWT RS256, mas o backend só resolvia identidade humana (oid/sub → AZURE_ENTERPRISE em identity_provider_link).

Solução¶

Ramo app-only no starter: detecta token de aplicação, valida App roles/allowlist com vars exclusivas, resolve vínculo AZURE_ENTERPRISE_APP → usuário técnico, herda ACL empresa/filial. Onboarding explícito via API admin (sem JIT).

2. Escopo por atividade¶

ID	Entrega	Módulos	Status
14.1	Spike claims + matriz 403 gateway/backend	structure, starter	Concluído — spike
14.2	Provider `AZURE_ENTERPRISE_APP`, Flyway comments, doc BD	database, flyway-ecosif	Concluído
14.3	Starter: detector, validator, resolver app-only	starter-security	Concluído
14.4	Bump starter + `application.yml` app-only nas 5 APIs	auth, masterdata, moviments, querys, reports	Concluído (testes Maven OK)
14.5	API admin onboarding `/api/admin/b2b-app-links`	ecosif-auth	Concluído
14.6	Checklist ops Entra + gateway	structure	Concluído — checklist
14.7	Logs estruturados M2M	starter, auth	Concluído
14.8	Docs integradores + baseline + env	structure, auth	Concluído
14.9	Homolog E2E com cliente	QA	Pendente

Extensão AUTH-14.10 (Itaú STS — planejado)¶

Cliente Itaú: B2B via openid.itau.com.br (CC + scope), sem App role Entra. Documentação em auth14_10_entrega_tecnica_itau_sts_cc.md. Implementação starter pendente.

3. Artefatos de código¶

3.1 ecosif-database¶

Item	Caminho
Constante provider	`IdentityProviderCode.AZURE_ENTERPRISE_APP`

3.2 flyway-ecosif (meta-repo)¶

Item	Caminho
Migration comments	`sql/V0.7.00.15__identity_provider_link_b2b_app.sql`
Doc modelo	`docs/dev/identity_provider_link_b2b_app.md`
Seed homolog	`docs/dev/seed-b2b-app-link-homolog.sql`

3.3 ecosif-spring-boot-starter-security¶

Classe	Responsabilidade
`EcosifSecurityProperties.Azure.AppOnly`	Binding `ecosif.security.azure.app-only.*`
`AzureEntraAppOnlySupport`	Detecção, validação roles/client, lookup keys
`DefaultExternalIdentityUserResolver`	Ramo app-only separado do humano
`AzureEntraAppOnlyAuthAudit`	Logs `ecosif.auth.m2m outcome=…`

Testes: 48 no starter (incl. AzureEntraAppOnlySupportTest, AzureEntraAppOnlySpikeTest, AzureEntraAppOnlyAuthAuditTest, casos app-only no resolver).

3.4 ecosif-auth¶

Classe	Responsabilidade
`B2bAppLinkAdminController`	REST `/api/admin/b2b-app-links`
`B2bAppLinkAdminService`	CRUD vínculo B2B
`B2bAppLinkRequest` / `B2bAppLinkResponse`	Contrato API
`ConflictException`	409 duplicidade
`@Order` em `@ControllerAdvice`	Validação 400 vs catch-all 500

Testes: +16 (B2bAppLinkAdminServiceTest 9, B2bAppLinkAdminControllerTest 7) — total auth 76 testes.

3.5 APIs Java (5 serviços)¶

${ecosifSecurity} → 0.7.08.202608301
Bloco ecosif.security.azure.app-only em application.yml

3.6 ecosif-structure¶

env.template — vars ECOSIF_AZURE_APP_*
docker-compose.yml — repasse vars aos 6 serviços Java
Docs deploy/dev (índice atualizado)

4. Variáveis exclusivas app-only¶

Variável	Propósito
`ECOSIF_ENABLE_AZURE_APP_ONLY`	Liga ramo B2B (default `false`)
`ECOSIF_AZURE_APP_REQUIRED_ROLES`	CSV App roles Entra
`ECOSIF_AZURE_APP_ALLOWED_CLIENT_IDS`	Allowlist `appid`/`azp`
`ECOSIF_AZURE_APP_LINK_PROVIDER`	Default `AZURE_ENTERPRISE_APP`

Proibido misturar com login humano: ECOSIF_AUTH_PROVIDER, ECOSIF_AZURE_SCOPES, ECOSIF_AZURE_EXPECTED_AUDIENCE, external-login.

5. Fluxo runtime (pós-implantação)¶

Integrador → Entra STS (client_credentials)
          → Bearer app-only → Gateway (iss/aud/sig, sem scp)
          → API Java (starter revalida)
          → isAppOnlyToken? → validateAccess (roles, client id)
          → lookup AZURE_ENTERPRISE_APP (oid → appid → azp)
          → gr_user técnico → ACL empresa/filial → 200

Sem vínculo: 401 + log ecosif.auth.m2m outcome=denied reason=no_identity_provider_link.

6. Documentação oficial (índice)¶

Documento	Público
integracao_b2b_entra_app_only.md	Arquitetura / integradores
manual_implantacao_b2b_entra_app_only.md	Ops — implantação
checklist_b2b_entra_app_only.md	Ops — checklist
spike_auth14_claims_app_only.md	QA / diagnóstico
variaveis_autenticacao_baseline.md	Vars `ECOSIF_*`
autenticacao.md	API onboarding B2B
identity_provider_link_b2b_app.md	Modelo BD

7. Validação automatizada (2026-08-30)¶

Módulo	Testes Maven	Resultado
ecosif-database	5	PASS
ecosif-spring-boot-starter-security	48	PASS
ecosif-auth	76	PASS
ecosif-masterdata	11	PASS
ecosif-moviments	29	PASS
ecosif-querys	0 (compile)	PASS
ecosif-reports	6	PASS

8. Pendências¶

AUTH-14.9: homolog E2E com cliente (checklist §7 do manual)
AUTH-13.4: regressão humano Enterprise no mesmo gateway (executar junto do 14.9)
Payload jwt.ms real do cliente para confirmar hipótese 403 na borda
Publicação imagens Docker 0.7.08.202608301 nos ambientes alvo

9. Relação AUTH-13¶

Reutiliza BearerTokenResolver (13.1), ErrorResponse (13.3). Não usa JIT do converter humano. Bump starter unificado em 14.4 (substitui 13.7 parcial). AUTH-13.6 (ErrorResponse em docker-logs/logtail) entregue no mesmo branch após AUTH-14.

10. Commits da entrega (branch `feature/auth-14-entra-app-only-b2b`)¶

Módulo	SHA	Mensagem (resumo)
ecosif-database	`34926b0`	provider `AZURE_ENTERPRISE_APP`
ecosif-spring-boot-starter-security	`6eb6ae2`	ramo app-only + audit M2M
ecosif-auth	`067511c`	API `b2b-app-links` + starter
ecosif-auth	`2e3e7d2`	AUTH-13.6 ErrorResponse debug
ecosif-masterdata	`2c52969`	bump starter + YAML app-only
ecosif-moviments	`6bfec68`	idem
ecosif-querys	`fb71e10`	idem
ecosif-reports	`8582ce9`	idem
ecosif-structure	`a47acc0`	docs ops + entrega técnica
meta-repo (hub)	`086252f`	flyway V0.7.00.15 + ponteiros
meta-repo (hub)	`0ed8ce3`	ponteiro auth AUTH-13.6