Resolução de problemas, localização de ficheiros e documentos relacionados com a integração de Access Management.
6. Resolução de problemas
| Sintoma | Causa provável | Onde procurar |
|---|---|---|
PermissionsRegistry não gerado | Processador de anotações em falta em annotationProcessorPaths | pom.xml — secção 2.4 do Permissions Integration Guide |
[Authorization Sync] Failed… em todos os arranques | Credenciais M2M erradas / em falta no backend | Ambiente do backend: igrp.access.m2m.client-id, igrp.access.m2m.client-secret |
[startup-sync] failed em todos os arranques da SPA | O mesmo, mas no frontend | Ambiente do frontend: IGRP_SERVICE_ID, IGRP_M2M_CLIENT_ID, IGRP_M2M_CLIENT_SECRET, IGRP_ACCESS_MANAGEMENT_API. O framework apresenta isto como IgrpConfigError(IGRP_ACCESS_MANAGEMENT_CONFIG_MISSING) em global-error.tsx. |
Ciclo de login com uma cadeia ?callbackUrl=…?callbackUrl=… cada vez maior na barra de endereço | NEXTAUTH_URL não inclui /api/auth (e/ou NEXT_PUBLIC_BASE_PATH quando definido). O NextAuth v4 não acrescenta automaticamente. | Corrija NEXTAUTH_URL segundo as regras do ponto 4.2. Reinicie o pod da SPA (os cookies delimitados ao caminho errado mantêm-se até expirarem — limpe os cookies do browser para o domínio para desbloquear a sessão de desenvolvimento). |
PKCE_ERROR ou OAUTH_CALLBACK_ERROR no callback | NEXTAUTH_SECRET mudou a meio do fluxo entre /authorize e /callback, OU o caminho do proxy mudou | Confirme que o segredo é estável entre pods, que NEXTAUTH_URL corresponde à origem da SPA onde o browser iniciou o fluxo, e que os cookies do caminho de callback estão de facto a ser enviados (problemas de SameSite / cross-origin). |
O framework lança um erro no arranque em produção: "NEXTAUTH_SECRET must be set" | É exatamente o que diz — o NextAuth falha de forma irrecuperável em produção quando NEXTAUTH_SECRET não está definido | Defina-o. Gere com openssl rand -base64 32. |
Pedido do scope email mas o token não inclui a claim | Scope não registado no cliente do AM (o valor por omissão do framework para scopes_supported é apenas ["openid"]) | Adicione email ao scopes do cliente no AM, e confirme IGRP_AUTH_SCOPES=openid email na SPA. |
| 403 numa página mesmo com o utilizador a ter o perfil correto | igrpAssertAuthorize foi chamado com um nome de permissão simples, mas o JWT não tem claim org (fail-closed) | Confirme que o departamento ativo do utilizador está definido. Use a forma totalmente qualificada "DEPT_X.suffix" ao chamar fora do contexto de departamento atual do utilizador. |
| Componente com controlo de permissão continua a renderizar-se após a remoção de um perfil | O controlo por claim do token fica em cache até o TTL do token expirar — ver ponto 3.6 "Latência de revogação" | Aguarde pelo ciclo de renovação, ou force um novo login. A revogação em tempo real tem de ser aplicada na camada de API, não na UI. |
| A UI em modo de pré-visualização funciona mas a produção não | O modo de pré-visualização concede superadministrador — todos os controlos passam silenciosamente | Teste com IGRP_PREVIEW_MODE=false + AUTH_PROVIDER=igrp-auth contra um AM real com um utilizador que não seja superadministrador, antes de lançar. |
| A barra lateral da SPA aparece vazia | O utilizador não tem perfil ativo, OU o perfil não tem itens de menu | AC → Users → confirme o perfil ativo; AC → Menus → confirme roles[] nos itens de menu |
A API devolve 401 em todos os pedidos | Incompatibilidade do iss do JWT — o issuer-uri do resource server não é igual ao IGRP_OAUTH_ISSUER do AM | Compare a claim iss do payload do JWT com o spring.security.oauth2.resourceserver.jwt.issuer-uri do backend da aplicação, ao carácter |
A API devolve 403 apesar de o perfil ter a permissão | JWT desatualizado; JWT sem a permissão; ou erro de escrita no @PreAuthorize | Descodifique o bearer, verifique o array permissions; confirme que T(Permission).* corresponde a uma constante existente |
| Itens de menu aparecem brevemente e depois desaparecem | syncOnCodeMenus=true mas o administrador do AC tem estado a editar os menus manualmente | Ou desative a sincronização por código (IGRP_SYNC_ON_CODE_MENUS=false), ou opte pelo modo code-first e deixe de editar no AC |
| Explosão silenciosa de perfis no AM | Erros de escrita em roles[].roleCode em menus.ts + syncRoles=true | Procure perfis criados com conjunto de permissões vazio; corrija o erro de escrita ou defina syncRoles=false e pré-crie os perfis manualmente |
| Ciclo de redirecionamento após alteração de uma variável de ambiente do AM | Quase de certeza o padrão de incompatibilidade de AUTH_JWT_ISSUER documentado em análises no estilo ANALISE-E-TASKS | Verifique os registos do pod à procura da linha WARN do OidcLoginFailureHandler (ver o commit recente) — indica o errorCode exato |
Após um redeploy do backend, os utilizadores veem ACCESS_DENIED em /api/users/me | O bug de "ressurreição" de utilizador ELIMINADO — corrigido nos commits recentes | Renove o JWT do utilizador (novo login) e confirme na build mais recente do AM |
Para o que não estiver aqui coberto, ative o registo TRACE (org.springframework.security=TRACE) no pod com falha — a linha de registo indica o filtro exato e a decisão tomada.
7. Referência — localização de ficheiros
| Assunto | Ficheiro |
|---|---|
| Exemplo de declaração de permissões | access-management/backend/access-management-api/src/main/java/cv/igrp/platform/access_management/shared/infrastructure/authorization/permission/ApplicationPermissions.java |
| Processador de anotações | access-management/backend/modules/core/src/main/java/cv/igrp/framework/auth/core/processor/PermissionSourceGenerator.java |
| Sincronização de arranque do backend | access-management/backend/modules/core-spring-boot/src/main/java/cv/igrp/framework/auth/core/autoconfig/AuthorizationSyncRunner.java |
| Sincronização de arranque do frontend | shared/frontend/nextjs/packages/framework/next/src/lib/startup-sync.ts |
| Layout raiz do frontend (gatilho de sincronização) | shared/frontend/nextjs/packages/framework/next/src/layouts/igrp-root-layout.tsx |
| Exemplo de fonte de menus (target) | shared/frontend/nextjs/templates/demo-v1/src/temp/menus/menus.ts |
| Fonte de menus (AC) | access-management/frontend/application-center/src/temp/menus/menus.ts |
| Cliente M2M (TS) | access-management/frontend/packages/packages/client/src/client/m2m-client.ts |
| API M2M (Java) | access-management/backend/modules/client/src/main/java/cv/igrp/platform/access/client/api/M2MApi.java |
| Propriedades do AM | access-management/backend/access-management-api/src/main/resources/application.properties |
| Configuração do AC | access-management/frontend/application-center/src/igrp.template.config.ts |
8. Documentos relacionados
8.1 Workspace do iGRP AM
Permissions Integration Guide
Documentação detalhada sobre @IgrpPermission, o annotation processor, expressões SpEL em @PreAuthorize, e a configuração do pom.xml do backend da aplicação.
Clientes OAuth2 e contas de serviço
Como as contas de serviço M2M são geridas via /api/service-accounts e SDK Java; a gestão de clientes OAuth2 e aplicações faz-se no Application Center.
8.2 Documentação oficial do framework (ramo dev)
Estes documentos residem dentro dos próprios repositórios do framework e são distribuídos de forma idêntica ao demo-v1 e ao Application Center. Quando este guia e a documentação do framework divergirem, a documentação do framework prevalece — abra uma issue de documentação neste workspace para corrigir a discrepância.
| Ficheiro | Conteúdo |
|---|---|
demo-v1/docs/ENVIRONMENT.md | Referência completa de variáveis de ambiente, forma de validação, tabela de registo de URIs de callback/logout. |
demo-v1/docs/AUTHENTICATION.md | withIGRPAuth, o modelo de bypass AUTH_PROVIDER=none / IGRP_PREVIEW_MODE=true, sanitizeCallbackUrl, o fluxo autenticado em seis passos. |
demo-v1/docs/ACCESS_MANAGEMENT.md | O "aperto de mão" OAuth2 client_credentials com o AM, as três fases de sincronização, e a superfície de falha do IgrpConfigError. |
demo-v1/docs/PERMISSIONS.md | O modelo completo de controlo por claims do JWT: igrpAssertAuthorize, <IGRPAuthorization>, usePermissions, a tabela de camadas de aplicação, a latência de revogação, a checklist de "sem recusa por omissão". |
demo-v1/docs/TOKENS.md | O fluxo de access-token / refresh-token / id-token entre o NextAuth e o AM. |
demo-v1/docs/ARCHITECTURE.md | A forma do modelo em quatro camadas (middleware → layout raiz → (igrp)/layout.tsx → construtor de configuração). |
demo-v1/docs/MIGRATION_GUIDE.md | Atualizações do framework de versão para versão. |
Os mesmos ficheiros são distribuídos dentro do Application Center em application-center/docs/*.md.
How is this guide?
Última atualização: