Integração B2B — Itaú STS (Client Credentials + scope)¶

Extensão do plano AUTH-14 para o perfil M2M Itaú: token emitido pelo STS interno (openid.itau.com.br) com flow=CC e claim scope, sem App role Entra.

PLANID: AUTH-14.10
Status: planejado (documentação + escopo fechado com cliente; implementação pendente)
Base: integracao_b2b_entra_app_only.md (perfil Microsoft roles)
Relacionado: checklist_b2b_itau_sts_cc.md · checklist_vars_terraform_b2b_java.md · spike

1. Resumo executivo¶

Pergunta	Resposta
Dois modelos convivem?	Sim. Humano = Azure (`login.microsoftonline.com`). Integrador = Itaú STS (`openid.itau.com.br`).
Integrador passa pelo auth?	Não. Um token STS → chama qualquer API Java (`masterdata`, `querys`, …) direto.
O que muda vs AUTH-14 Entra?	Autorização por `scope` (não `roles`); issuer/JWKS Itaú; sem `aud` (M2M via `sub` + scope); lookup B2B por `sub` (client id).
O que permanece igual?	`b2b-app-links`, provider `AZURE_ENTERPRISE_APP`, usuário técnico, ACL `empresa`/`filial`, starter nas 5 APIs.

2. Perfis de token no mesmo perímetro¶

┌─────────────────────┐   MSAL / Entra          ┌──────────────────────────┐
│ SPA QW4 (humano)    │ ─────────────────────►│ login.microsoftonline.com │
└──────────┬──────────┘   scp delegated        └────────────┬─────────────┘
           │                                                  │
           │ Bearer JWT Entra                                 │
           ▼                                                  │
┌─────────────────────┐   CC + scope            ┌────────────▼─────────────┐
│ Lambda / integrador │ ───────────────────────►│ openid.itau.com.br       │
└──────────┬──────────┘   flow=CC, usr=null     └────────────┬─────────────┘
           │                                                  │
           └──────────────────────┬───────────────────────────┘
                                  │ API Gateway (valida scope)
                                  ▼
                         5 microsserviços Java + starter
                                  │
                    ┌─────────────┴─────────────┐
                    ▼                           ▼
            AZURE_ENTERPRISE              AZURE_ENTERPRISE_APP
            oid/sub → pessoa              sub → usuário técnico

Perfil	Issuer	Detecção	Autorização	Vínculo BD
Humano QW4	`login.microsoftonline.com/.../v2.0`	`scp` / usuário	Scopes delegated	`AZURE_ENTERPRISE` + `oid`/`sub`
M2M Itaú CC	`https://openid.itau.com.br/api/oauth/token`	`flow=CC`, `usr=null`	Claim `scope` (mesmos nomes QW4)	`AZURE_ENTERPRISE_APP` + `sub`
M2M Entra (opcional/futuro)	Microsoft	`roles` / `idtyp=app`	App roles	`AZURE_ENTERPRISE_APP` + `oid`/`appid`

3. Contrato de claims — token Itaú CC (referência cliente DEV)¶

Payload informado pelo cliente (valores de exemplo):

{
  "iss": "https://openid.itau.com.br/api/oauth/token",
  "sub": "e19c3d92-3603-4a89-923a-1a4bba633591",
  "exp": 1788290226,
  "iat": 1788286626,
  "Access_Token": "2aa3fe95.0d7e7bba-19f9-4017-970b-205406e5442c",
  "usr": "null",
  "flow": "CC",
  "source": "INT",
  "site": "ctmm1",
  "env": "D",
  "mbi": "true",
  "aut": "",
  "scope": "appid-42e02f44-8897-4513-978b-3ce788b41e27 qw4-balancetes-fundos-investimentos.read resource.READ"
}

Claim	Uso eCosif (alvo AUTH-14.10)
`iss`	Identificar perfil Itaú; JWKS dedicado
`sub`	Client id do chamador (lambda DEV fixa); chave de `b2b-app-links`; allowlist
`aud`	Não presente no token CC do emissor Itaú — backend com `ECOSIF_ITAU_STS_AUDIENCE_MODE=NONE`
`exp` / `iat`	Validade
`flow`	`CC` → classificar M2M
`usr`	`"null"` → sem usuário humano
`scope`	CSV espaços: validar scopes exigidos (`qw4-balancetes-fundos-investimentos.read`, …)
`appid-{guid}` no scope	Opcional: validar app id da API (confirmar com cliente)
`Access_Token`	Metadado Itaú — não usar como chave de vínculo

Scopes de negócio: mesmos nomes do humano (qw4-balancetes-fundos-investimentos.read / .write).

4. Runtime — cada request integrador¶

Integrador obtém token no STS Itaú (client_credentials — procedimento interno Itaú).
Chama diretamente /ecosif-masterdata/..., /ecosif-querys/..., etc., com Authorization: Bearer <jwt>.
Gateway: valida assinatura, issuer Itaú, scope exigido.
Backend (starter):
Revalida JWT (multi-issuer: Microsoft + Itaú).
Classifica perfil Itaú CC.
Valida scopes + allowlist sub.
Resolve identity_provider_link (AZURE_ENTERPRISE_APP, sub) → gr_user técnico.
Aplica ACL empresa/filial.

