Pular para conteúdo

Autenticação — guia para integradores

Documentação canônica: integradores/autenticacao.md · external-login-api.md

Contrato atual de login no ecosif-auth (MVP1 Modo A — JWT ECOSIF).

Endpoints

Método Rota Quando usar
POST /api/auth/signin Login local (usuário + senha). Usado por ecosif-automations e integrações server-to-server.
POST /api/auth/external-login Login Microsoft Entra, Azure Enterprise ou Google — envie o id_token do IdP.
POST /api/admin/users/remap Manutenção (Bearer autenticado): grupo de ECOSIF_AUTH_DEFAULT_ROLE, associa usuários sem grupo, limpa troca de senha dos usuários em identity_provider_link e estende validade/dtexpira em 90 dias.

Removidos (não usar)

Legado Substituição
POST /api/auth/signin-azure 404 — use POST /api/auth/external-login
POST /api/auth/signin com "azure": true 400 — use external-login
Fluxo oauth2Login server-side nos microsserviços Removido — login externo só via external-login + JWKS no ecosif-auth

external-login — request

{
  "provider": "AZURE",
  "token": "<id_token do Entra ID>",
  "tokenType": "ID_TOKEN"
}
provider Descrição
AZURE Contas Microsoft (Entra ID)
AZURE_ENTERPRISE Azure Enterprise (API scope)
GOOGLE Google Identity Services

signin local — request

{
  "username": "usuario@empresa.com",
  "password": "senha"
}

Não envie "azure": true — retorna 400.

Resposta (signin e external-login)

{
  "accessToken": "<JWT_ECOSIF>",
  "user": {
    "id": "1",
    "displayName": "Nome",
    "email": "user@empresa.com",
    "roles": ["STAFF"],
    "tenant": "TEMP_TENANT"
  },
  "tenantName": "TEMP_TENANT"
}

Use o JWT nas APIs: Authorization: Bearer <accessToken>.

O JWT é emitido e validado pelo ecosif-spring-boot-starter-security (io.ecosif.security.jwt.TokenProvider) nos microsserviços Java.

Erros (contrato)

Erros de autenticação e validação usam ErrorResponse (compatível com o legado success + message):

{
  "success": false,
  "message": "Usuário ou senha incorretos",
  "code": "AUTH_BAD_CREDENTIALS",
  "status": 401,
  "path": "/ecosif-auth/api/auth/signin",
  "timestamp": "2026-08-10T16:00:00Z"
}

Códigos estáveis: ver AuthErrorCodes (ex.: AUTH_IDP_NOT_LINKED, AUTH_EXTERNAL_TOKEN_INVALID). 401 do Resource Server (Bearer inválido / sem vínculo) também retorna esse JSON via RestAuthenticationEntryPoint.

Integração B2B — Entra app-only (AUTH-14)

Fluxo machine-to-machine para sistemas externos no perímetro Azure Enterprise + API Gateway. Não usa external-login, signin nem JWT ECOSIF nas APIs de negócio.

Aspecto Login humano (Modo B) B2B app-only
Obter token MSAL popup → id_token + access token client_credentials no Entra STS
Endpoint eCosif login POST /api/auth/external-login Nenhum
Bearer nas APIs Access token Microsoft (scp) Access token app-only (roles)
Vínculo BD identity_provider_link pessoa AZURE_ENTERPRISE_APP → usuário técnico

Fluxo do integrador

  1. Obter token: POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token com grant_type=client_credentials e scope=api://{api-id}/.default.
  2. Chamar APIs: Authorization: Bearer <access_token> em /ecosif-*.
  3. Onboarding (ops): usuário técnico + vínculo service principal + UserCompanyBranch — ver guia structure.

Onboarding via API (ops)

Autentique com JWT ECOSIF (POST /api/auth/signin) e cadastre o vínculo:

