Guia prático

Passo 1 — Criar os clientes OAuth2 no AM (uma vez por projeto)Copy Anchor Link

Para cada projeto, registe três clientes OAuth2 no AM (a separação por tipo de grant reduz o raio de impacto de uma rotação / revogação):

• invoicing-spa — authorization_code + refresh_token. Consumido pelas variáveis IGRP_AUTH_* do frontend (login do utilizador final através do fornecedor igrp-auth do framework).
• invoicing-spa-m2m — client_credentials. Consumido pelas variáveis IGRP_M2M_* do frontend para a sincronização de arranque de menus / aplicação.
• invoicing-backend-m2m — client_credentials. Consumido pelas propriedades igrp.access.m2m.* do backend da aplicação para a sincronização de permissões.

Registe-os através da (brevemente disponível) página de gestão de clientes no AC, ou inserindo registos via SQL a partir do padrão de semeação igrp.oauth.default-client.*, até a página estar disponível.

Para o cliente invoicing-spa, lembre-se também de registar os dois URIs de redirecionamento (ver ponto 4.2 "Autenticação"):

• Callback: ${NEXTAUTH_URL_ORIGIN}${NEXT_PUBLIC_BASE_PATH}/api/auth/callback/igrp-auth
• Pós-logout: ${NEXTAUTH_URL_ORIGIN}${NEXT_PUBLIC_BASE_PATH}/login

Guarde o clientSecret em bruto de cada resposta de criação — só é mostrado uma vez.

Passo 2 — Configurar o backend da aplicaçãoCopy Anchor Link

Siga a secção 2.4 do Permissions Integration Guide para o pom.xml (repositórios, dependências, caminho do processador de anotações) e a secção 5 do mesmo guia para o application.properties.

No mínimo:

spring.application.name=invoicing-backend
spring.security.oauth2.resourceserver.jwt.issuer-uri=https://api.example.com/igrp-access-management

igrp.access.base-url=https://api.example.com/igrp-access-management
igrp.access.m2m.client-id=invoicing-backend-m2m
igrp.access.m2m.client-secret=${INVOICING_BACKEND_M2M_SECRET}

Declare as suas permissões:

public final class InvoicePermissions {
    private InvoicePermissions() {}

    @IgrpPermission(name = "my.invoice.create", description = "Create invoice")
    public static final String INVOICE_CREATE = "my.invoice.create";
    // …
}

Arranque-o. Verifique os registos para:

• [Authorization Sync] Authenticating to Access Management via client_credentials grant (clientId=invoicing-backend-m2m)
• [Authorization Sync] Resource synchronization completed.
• [Permission Sync] Successfully synchronized N permissions.

Verifique no AC: Settings → Applications → INVOICING deve agora listar as suas permissões.

Passo 3 — Atribuir um perfil → permissãoCopy Anchor Link

Crie um perfil no AC (p. ex. INV.reader no departamento FIN), associe-lhe permissões e atribua o perfil a um utilizador de teste.

Passo 4 — Configurar o frontend da aplicaçãoCopy Anchor Link

Crie src/temp/menus/menus.ts (ponto 3.1) e src/igrp.template.config.ts (ponto 3.2). Defina as variáveis de ambiente conforme o ponto 4.4.

Arranque a SPA. Nos registos do servidor NextJS:

• [startup-sync] Application sync ok: appCode=INVOICING
• [startup-sync] Menu sync ok: appCode=INVOICING, items=4, syncRoles=true

Verifique no AC: Settings → Applications → INVOICING → Menus deve agora mostrar a sua árvore.

Passo 5 — Iniciar sessão e utilizarCopy Anchor Link

Inicie sessão com o utilizador de teste ao qual foi atribuído INV.reader no passo 3. A barra lateral da SPA mostra apenas os itens de menu cujo roles[] inclui INV.reader/FIN. As chamadas à API do backend da aplicação transportam o JWT do utilizador com permissions: ["my.invoice.read", …], e o @PreAuthorize aceita ou rejeita em conformidade.