Proibido: integrador chamar /api/auth/signin ou external-login para obter JWT ECOSIF.

5. Onboarding (uma vez por integrador/ambiente)¶

Caminho oficial — UI Angular¶

Login como ADMIN no eCosif.
Menu Ferramentas Administrativas → Integradores B2B (/integrators).
Informar o external id = sub do token CC Itaú (client id).
Escolher:
Usuário existente — select do usuário técnico; ou
Criar usuário técnico — username (ex.: b2b-<integrador>), nome, senha e empresas (ACL).
Salvar. A UI chama POST /usersettings (se novo) e em seguida POST /api/admin/b2b-app-links.
Ligar ECOSIF_ENABLE_AZURE_APP_ONLY=true nas 5 APIs após smoke.

Offboard: na mesma tela, ícone de excluir no vínculo.

Alternativa — API / SQL (ops)¶

One-shot (criar técnico + vínculo):

POST /api/admin/b2b-app-links/provision
Authorization: Bearer <JWT ADMIN>
Content-Type: application/json

{
  "externalId": "e19c3d92-3603-4a89-923a-1a4bba633591",
  "username": "b2b-itau-dev",
  "name": "Integrador B2B Itaú",
  "password": "ChangeMeB2b!"
}

Só vínculo (usuário já existe):

POST /api/admin/b2b-app-links
Authorization: Bearer <JWT ADMIN>
Content-Type: application/json

{
  "externalId": "e19c3d92-3603-4a89-923a-1a4bba633591",
  "userId": 42
}

externalId = sub do token CC. Endpoints exigem authority ADMIN. ACL gr_filial_usuario continua obrigatória (UI ou SQL).

Seed SQL homolog (fallback sem API): seed-b2b-app-link-homolog.sql.

6. Variáveis exclusivas M2M (AUTH-14 + extensão 14.10)¶

Ver matriz completa: checklist_vars_terraform_b2b_java.md e variaveis_autenticacao_baseline.md.

Variável	Perfil Itaú CC
`ECOSIF_ENABLE_AZURE_APP_ONLY`	`true` após onboarding
`ECOSIF_AZURE_APP_LINK_PROVIDER`	`AZURE_ENTERPRISE_APP`
`ECOSIF_AZURE_APP_REQUIRED_SCOPES`	`qw4-balancetes-fundos-investimentos.read` (nova — AUTH-14.10)
`ECOSIF_AZURE_APP_REQUIRED_ROLES`	vazio (sem App role Entra)
`ECOSIF_AZURE_APP_ALLOWED_CLIENT_IDS`	`sub` da lambda/integrador por ambiente
`ECOSIF_ITAU_STS_ISSUER`	`https://openid.itau.com.br/api/oauth/token` (nova)
`ECOSIF_ITAU_STS_JWKS_URI`	Confirmar com cliente (nova)
`ECOSIF_ITAU_STS_AUDIENCE_MODE`	`NONE` (default — emissor não envia `aud`)

Humano (inalterado): ECOSIF_AUTH_PROVIDER=AZURE_ENTERPRISE, ECOSIF_AZURE_SCOPES, issuer Microsoft.

7. Gateway (responsabilidade cliente Itaú)¶

[ ] Authorizer aceita issuer openid.itau.com.br além de Microsoft (humano).
[ ] Policy M2M valida claim scope (não exige scp Entra).
[ ] Scopes exigidos alinhados ao QW4.
[ ] Humano continua com token Microsoft + scp.
[ ] JWT ECOSIF (HS256) rejeitado em /ecosif-*.

8. Homologação (AUTH-14.10.9)¶

#	Cenário	Esperado
1	Humano MSAL → API	200
2	CC Itaú + scope + vínculo + ACL	200 em masterdata e querys (mesmo token)
3	CC sem scope exigido	403 gateway ou 401 backend
4	CC sem vínculo `b2b-app-links`	401 backend
5	CC com `sub` fora da allowlist	401 backend
6	CC sem chamar auth antes	200 direto na API de negócio

9. Pendências do cliente¶

Item	Status
URL JWKS do `openid.itau.com.br`	Pendente
`sub` em PROD (vs lambda DEV)	Pendente
Validar também `appid-{guid}` no scope?	Confirmar
Scope `resource.READ` — obrigatório?	Confirmar

10. Referências¶

Documento	Conteúdo
integracao_b2b_entra_app_only.md	Perfil Entra `roles` (AUTH-14)
manual_implantacao_b2b_itau_sts_cc.md	Runbook implantação Itaú
auth14_10_entrega_tecnica_itau_sts_cc.md	Escopo de implementação
spike_auth14_10_itau_sts_claims.md	Respostas cliente + matriz claims