Login com Microsoft (Azure) no modo híbrido — visão do produto¶

Este texto explica, em linguagem de negócio e operação, como o eCosif autentica pessoas com conta Microsoft (Azure / Entra ID) no modo híbrido, sem entrar em detalhes de engenharia.

Público: profissionais de negócio, produto e TI que precisam entender o fluxo e configurar o ambiente.

Documentação técnica relacionada: variaveis_autenticacao_baseline.md · gateway_hibrido_ecosif_azure.md

Em uma frase¶

O usuário entra com a conta Microsoft da empresa; o eCosif confere se o token da Microsoft é válido, identifica (ou cria) a pessoa no sistema e, nas próximas chamadas, usa o próprio token Microsoft nas APIs — enquanto quem entra com usuário e senha local continua usando o token interno do eCosif.

Dois jeitos de entrar (modo híbrido)¶

No mesmo ambiente podem coexistir:

Forma de login	Quem usa	O que “vale” depois do login
Local (usuário e senha do eCosif)	Integrações, operadores com conta local	Token interno do eCosif
Microsoft (botão Azure)	Colaboradores com conta corporativa	Token da Microsoft

A regra importante: a origem do login define o tipo de “crachá” da sessão. Quem entrou com Microsoft não troca para o token interno no meio do caminho, e vice-versa.

O que o eCosif lê no token da Microsoft¶

Quando a pessoa conclui o login Microsoft, o navegador envia ao eCosif um token (um “crachá digital” emitido pela Microsoft). O eCosif não inventa a identidade: ele lê e confere informações que já vêm nesse token.

Conferência de segurança (antes de confiar na pessoa)¶

O sistema verifica se o token:

foi emitido pela Microsoft do tenant (organização) configurado;
foi feito para esta aplicação eCosif (não para outro sistema);
ainda está dentro do prazo de validade;
tem assinatura válida (não foi adulterado).

Se algo falhar, o login é recusado.

Dados usados para reconhecer a pessoa¶

Informação no token	Para que serve no eCosif
Identificador único da conta Microsoft (`sub`)	Ligar a conta Microsoft ao usuário interno (vínculo permanente)
E-mail / nome de usuário preferido (`preferred_username`, `email` ou `upn`)	Nome de login no eCosif (quem é a pessoa na aplicação)
Nome de exibição (`name`)	Nome mostrado / gravado no cadastro
Grupos (`groups`), se existirem	Só entram se o ambiente estiver configurado para mapear grupos → perfil/tenant (opcional; não é o caso típico do primeiro uso)

Na prática, para um ambiente novo sem usuários e sem grupos cadastrados, o essencial é: identificador Microsoft + e-mail/nome de usuário + nome.

Cenário típico: base vazia ou colaborador que nunca acessou o sistema.

1. Pessoa clica em "Entrar com Microsoft"
2. Microsoft autentica (senha, MFA, etc. — fora do eCosif)
3. eCosif recebe o token e confere validade
4. eCosif não encontra a pessoa no cadastro
5. Se o auto-cadastro estiver ligado, cria o usuário com perfil padrão
6. Grava o vínculo: "esta conta Microsoft = este usuário eCosif"
7. Sessão fica marcada como login Microsoft
8. Daí em diante, as telas/APIs usam o token Microsoft como autorização

O que o negócio precisa saber

Sem auto-cadastro ligado, o primeiro login Microsoft falha (pessoa não encontrada).
O perfil inicial (ex.: papel STAFF e tenant padrão) vem das variáveis de ambiente, não de um cadastro manual prévio.
Grupos do Azure não são obrigatórios nesse modelo: com mapeamento de grupos desligado, qualquer conta Microsoft válida do tenant configurado pode ser provisionada com o perfil padrão.

Uso normal (pessoa já cadastrada / já vinculada)¶

1. Pessoa clica em "Entrar com Microsoft"
2. Microsoft autentica
3. eCosif confere o token
4. Localiza a pessoa pelo vínculo Microsoft ou pelo e-mail/usuário
5. Confere se a conta está ativa e dentro da validade
6. Sessão Microsoft; APIs usam o token Microsoft

Não cria usuário de novo. Apenas autentica e segue o trabalho.

Se a conta interna estiver inativa ou expirada, o acesso é negado mesmo com Microsoft ok.

Como o eCosif trata o token (visão simples)¶

Momento	O que acontece
No login Microsoft	O token serve para provar identidade e (se preciso) abrir o cadastro. O eCosif também emite um token interno para a sessão da tela, mas no modo híbrido as APIs de negócio passam a aceitar o token Microsoft nessa sessão.
Nas chamadas do dia a dia (após login Microsoft)	O front envia o token Microsoft nas requisições. Os serviços eCosif validam esse token (assinatura, organização, validade) e só então atendem.
Após login local	O front envia o token interno do eCosif. Os mesmos serviços aceitam esse formato também — por isso o modo se chama híbrido.

Resumo: o token Microsoft não é “só um login bonito”; no modo híbrido ele passa a ser a autorização usada enquanto a pessoa estiver nessa sessão Microsoft.

API Gateway com Lambda authorizer (requisito de alguns clientes)¶

Quando o tráfego passa por API Gateway e a Lambda authorizer é obrigatória em todas as rotas (incluindo login), o Angular envia tokens no POST /external-login assim:

Modo (`ECOSIF_AUTH_PROVIDER`)	Header `Authorization`	Body (`token` / `tokenType`)
`AZURE` (id_token)	Bearer id_token	id_token / `ID_TOKEN`
`AZURE_ENTERPRISE` (access_token com scopes)	Bearer access_token	id_token / `ID_TOKEN`

Nas APIs depois do login (masterdata, querys, reports, …) o front envia o mesmo tipo de Bearer: access_token MSAL com scopes de API. O Angular tenta renovar com acquireTokenSilent; se o silent falhar, reutiliza o access_token gravado na sessão no momento do login — assim o authorizer não recebe header vazio.

