Skip to content

Commit 1dee637

Browse files
casualmattcasualmatt
committed
feat: update Italian documentation for Auth Module, add client and server guides
1 parent cd45402 commit 1dee637

8 files changed

Lines changed: 416 additions & 44 deletions

File tree

‎content/en/1.auth-module/2.client-guide.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@
22
links:
33
- label: Auth Service
44
to: https://jamflow.cloud/auth-service
5-
title: "Auth Module: Client Guide"
6-
description: "JAMflow Authentication and Authorization"
5+
title: "Client Guide"
6+
description: "Authentication and Authorization on the client side"
77
navigation:
88
icon: i-lucide-chromium
99
---

‎content/en/index.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,8 @@ seo:
1212
JAMflow Docs
1313

1414
#description
15-
Find the documentation for JAMflow modules in Italian and English
15+
Find the documentation for JAMflow modules in Italian and English,
16+
and start building your application today!
1617
::
1718

1819
::u-page-section
@@ -28,7 +29,7 @@ Find the documentation for JAMflow modules in Italian and English
2829
Auth Module
2930

3031
#description
31-
User authentication and management module for JAMflow applications.
32+
User authentication, authorization and management module for JAMflow applications.
3233

3334

3435
```ts

‎content/it/1.auth-module/1.getting-started.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
---
2+
links:
3+
- label: Auth Service
4+
to: https://jamflow.cloud/auth-service
5+
title: "Auth Module: Getting Started"
6+
description: "JAMflow Authentication and Authorization"
7+
navigation:
8+
icon: i-lucide-user-lock
9+
---
10+
11+
Jamflow Auth Module integra le applicazioni Nuxt con il Jamflow Auth Service. Centralizza l'autenticazione, l'appartenenza ai team e i controlli di permessi senza richiedere una connessione al database per ogni validazione. Invece, utilizza token JWT per ID, accesso e refresh emessi dall'Auth Service ed espone utility amichevoli sia sul client che sul server.
12+
13+
Il modello dei permessi è ispirato a Google Zanzibar e permette di definire regole di controllo accessi molto dettagliate basate su ruoli utente, appartenenza a team e relazioni tra risorse.
14+
15+
::u-
16+
17+
::
18+
19+
20+
## Cosa ottieni
21+
22+
- Bootstrap automatico della sessione durante SSR e idratazione SPA
23+
- Composables Vue tipizzati (`useUserSession`, `usePermissions`) per lavorare con token e permessi
24+
- Utility Nitro per verificare sessioni, proteggere route ed effettuare richieste service-to-service
25+
- Endpoint proxy (`/_auth-api/**`, `/.well-known/jwks.json`) per mantenere i cookie sul tuo dominio e evitare problemi CORS
26+
- Superficie di configurazione minima che si collega ai tenant dell'Auth Service gestiti dalla tua azienda
27+
28+
## Quickstart
29+
30+
Una volta ricevuto un deployment dell'Auth Service, puoi installare l'Auth Module nelle tue applicazioni Nuxt.
31+
32+
1. Installa il modulo tramite il package manager preferito.
33+
2. Registralo in `nuxt.config.ts`:
34+
35+
```ts
36+
export default defineNuxtConfig({
37+
modules: ['@jamflow/auth-module'],
38+
auth: {
39+
issuer: 'https://<YOUR-PROJECT>.auth.jamflow.app',
40+
audience: 'https://your-project.com',
41+
},
42+
})
43+
```
44+
45+
3. Assicurati che l'ambiente permetta di impostare cookie sicuri per l'host che serve la tua app Nuxt.
46+
4. Usa la [Guida client](./client-guide.md) e la [Guida server](./server-guide.md) fornite per collegare i flussi utenti.
47+
48+
## Modello dei token
49+
50+
L'Auth Service emette tre cookie:
51+
52+
| Token | Cookie di default | Scopo |
53+
| --- | --- | --- |
54+
| ID token | `j_id_token` | Identifica l'utente autenticato (nome, email, team, ecc.).
55+
| Access token | `j_access_token` | Trasporta stringhe di permessi serializzate per l'autorizzazione.
56+
| Refresh token | `j_refresh_token` | Permette di rinnovare ID/access token senza riautenticazione.
57+
58+
Il modulo verifica i token usando il documento JWKS esposto dal tuo Auth Service. La verifica è automatica e la chiave viene messa in cache per un'ora.
59+
60+
## Architettura a colpo d'occhio
61+
62+
::Mermaid
63+
```
64+
flowchart LR
65+
subgraph Browser
66+
A[Vue component]
67+
end
68+
subgraph NuxtApp[Nuxt Nitro]
69+
B[useUserSession]
70+
C[usePermissions]
71+
D[/requireUserSession, requireUserPermission/]
72+
E[Proxy routes]
73+
end
74+
subgraph AuthService
75+
F["/api/auth/*" endpoints]
76+
G["/.well-known/jwks.json"]
77+
end
78+
79+
A --> B
80+
A --> C
81+
B & C --> E --> F
82+
D --> E
83+
E --> G
84+
```
85+
::
86+
87+
- I composables client parlano sempre a `/_auth-api/...`, che fa da proxy verso `${issuer}/api/...`.
88+
- Le utility server fanno lo stesso e inoltre mettono in cache i token decodificati nel contesto `H3Event` per il riutilizzo.
89+
- Le chiavi JWKS sono proxate tramite `/.well-known/jwks.json` per evitare richieste cross-origin dal browser.
90+
91+
## Riferimento di configurazione
92+
93+
| Opzione | Variabile d'ambiente | Descrizione |
94+
| --- | --- | --- |
95+
| `auth.issuer` | `NUXT_PUBLIC_AUTH_ISSUER` | URL base del deployment del tuo Auth Service. Obbligatorio.
96+
| `auth.audience` | `NUXT_PUBLIC_AUTH_AUDIENCE` | Audience attesa per gli access token. Obbligatorio.
97+
| `auth.jwksUrl` | `NUXT_PUBLIC_AUTH_JWKS_URL` | Percorso al documento JWKS. Di default `/.well-known/jwks.json`.
98+
| `auth.idToken.name` | `NUXT_PUBLIC_AUTH_ID_TOKEN_NAME` | Nome del cookie per l'ID token. Di default `j_id_token`.
99+
| `auth.accessToken.name` | `NUXT_PUBLIC_AUTH_ACCESS_TOKEN_NAME` | Nome del cookie per l'access token. Di default `j_access_token`.
100+
| `auth.refreshToken.name` | `NUXT_AUTH_REFRESH_TOKEN_NAME` | Nome del cookie per il refresh token. Di default `j_refresh_token`.
101+
| `auth.refreshToken.expiresIn` | `NUXT_AUTH_REFRESH_TOKEN_EXPIRES_IN` | Scadenza (in secondi) usata per valutare la longevità del refresh token.
102+
| `auth.apiToken` | `NUXT_AUTH_API_TOKEN` | Token macchina per l'accesso all'API dell'Auth Service (usato da `createInvite`).
103+
104+
## Checklist per lo sviluppo usando il modulo
105+
106+
1. Configura i valori runtime tramite variabili d'ambiente in file `.env` o segreti di deploy.
107+
2. Conferma che i cookie siano emessi con gli attributi `Secure` e `SameSite` attesi per il tuo scenario di hosting.
108+
3. Decidi come l'interfaccia gestisce i fallimenti di permesso (redirect vs. stato vuoto).
109+
110+
## Per saperne di più
111+
112+
- [Guida client](/it/auth-module/client-guide.md) – lavorare con i composables, i flussi di login e i permessi in Vue.
113+
- [Guida server](/it/auth-module/server-guide.md) – utility Nitro, guardie per i permessi e helper di servizio.

‎content/it/1.auth-module/2.client-guide.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
---
2+
links:
3+
- label: Auth Service
4+
to: https://jamflow.cloud/auth-service
5+
title: "Client Guide"
6+
description: "Autenticazione e autorizzazione sul lato client"
7+
navigation:
8+
icon: i-lucide-chromium
9+
---
10+
11+
Questo modulo fornisce una serie di composables Vue e plugin Nuxt che facilitano l'integrazione con Jamflow Auth Service nelle applicazioni Nuxt. Qui trovi i principali strumenti lato client, come comunicano con il backend Auth e come integrarli nella tua app.
12+
13+
::warning
14+
**Prerequisiti**
15+
16+
- Il tuo contratto deve includere un'istanza di Auth Service.
17+
- Il modulo deve essere registrato in `nuxt.config.ts` e configurato con almeno `issuer` e `audience`.
18+
- I cookie per ID, access e refresh token sono gestiti automaticamente dal modulo; assicurati che il tuo ambiente di deploy non li blocchi.
19+
::
20+
21+
## Bootstrap della sessione
22+
23+
Due plugin Nuxt si occupano di mantenere la sessione aggiornata durante navigazione e idratazione:
24+
25+
- `session.server`: viene eseguito prima del render sul server. Popola il payload con una flag `isCached` e, quando la richiesta è renderizzata al volo, chiama `useUserSession().fetch()` per decodificare gli ID e access token più recenti.
26+
- `session.client`: viene eseguito sul client durante l'idratazione. Se la pagina è stata consegnata da cache del payload o da prerendering statico, recupera la sessione dopo il mount dell'app per evitare dati obsoleti.
27+
28+
Non è necessario importare manualmente questi plugin: vengono registrati automaticamente all'installazione del modulo.
29+
30+
## `useUserSession()`
31+
32+
`useUserSession` è il composable principale esposto dal modulo. Si occupa di rinfrescare i cookie in modo trasparente, comunicare con le route proxy del server e fornire uno stato reattivo per l'utente autenticato.
33+
34+
```ts
35+
const {
36+
user, // Computed<IDTokenClaims | null>
37+
access, // Computed<AccessTokenClaims | null>
38+
loggedIn, // Computed<boolean>
39+
login,
40+
requestAccess,
41+
fetch,
42+
refresh,
43+
clear,
44+
} = useUserSession()
45+
```
46+
47+
### Accesso allo stato
48+
49+
- `user`: claim dell'ID token (sub, email, team, ecc.). `null` quando il visitatore è anonimo o il token non è verificabile.
50+
- `access`: claim dell'access token, inclusi i codici di permesso serializzati usati da `usePermissions`.
51+
- `loggedIn`: booleano di comodo derivato da `user`.
52+
53+
### Azioni
54+
55+
- `login(email, password)`: Chiama `/_auth-api/auth/login`, imposta i cookie, recupera i permessi di accesso e risolve quando la sessione è pronta.
56+
- `requestAccess(teamId?)`: Richiede manualmente un access token aggiornato per l'utente corrente. Utile quando si cambia contesto team.
57+
- `fetch()`: Rilegge i cookie, valida i token contro il JWKS e aggiorna lo stato locale. Di solito non serve chiamarla direttamente perché i plugin la gestiscono.
58+
- `refresh()`: Usa l'endpoint di refresh per ottenere nuovi ID e access token.
59+
- `clear()`: Disconnette l'utente cancellando i cookie tramite `/_auth-api/auth/session` e resettando lo stato in memoria.
60+
61+
### Uso nei diversi contesti di fetch
62+
63+
Il composable seleziona automaticamente tra `$fetch` client e `$fetch` request-scoped sul server. Questo è importante quando si scrivono plugin o middleware personalizzati: lo stesso codice funziona in componenti, route server e handler Nitro senza configurazioni aggiuntive.
64+
65+
## Gestire i permessi con `usePermissions()`
66+
67+
I permessi sono codificati nell'access token come codici brevi (es. `@blog:cru` per create/read/update globali sul topic `blog`). `usePermissions` traduce queste stringhe in una struttura dati descrittiva e fornisce helper per proteggere UI e pagine.
68+
69+
```ts
70+
const { permissions, hasPermission, pagePermission } = usePermissions()
71+
```
72+
73+
- `permissions`: oggetto computed di tipo `DecryptedPermissions` che separa gli ambiti `team` e `global`.
74+
- `hasPermission(check)`: Restituisce `true` se l'access token corrente concede tutte le azioni richieste per uno specifico topic. Imposta `check.team = true` per valutare i permessi a livello di team; altrimenti si controlla l'ambito globale.
75+
- `pagePermission(check, { redirect? })`: Restituisce l'oggetto `ResourcePermissions` completo per il topic. Se l'utente non ha accesso puoi abilitare un redirect (di default `'/'`). Senza redirect restituisce un oggetto con tutte le azioni a `false`, utile per renderizzare uno stato di avviso.
76+
77+
### Esempio: proteggere una pagina
78+
79+
```vue
80+
const { pagePermission } = usePermissions()
81+
82+
<script setup lang="ts">
83+
const blogPerms = await pagePermission({
84+
topic: 'blog-posts',
85+
actions: ['read'],
86+
})
87+
</script>
88+
89+
<template>
90+
<section v-if="blogPerms.read">
91+
<!-- Contenuto protetto -->
92+
</section>
93+
<NuxtErrorBoundary v-else>
94+
<p>Non hai ancora accesso ai post del blog.</p>
95+
</NuxtErrorBoundary>
96+
</template>
97+
```
98+
99+
### Esempio: abilitare/disabilitare controlli UI
100+
101+
```vue
102+
<script setup lang="ts">
103+
const { hasPermission } = usePermissions()
104+
105+
const canPublish = computed(() => hasPermission({
106+
topic: 'blog-posts',
107+
actions: ['execute'],
108+
}))
109+
</script>
110+
111+
<template>
112+
<UButton :disabled="!canPublish">Publish</UButton>
113+
</template>
114+
```
115+
116+
## Ciclo di vita dei token
117+
118+
- I cookie vengono aggiornati automaticamente ad ogni chiamata a `fetch()` e `refresh()` tramite l'helper `refreshCookie` di Nuxt.
119+
- Quando un access token è scaduto, `useUserSession` richiede trasparentemente uno nuovo e propaga gli header Set-Cookie dall'API al browser.
120+
- Le chiavi JWKS vengono memorizzate in memoria per fino a un'ora per ridurre traffico di rete inutile.
121+
122+
## Risoluzione dei problemi
123+
124+
| Sintomo | Probabile causa | Soluzione |
125+
| --- | --- | --- |
126+
| `useUserSession().user` è sempre `null` | `issuer` / `audience` runtime mancanti o non validi | Verifica `nuxt.config` e le variabili d'ambiente. |
127+
| Il login riesce ma i permessi sono vuoti | Access token non richiesto o codici permesso non configurati server-side | Assicurati che `requestAccess()` venga chiamato dopo il login e che l'Auth Service emetta i permessi. |
128+
| Le navigazioni client perdono la sessione | Cookie bloccati dal dominio o mismatch degli attributi secure | Controlla l'URL base del deploy e la configurazione dei cookie nel servizio. |
129+
130+
## Passi successivi
131+
132+
- Consulta la [Guida server](/it/auth-module/server-guide.md) per le utility Nitro da usare nelle route API.
133+
- Fai attenzione alla scadenza dei token in tab mantenute a lungo; valuta di chiamare periodicamente `useUserSession().refresh()` se la tua UX lo richiede.

0 commit comments

Comments
 (0)