Método Path Descrição
POST /api/admin/b2b-app-links Cria vínculo AZURE_ENTERPRISE_APP → usuário técnico
GET /api/admin/b2b-app-links Lista vínculos (paginado)
GET /api/admin/b2b-app-links/{id} Detalhe
GET /api/admin/b2b-app-links/by-external-id/{oid} Lookup por oid do service principal
DELETE /api/admin/b2b-app-links/{id} Offboarding (remove vínculo)

Exemplo:

POST /api/admin/b2b-app-links
Authorization: Bearer <jwt-ecosif>

{
  "externalId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "userId": 42
}

ACL empresa/filial continua em gr_filial_usuario (masterdata) — o vínculo sozinho não concede escopo contábil.

Variáveis exclusivas (backend)

Não reutilizar ECOSIF_AUTH_PROVIDER, ECOSIF_AZURE_SCOPES nem ECOSIF_AZURE_EXPECTED_AUDIENCE para validar tokens app-only.

Variável Uso
ECOSIF_ENABLE_AZURE_APP_ONLY Liga ramo app-only no starter (default false)
ECOSIF_AZURE_APP_REQUIRED_ROLES App roles Entra exigidas
ECOSIF_AZURE_APP_ALLOWED_CLIENT_IDS Allowlist appid/azp
ECOSIF_AZURE_APP_LINK_PROVIDER Default AZURE_ENTERPRISE_APP

Compartilhadas com Modo B: ECOSIF_API_TOKEN_MODE=AZURE_ENTERPRISE_GATEWAY, ECOSIF_AZURE_TENANT_ID, ECOSIF_AZURE_API_AUDIENCE.

Guia completo (curl STS, gateway, checklist): integracao_b2b_entra_app_only.md (ecosif-structure).

Status: starter/database/API onboarding implementados (AUTH-14.2–14.5); homolog E2E pendente (AUTH-14.9).

Perfil Itaú STS — CC + scope (AUTH-14.10)

Cliente Itaú: integrador obtém token no STS openid.itau.com.br (flow=CC, claim scope). Não usa App role Entra. Login humano QW4 permanece somente Azure.

Aspecto Entra app-only (AUTH-14) Itaú STS CC (14.10)
STS login.microsoftonline.com openid.itau.com.br
Autorização token roles scope (mesmos nomes QW4)
Chave vínculo oid / appid SP sub (client id integrador)
aud api://… sub (contrato cliente)

Multi-serviço: o integrador chama diretamente masterdata, querys, moviments, etc. com o mesmo Bearer — sem passar pelo auth para obter token.

Onboarding: mesmo POST /api/admin/b2b-app-links com externalId = sub do token CC.

Guia: integracao_b2b_itau_sts_cc.md · checklist Terraform: checklist_vars_terraform_b2b_java.md.

Status: starter 0.7.08.202609021 + YAML nas 5 APIs (AUTH-14.10.2–14.10.4); homolog E2E pendente (AUTH-14.10.9).

Fluxo Angular (referência)

  1. MSAL/GIS obtém id_token no browser.
  2. Angular chama POST /api/auth/external-login (pode enviar Authorization: Bearer para API Gateway; o auth não autentica esse Bearer em /api/auth/** — identidade e provisionamento vêm do body).
  3. JWT ECOSIF é armazenado; no modo híbrido as APIs de negócio usam o token Microsoft sticky (após o vínculo em identity_provider_link).
  4. Com ECOSIF_AUTH_AUTO_PROVISION=true e ECOSIF_AUTH_AUTO_PROVISION_GROUP=true, o usuário é associado em gr_grupo_usuario ao grupo cujo nome é ECOSIF_AUTH_DEFAULT_ROLE (modelo da seed V0.6.00.3). Se esse grupo não existir, o auth clona Administrators (id 1). Role ADMIN reutiliza Administrators. Sem a segunda flag, o provisionamento só cria gr_user + identity_provider_link.

Documentação relacionada