| Data de elaboração | 20/05/2026 |
|---|---|
| Responsável pelo estudo | José Lucas da Silva Costa (Analista) |
| Equipe do estudo |
|
| Alvo | Alpha |
| Origem | Carta de Serviços e Alpha Solicitações |
| Objetivo | Investigar a viabilidade técnica de desacoplar as regras de autorização e gerenciamento de permissões do SAURON/Meu Acesso e da API de Servidores, avaliando a utilização do SPA como solução centralizadora de escopos e permissões. |
| Documentação correlata (opcional) |
https://alphasolicitacoesapi.production.local/index.html https://wiki.setic.ro.gov.br/pt-br/home/spaces/code/gc/padroes |
| Observações | Nenhuma |
Este estudo tem por objeto verificar se é viável usar o SPA como ponto central de permissões e escopos nos sistemas Alpha Carta de Serviços e Alpha Solicitações, de modo a reduzir a dependência direta que esses sistemas mantêm com o SAURON/Meu Acesso.
Os sistemas Alpha dependem do SAURON de duas formas distintas: para autenticar usuários via OIDC, e para saber o que cada usuário pode fazer, seja lendo claims do token, seja chamando a API do SAURON diretamente. Essa dupla dependência gera amarras que travam:
a) evoluir o modelo de permissões sem mexer no autenticador
b) adotar novos autenticadores no futuro, como o GOV.BR
c) tratar usuários internos e externos de forma unificada
d) manter consistência, hoje cada sistema verifica escopos do seu próprio jeito
a) Mapear o que cada sistema Alpha depende do SAURON hoje
b) Verificar se o SPA, no estado em que está, dá conta de centralizar as permissões
c) Identificar o que precisaria mudar nos sistemas Alpha
c) Levantar as histórias de usuário para subsidiar a implementação
a) Alpha Carta de Serviços Web: frontend ASP.NET MVC para gerenciamento interno do catálogo de serviços
b) Alpha Carta de Serviços API: backend do Alpha Carta de Serviços, API REST ASP.NET
c) Alpha Solicitações Web: frontend ASP.NET MVC para gestão de solicitações
d) Alpha Solicitações API: backend do Alpha Solicitações, API REST ASP.NET
e) SPA (Sistema de Permissão e Autenticação): sistema NestJS com três microsserviços (usuario, perfil, escopo)
f) SAURON / Meu Acesso: provedor de identidade e autorização, acessado via OIDC para autenticação e via API REST para consultas de perfis
O SPA é uma API REST que gerencia escopos e permissões. Dado um pessoaId, ele devolve os escopos ativos daquele usuário. O endpoint que os sistemas Alpha já consomem é:
GET /pessoas/{pessoaId}/escoposSPA — apps/escopo/src/main.ts (Swagger configurado em addServer)
Observação: O SPA não autentica ninguém e não emite token. Ele entra em cena depois do login, para dizer o que aquele usuário pode fazer. Um detalhe importante: os sistemas Alpha já consultam o SPA, mas só para uma parte das permissões. O CDS.API e o GCS.Web já fazem chamadas ao SPA para escopos de RH, mas seguem dependendo do SAURON para os demais perfis. O problema, portanto, não é falta de integração é integração incompleta.
❯ Quais responsabilidades atualmente dependem do SAURON/Meu Acesso e da API de Servidores?
A autenticação aponta para o SAURON via OIDC. O CPF, o nome e o id do usuário são lidos diretamente dos claims do token dentro do UserServiceRepository:
var cpf = httpContextAccessor.HttpContext.User.Claims
.FirstOrDefault(c => c.Type.Equals("movimentacao@Cpf"));
var nome = httpContextAccessor.HttpContext.User.Claims
.FirstOrDefault(c => c.Type == "movimentacao@Nome");
var id = httpContextAccessor.HttpContext.User.Claims
.FirstOrDefault(c => c.Type.Equals("sub"));GCS.Web — Models/Repositories/UserServiceRepository.cs
Os perfis de acesso também chegam do SAURON como claims do tipo "Perfil". A verificação é feita diretamente sobre esses claims, sem nenhuma abstração intermediária:
httpContextAccessor.HttpContext.User.Claims
.Any(c => c.Type.Equals(ControleDePerfil.Perfil)
&& c.Value.Equals("GestorDeServicos@Gcs"))GCS.Web — Models/Repositories/UserServiceRepository.cs (VerificaSeOServidorPossuiPerfilGestorDeServicos)
O mesmo vale para "Administrador@Gcs", "Atendente@Gcs" e "ChefeImediato@Gcs". Esses perfis controlam o acesso a controllers inteiros como CartaDeServicosController e AgendamentoController, que exigem a policy "GestorDeServicosEAdministrador":
[Authorize(Policy = "GestorDeServicosEAdministrador")]
public class CartaDeServicosController : ControllerGCS.Web — Controllers/CartaDeServicosController.cs
Além dos claims do token, o GCS.Web vai direto à API do SAURON via SauronRepository para buscar a lista de atendentes, usando login e senha próprios:
var rest = $"api/usuario/BuscarPerfisDoUsuarioPorDescricaoESistema/" + perfilAtendente + "/" + ClienteId;
var request = new RestRequest(rest, Method.Post);GCS.Web — Models/Repositories/SauronRepository.cs (ObterListaDeAtendentes)
O CDS.API também vai direto ao SAURON via SauronApiRepository para buscar dados de usuário por CPF. A autenticação é feita com login e senha próprios via api/Autenticacao:
var rest = $"api/Usuario/BuscarPorCpf/" + cpf;
var request = new RestRequest(rest, Method.Post);
request.AddHeaders(headers); // Bearer token obtido do SAURONCDS.API — Repositories/SauronApiRepository.cs (ObterUsuarioPorCpf)
A autenticação é configurada em AuthenticationExtensions.AddSauronAuthentication, apontando para o SAURON via OIDC. O padrão de consulta de escopos é o mesmo do GCS.Web que usa o ApiEscopo para consultar o SPA.
services.AddOpenIdConnect("oidc", options =>
{
options.Authority = configuration["UrlDeAutenticacao"];
options.ClientId = configuration["ClientId"];
});AlphaSolicitacoesWeb — Extensions/AuthenticationExtensions.cs
❯ Como as regras de escopo e permissões são definidas atualmente nos sistemas Alpha?
Os sistemas Alpha definem permissões de dois jeitos diferentes, que coexistem sem nenhuma unificação:
Perfis como GestorDeServicos@Gcs, Administrador@Gcs, Atendente@Gcs e ChefeImediato@Gcs chegam como claims do token do SAURON e são lidos diretamente no UserServiceRepository. São esses perfis que definem o que o usuário pode ou não acessar.
Para permissões mais específicas como RH Setorial e RH SEGEP, os sistemas já consultam o SPA via ApiEscopo. O fluxo é direto: busca o pessoaId do usuário na API de usuários e depois consulta os escopos no SPA filtrando por perfilId:
public EscopoDto ObterEscopoPerfilDeRHSetorial(int? usuarioId)
{
RestResponse response = ConsultarEscopoPorUsuarioId(usuarioId);
// filtra por perfilRHSetorialEscopoId
}
private RestResponse ConsultarEscopoPorUsuarioId(int? usuarioId)
{
var rest = $"/pessoas/{usuarioId}/escopos";
}GCS.Web — Models/Repositories/ApiEscopo.cs (ObterEscopoPerfilDeRHSetorial / ConsultarEscopoPorUsuarioId)
O CDS.API faz o mesmo em ApiUsuarioExterno.ObterUnidadeOrganizacionalExterno, consultando /pessoas/{usuarioId}/escopos e filtrando pelo IdPerfilGestor. Ou seja: o SPA já é consultado, só que para uma fração das permissões. O restante ainda vem do SAURON por claims.
Os dois mecanismos convivem sem integração. O acesso a um controller inteiro é decidido por claims do SAURON; permissões mais finas são decididas pelo SPA. Não existe um contrato único, cada sistema resolve isso do seu jeito, o que torna qualquer mudança mais arriscada do que deveria ser.
❯ Quais dependências técnicas existem entre autenticação, autorização e dados funcionais de servidores?
a) Autenticação via SAURON (OIDC): os sistemas Alpha apontam para o SAURON como provedor de login. O token gerado carrega claims de identidade (sub, movimentacao@Cpf, movimentacao@Nome) e de perfil. Trocar o provedor significa rever todos os pontos do código que dependem desses claims e são muitos.
b) Autorização via claims do token: o UserServiceRepository verifica perfis nos claims do token SAURON (tipo "Perfil", valores como "GestorDeServicos@Gcs"). Sem nenhuma abstração, o nome do perfil, que é um detalhe interno do SAURON, está exposto diretamente no código de autorização.
c) Consultas diretas à API do SAURON: o SauronRepository no GCS.Web e o SauronApiRepository no CDS.API chamam o SAURON de forma síncrona com credenciais próprias. Se o SAURON cair, essas funcionalidades param junto.
d) Consulta ao SPA (parcial): o ApiEscopo em ambos os sistemas já bate no SPA em /pessoas/{pessoaId}/escopos, mas só para perfis de RH. Tudo o mais continua no SAURON.
❯ Como o SPA poderia centralizar regras de permissões e escopos?
O SPA já tem o que precisa e já é consultado pelos sistemas Alpha, o problema é que essa consulta cobre só uma parte. A proposta é ampliar o que já existe:
a) Todos os perfis hoje verificados nos claims do SAURON (GestorDeServicos, Administrador, Atendente, ChefeImediato) passam a ser representados como escopos no SPA, cada um com seu perfilId.
b) Após o login via SAURON, os sistemas Alpha consultam GET /pessoas/{pessoaId}/escopos no SPA e baseiam todas as decisões de acesso no que vier dali.
c) O ApiEscopo que já existe nos dois sistemas, passa a ser a única fonte de permissões, acabando com as verificações espalhadas nos claims do token.
Há um ponto que precisa ser resolvido antes de qualquer coisa: o SPA identifica usuários por pessoaId, não por CPF nem pelo claim sub do SAURON. Enquanto não existir um mapeamento claro entre o token do SAURON e o pessoaId do SPA, a consulta de escopos não tem como funcionar. Isso é pré-requisito.
❯ Quais impactos arquiteturais existiriam no desacoplamento?
O UserServiceRepository precisa mudar: os métodos VerificaSeOServidorPossuiPerfilGestorDeServicos, VerificaSeOServidorPossuiPerfilAdministrador, VerificaSeOServidorPossuiPerfilAtendente e VerificarSeOServidorPossuiPerfilChefeImediato param de ler claims do token e passam a consultar os escopos do SPA.
As policies dos controllers como "GestorDeServicosEAdministrador" precisam ser redesenhadas para operar com base nos escopos do SPA, não em claims do SAURON.
A consulta que hoje vai ao SAURON via SauronRepository.ObterListaDeAtendentes pode ser substituída por uma chamada ao SPA filtrada pelo perfilId do perfil de atendente.
A consulta que hoje vai ao SAURON via SauronApiRepository.ObterUsuarioPorCpf pode ser substituída pela API de usuários do SPA (/usuarios?cpf={cpf}), que o próprio ApiUsuarioExterno.ObterPessoaExterno já usa. Esse ponto de dependência com o SAURON seria eliminado.
O ApiEscopo já está implementado e segue o mesmo padrão do GCS.Web. O caminho é o mesmo: ampliar as consultas ao SPA para cobrir os perfis que hoje dependem de claims do SAURON.
Um pontos de atenção a ser considerar é o mapeamento entre o token do SAURON e o pessoaId do SPA que não existe de forma padronizada, sem isso, não há como consultar os escopos do usuário correto.
❯ Como permitir futura flexibilidade para troca de autenticador sem impacto nas regras de autorização?
A chave aqui é separar autenticação de autorização. Se os sistemas Alpha passarem a tomar decisões de acesso com base nos escopos do SPA e não em claims específicos do SAURON como movimentacao@Cpf ou Perfil, trocar o autenticador deixa de ser um problema de autorização. Vira só uma questão de login.
O código deixa isso claro: o claim movimentacao@Cpf é um detalhe do SAURON. Se o provedor mudar, esse claim muda, e tudo que depende dele precisa ser alterado. Com o SPA como fonte de escopos, basta que o novo autenticador entregue um identificador que se mapeie para um pessoaId, o restante do fluxo não precisa mudar.
❯ Separação entre autenticação e autorização
A autenticação fica onde está, no SAURON via OIDC. O que muda é a autorização: após o login, os sistemas consultam o SPA para saber o que o usuário pode fazer. As verificações que hoje dependem de claims do token passam a depender dos escopos do SPA, que já tem a estrutura para isso.
❯ Centralização de permissões e escopos utilizando o SPA
O ApiEscopo já existe nos dois sistemas e já consulta GET /pessoas/{pessoaId}/escopos. Centralizar permissões significa ampliar essa consulta para cobrir todos os perfis, não só os de RH e acabar com as verificações paralelas nos claims do SAURON. A estrutura do SPA (UsuarioEscopo com perfilId, unidadeId, departamentoId, instituicaoId) já comporta essa expansão.
❯ Unificação do modelo de usuários internos e externos
O SPA não faz distinção entre usuário interno e externo, a entidade Usuario guarda pessoaId e email, sem campo de tipo. Quem define o que o usuário pode fazer é o escopo atribuído, não de onde ele veio. Isso abre caminho para que servidores públicos e cidadãos que exercem a mesma função recebam o mesmo perfil, independentemente do autenticador.
❯ Redução de dependências diretas com a API de Servidores
Com os escopos no SPA, as chamadas diretas ao SAURON fora do fluxo de autenticação como SauronRepository.ObterListaDeAtendentes e SauronApiRepository.ObterUsuarioPorCpf podem ser removidas. O SPA já tem APIs de usuário (/usuarios?filter[cpf]={cpf}) e de escopos que substituem essas chamadas.
a) O mapeamento entre o token do SAURON e o pessoaId do SPA não existe de forma padronizada, é o principal bloqueio antes de qualquer implementação.
b) Os perfis hoje verificados nos claims do SAURON (GestorDeServicos@Gcs, etc.) precisam estar cadastrados no SPA com perfilId correspondentes. Sem esse cadastro, a consulta ao SPA não devolve nada útil.
c) A consulta ao SPA adiciona uma chamada de rede no fluxo de autorização. É preciso definir cache nos sistemas consumidores para não penalizar a latência.
d) Parte das consultas ao SAURON pode servir a regras de negócio além da autorização. Separar os dois casos exige atenção para não quebrar o que já funciona.
As histórias abaixo representam as mudanças necessárias nos sistemas Alpha para que o SPA assuma o papel de centralizador de permissões. Este estudo não entra em implementação, as histórias servem de insumo para o planejamento das sprints:
Por quê?
Hoje os perfis do usuário chegam como claims do token do SAURON e são verificados diretamente no código. Qualquer mudança no SAURON quebra a autorização. Concentrando essa verificação no SPA, o sistema fica independente dos detalhes do provedor de autenticação.
Regras e Validações
Cenários
Cenário 1 - Usuário com perfil GestorDeServicos acessa o sistema
Dado que o usuário autenticou via SAURON
E possui escopo com perfilId de GestorDeServicos cadastrado no SPA
Quando o sistema verifica as permissões do usuário
Então deve consultar a rota de escopos no SPA
E conceder acesso normalmente
Por quê?
O Alpha Solicitações segue o mesmo padrão do Alpha Carta de Serviços: perfis do usuário verificados diretamente nos claims do token do SAURON. Centralizar essa verificação no SPA garante consistência entre os sistemas e desacopla a autorização do provedor de autenticação.
Regras e Validações
Cenários
Cenário 1 - Usuário com perfil Atendente acessa o sistema
Dado que o usuário autenticou via SAURON
E possui escopo com perfilId de Atendente cadastrado no SPA
Quando o sistema verifica as permissões do usuário
Então deve consultar a rota de escopos no SPA
E conceder acesso normalmente
Cenário 2 - Busca de lista de atendentes
Dado que o sistema precisa listar os atendentes disponíveis
Quando a busca de atendentes é acionada
Então deve consultar a rota de escopos no SPA filtrada pelo perfilId de atendente
E não deve realizar nenhuma chamada direta à API do SAURON
A proposta é tecnicamente viável. A análise do código mostra que os sistemas Alpha já consultam o SPA, o ApiEscopo existe nos dois e já faz chamadas ao endpoint para buscar escopos. O problema não é falta de integração, é integração incompleta: parte das permissões vem do SPA, parte vem dos claims do SAURON, e as duas lógicas convivem sem nenhuma unificação.
O que precisa mudar está nos sistemas Alpha: ampliar as consultas ao SPA para cobrir todos os perfis e retirar as verificações diretas nos claims do SAURON. O SPA já tem o que é necessário: perfilId, dimensões organizacionais e o endpoint de escopos por pessoa.
O pré-requisito que antecede qualquer implementação é o mapeamento entre o token do SAURON e o pessoaId do SPA. Sem isso resolvido, os sistemas Alpha não conseguem consultar os escopos do usuário correto.