No ecosif-auth, o Resource Server ignora o Bearer em /api/auth/** (incluindo external-login e signin). A identidade do login vem do body (validação IdP + provisionamento em gr_user / identity_provider_link). O header Authorization continua sendo enviado para o API Gateway / Lambda authorizer; só o Spring Security do auth não o usa nessas rotas — assim o primeiro login não exige vínculo prévio.

No enterprise, o authorizer precisa ver scopes de API no access_token. Scopes só OIDC (openid profile email) fazem o Entra emitir access_token para o Microsoft Graph (aud 00000003-…) — a Lambda costuma barrar.

Checklist Entra (lado cliente):

App Registration: Expose an API → Application ID URI (ex. api://{client-id}) + scope (ex. access_as_user).
Manifest: "accessTokenAcceptedVersion": 2 (issuer login.microsoftonline.com/.../v2.0).
SPA: permissão/consent nesse scope.
Variáveis eCosif: ECOSIF_AUTH_PROVIDER=AZURE_ENTERPRISE, ECOSIF_API_TOKEN_MODE=HYBRID_ECOSIF_AZURE, ECOSIF_AZURE_SCOPES incluindo o scope api://…, ECOSIF_AZURE_API_AUDIENCE = audience real do access_token.
Authorizer AWS: regras alinhadas a esse aud / scp (não Graph).

Login local (/signin): não há token Microsoft. Se o authorizer exigir Bearer em todas as rotas de auth, o cliente precisa definir como o gateway trata o signin (ex.: outro mecanismo aceito pela Lambda, ou fluxo só Microsoft nesse ambiente).

Variáveis de configuração — o que são e como usar¶

Valores abaixo pensados para: modo híbrido + Azure simples + primeiro uso sem usuários/grupos no sistema.

Legenda — onde aplica

Sigla	Módulo	Papel
auth	`ecosif-auth`	Login, validação do token Microsoft no `external-login`, criação de usuário
angular	`ecosif-angular`	Tela de login, botão Microsoft (MSAL), escolha do token na sessão
APIs	masterdata, moviments, querys, reports (+ auth no modo híbrido)	Aceitam token eCosif e/ou Microsoft nas rotas de negócio

No .env do ecosif-structure as variáveis são compartilhadas; o Compose injeta cada uma só nos containers que precisam.

Variável	Onde aplica	O que faz	Como usar
`ECOSIF_API_TOKEN_MODE`	auth, angular, APIs	Define se as APIs aceitam só token eCosif, só Microsoft via gateway, ou os dois (híbrido).	Coloque `HYBRID_ECOSIF_AZURE` nos três (mesmo valor).
`ECOSIF_AUTH_PROVIDER`	auth, angular	Qual provedor externo o backend aceita; no front alinha o fluxo Microsoft.	`AZURE` (id_token) ou `AZURE_ENTERPRISE` (access_token + scope de API; authorizer com scopes).
`ECOSIF_ENABLE_AZURE_AUTH`	angular	Mostra ou esconde o botão Microsoft na tela.	`true`
`ECOSIF_ENABLE_LOCAL_AUTH`	angular	Mostra ou esconde o formulário usuário/senha.	`true` se ainda precisar de login local; `false` se só Microsoft.
`ECOSIF_ENABLE_RUNTIME`	angular	Faz o Angular ler a configuração do ambiente no container.	`true` em Docker/ECS.

Conta Microsoft (aplicação no Entra ID)¶

Variável	Onde aplica	O que faz	Como usar
`ECOSIF_AZURE_CLIENT_ID`	auth, angular	Identifica o aplicativo eCosif registrado na Microsoft.	ID do App Registration (SPA).
`ECOSIF_AZURE_TENANT_ID`	auth, angular, APIs	Identifica a organização (tenant) Microsoft.	ID do diretório Entra.
`ECOSIF_AZURE_AUTHORITY`	angular	Endereço de login Microsoft (MSAL no navegador).	`https://login.microsoftonline.com/<tenant-id>`
`ECOSIF_AZURE_SCOPES`	angular	O que o login Microsoft pede.	OIDC: `openid,profile,email`. Enterprise: inclua `api://<uri>/access_as_user` (ou o front acrescenta se `AZURE_ENTERPRISE`).
`ECOSIF_AZURE_EXPECTED_AUDIENCE`	auth	Confirma que o token foi emitido para este app (no `external-login`).	Pode ficar vazio (usa o Client ID).
`ECOSIF_AZURE_EXPECTED_ISSUER`	auth	Confirma o emissor do token (no `external-login`).	Pode ficar vazio (montado a partir do tenant).
`ECOSIF_AZURE_API_AUDIENCE`	auth, APIs	Audience de API (cenário enterprise / access token).	Deixe vazio no Azure simples; em `AZURE_ENTERPRISE` preencha com o `aud` do access_token (ex. `api://{client-id}`).

Variável	Onde aplica	O que faz	Como usar
`AUTH_TOKEN_SECRET`	auth, APIs (Angular herda via `ECOSIF_ANGULAR_AUTH_TOKEN`)	Chave compartilhada para emitir/validar o token interno.	Mesmo valor em auth e APIs. Segredo forte; não versionar.
`TOKEN_EXPIRATION`	auth, APIs, angular	Tempo de vida do token interno (milissegundos).	Ex.: `1800000` = 30 minutos.
`ECOSIF_JWT_SUBJECT_CLAIM`	auth, APIs	Como o token interno identifica a pessoa (`username` ou `userId`).	Em geral `username`.

Auto-cadastro (obrigatório se não houver usuários pré-cadastrados)¶

Variável	Onde aplica	O que faz	Como usar
`ECOSIF_AUTH_AUTO_PROVISION`	auth	Cria o usuário no primeiro login Microsoft.	`true` — sem isso, base vazia = login Microsoft falha.
`ECOSIF_AUTH_AUTO_PROVISION_GROUP`	auth	Com auto-provision, cria/associa grupo (`gr_grupo` / `gr_grupo_usuario`).	`false` por padrão. `true` clona `Administrators` se a role não existir.
`ECOSIF_AUTH_DEFAULT_TENANT`	auth	Tenant lógico inicial do usuário novo.	Ex.: `TEMP_TENANT`
`ECOSIF_AUTH_DEFAULT_ROLE`	auth	Papel inicial.	Ex.: `STAFF`
`ECOSIF_AUTH_DEFAULT_CREATED_BY`	auth	Marca a origem do cadastro.	Ex.: `AZURE_AD`
`ECOSIF_AUTH_DEFAULT_EXPIRY_TYPE`	auth	Tipo de política de validade da conta.	Em geral `A`
`ECOSIF_AUTH_DEFAULT_EXPIRY_YEARS`	auth	Validade da conta criada automaticamente (anos).	Ex.: `1`

Grupos / claims (manter desligado no primeiro uso sem grupos)¶

Variável	Onde aplica	O que faz	Como usar
`ECOSIF_AUTH_GROUP_MAPPING_ENABLED`	auth	Usa grupos Azure para decidir tenant/papel.	`false` se não há grupos mapeados.
`ECOSIF_AUTH_GROUP_MAPPING_REQUIRED`	auth	Exige grupo mapeado para criar usuário.	`false` — se `true` com base sem grupos, ninguém entra.
`ECOSIF_AUTH_CLAIM_MAPPING_ENABLED`	auth	Usa claims extras para tenant/papel.	`false` no início.
`ECOSIF_AUTH_CLAIM_MAPPING_REQUIRED`	auth	Exige claim mapeado para criar usuário.	`false` no início.
`ECOSIF_AUTH_GROUP_MAPPING_FILE` / `ECOSIF_AUTH_CLAIM_MAPPING_FILE`	auth	Arquivo de regras de mapeamento.	Vazio até existir política de grupos.

Variável	Onde aplica	O que faz	Como usar
`ECOSIF_AUTH_EXT_LOGIN_RL_EN`	auth	Liga limite de tentativas por IP no `external-login`.	`true` em produção.
`ECOSIF_AUTH_EXT_LOGIN_RL_MAX`	auth	Máximo de tentativas na janela.	Ex.: `30`
`ECOSIF_AUTH_EXT_LOGIN_RL_WIN`	auth	Janela em segundos.	Ex.: `60`

Bloco pronto para copiar (híbrido + Azure + base vazia)¶

ECOSIF_API_TOKEN_MODE=HYBRID_ECOSIF_AZURE
ECOSIF_AUTH_PROVIDER=AZURE
ECOSIF_ENABLE_AZURE_AUTH=true
ECOSIF_ENABLE_LOCAL_AUTH=true
ECOSIF_ENABLE_RUNTIME=true

ECOSIF_AZURE_CLIENT_ID=<app-registration-spa>
ECOSIF_AZURE_TENANT_ID=<tenant-id>
ECOSIF_AZURE_AUTHORITY=https://login.microsoftonline.com/<tenant-id>
ECOSIF_AZURE_SCOPES=openid,profile,email
ECOSIF_AZURE_EXPECTED_AUDIENCE=
ECOSIF_AZURE_EXPECTED_ISSUER=
ECOSIF_AZURE_API_AUDIENCE=

AUTH_TOKEN_SECRET=<mesmo-secret-em-todos-os-servicos>
TOKEN_EXPIRATION=1800000
ECOSIF_JWT_SUBJECT_CLAIM=username

ECOSIF_AUTH_AUTO_PROVISION=true
ECOSIF_AUTH_AUTO_PROVISION_GROUP=false
ECOSIF_AUTH_DEFAULT_TENANT=TEMP_TENANT
ECOSIF_AUTH_DEFAULT_ROLE=STAFF
ECOSIF_AUTH_DEFAULT_CREATED_BY=AZURE_AD
ECOSIF_AUTH_DEFAULT_EXPIRY_TYPE=A
ECOSIF_AUTH_DEFAULT_EXPIRY_YEARS=1

ECOSIF_AUTH_GROUP_MAPPING_ENABLED=false
ECOSIF_AUTH_GROUP_MAPPING_REQUIRED=false
ECOSIF_AUTH_CLAIM_MAPPING_ENABLED=false
ECOSIF_AUTH_CLAIM_MAPPING_REQUIRED=false

ECOSIF_AUTH_EXT_LOGIN_RL_EN=true
ECOSIF_AUTH_EXT_LOGIN_RL_MAX=30
ECOSIF_AUTH_EXT_LOGIN_RL_WIN=60

Perguntas frequentes¶

Preciso cadastrar o usuário antes no eCosif?
Não, se ECOSIF_AUTH_AUTO_PROVISION=true. No primeiro login Microsoft o sistema cria o cadastro com o perfil padrão.

Preciso cadastrar grupos no Azure para o login funcionar?
Não, no modelo descrito. Grupos só entram se o mapeamento estiver ligado e for obrigatório.

Login Microsoft e login local podem coexistir?
Sim. É exatamente o propósito do modo híbrido. Cada sessão usa um tipo de autorização, conforme a origem do login.

O e-mail do token precisa ser o mesmo “usuário” do eCosif?
Na criação automática, o eCosif usa o identificador de login vindo do token (em geral o e-mail / preferred username). Depois, o vínculo pela conta Microsoft (sub) é o que garante o reconhecimento nas próximas vezes.

Se o auto-cadastro estiver desligado?
Só entram pessoas já cadastradas (e, de preferência, já vinculadas à conta Microsoft). Em base vazia, o login Microsoft não completa.