Gestione degli Utenti

Auris fornisce un sistema completo per la gestione del ciclo di vita degli utenti accessibile sia tramite la Console Admin che tramite le API REST. Gli amministratori possono elencare, creare, aggiornare, disabilitare, eliminare temporaneamente e ripristinare gli utenti senza toccare l’interfaccia admin nativa di Keycloak.

Elenco degli Utenti

L’elenco utenti supporta paginazione, ricerca full-text, filtraggio per ruolo e per stato. I risultati vengono restituiti nell’envelope di paginazione standard di Auris.

Struttura della risposta:

{
  "data": [
    {
      "id": "usr_01HX...",
      "email": "[email protected]",
      "username": "alice",
      "firstName": "Alice",
      "lastName": "Rossi",
      "enabled": true,
      "roles": ["member"],
      "createdAt": "2025-03-01T10:00:00Z",
      "lastLogin": "2025-06-10T08:45:00Z",
      "metadata": {}
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 142,
    "totalPages": 8
  }
}

Guida alla Console: Vai su Console Admin → Utenti. La tabella si aggiorna automaticamente quando modifichi il termine di ricerca o applichi i filtri. Clicca su una riga per aprire il pannello di dettaglio utente.

Creazione degli Utenti

Gli utenti possono essere creati direttamente con una password, oppure senza password per attivare un’email di invito che chiede all’utente di impostare le proprie credenziali.

Corpo della richiesta:

{
  "email": "[email protected]",
  "username": "mario",
  "firstName": "Mario",
  "lastName": "Rossi",
  "password": "PasswordSicura123!",
  "sendInvite": false,
  "roles": ["member"],
  "metadata": {
    "department": "engineering",
    "employeeId": "EMP-4421"
  }
}

Riferimento campi:

Guida alla Console: Clicca il pulsante “Nuovo Utente” nella pagina Utenti. Il dialogo presenta un form a schede: Generale (nome, email), Credenziali (password o toggle invito) e Ruoli (selezione multipla).

Aggiornamento degli Utenti

Campi aggiornabili:

{
  "firstName": "Mario",
  "lastName": "Bianchi",
  "enabled": true,
  "roles": ["member", "billing-admin"],
  "metadata": {
    "department": "leadership"
  }
}

L’aggiornamento di roles sostituisce completamente il set di ruoli dell’utente — includi tutti i ruoli desiderati, non solo quelli da aggiungere. Per aggiungere un singolo ruolo senza influenzare gli altri, leggi prima l’elenco ruoli corrente, aggiungi il nuovo ruolo, poi invia il set completo.

L’aggiornamento di enabled: false disabilita immediatamente l’utente in Keycloak, invalidando tutte le sessioni attive.

Eliminazione Temporanea e Ripristino

Auris usa l’eliminazione temporanea (soft delete) per preservare le tracce di audit. L’eliminazione di un utente contrassegna il record con deletedAt invece di rimuoverlo dal database o da Keycloak.

Ripristino di un utente:

Guida alla Console: La pagina Utenti ha una scheda filtro “Eliminati” che mostra gli utenti eliminati temporaneamente. Ogni riga utente eliminato ha un’azione “Ripristina” nel menu a tendina.

Sessioni Utente

Auris traccia le sessioni Keycloak attive per utente. Gli amministratori possono visualizzare i dettagli delle sessioni e revocare sessioni individuali per forzare la ri-autenticazione — utile quando il dispositivo di un utente viene perso o compromesso.

Guida alla Console: Apri un pannello di dettaglio utente e seleziona la scheda “Sessioni”. Ogni sessione mostra browser/OS, indirizzo IP, ora di login e un pulsante “Revoca”.

Metadati Utente

I metadati consentono di memorizzare dati JSON arbitrari su un utente senza modificare lo schema di Auris. Vengono restituiti su ogni oggetto utente e sono accessibili nell’SDK di Management.

Casi d’uso comuni:

• Preferenze specifiche dell’applicazione (theme, language, timezone)
• Identificatori interni (employeeId, costCenter, managerId)
• Feature flag o dati di autorizzazione
• Tracciamento del progresso di onboarding

I metadati vengono memorizzati come oggetto JSON piatto o annidato. Non esiste uno schema imposto — la struttura è interamente definita dall’applicazione.

{
  "metadata": {
    "department": "engineering",
    "employeeId": "EMP-4421",
    "onboarding": {
      "completed": true,
      "completedAt": "2025-04-15T09:00:00Z"
    }
  }
}

Management SDK

Usa il Management SDK per l’amministrazione degli utenti lato server. Il Management SDK si autentica tramite credenziali client M2M — non è destinato all’uso nel codice browser.

import { AurisClient } from '@auris/js'
 
const auris = new AurisClient({
  domain: 'https://auth.tuaapp.com',
  clientId: process.env.AURIS_CLIENT_ID,
  clientSecret: process.env.AURIS_CLIENT_SECRET,
})
 
// Crea un management client autenticato con credenziali M2M
const mgmt = auris.createManagementClient({
  clientId: process.env.AURIS_MGMT_CLIENT_ID,
  clientSecret: process.env.AURIS_MGMT_CLIENT_SECRET,
})
 
// Elenca gli utenti con paginazione
const result = await mgmt.users.list({ page: 1, limit: 20 })
console.log(result.data)       // User[]
console.log(result.pagination) // { page, limit, total, totalPages }
 
// Ottieni un utente specifico
const user = await mgmt.users.get('usr_01HX...')
 
// Crea un utente
const newUser = await mgmt.users.create({
  email: '[email protected]',
  firstName: 'Carla',
  roles: ['member'],
  sendInvite: true,
})
 
// Aggiorna un utente
await mgmt.users.update('usr_01HX...', {
  metadata: { department: 'product' },
})
 
// Disabilita un utente
await mgmt.users.update('usr_01HX...', { enabled: false })
 
// Elimina temporaneamente un utente
await mgmt.users.delete('usr_01HX...')

import { createServerManagementClient } from '@auris/nextjs/server'
 
// In un Route Handler o Server Component
export async function GET() {
  // Legge automaticamente AURIS_MGMT_CLIENT_ID e AURIS_MGMT_CLIENT_SECRET dall'ambiente
  const mgmt = createServerManagementClient()
 
  const user = await mgmt.users.get('usr_01HX...')
 
  return Response.json(user)
}
 
// Elenco utenti in un Server Component
async function AdminUsersPage() {
  const mgmt = createServerManagementClient()
  const { data: users, pagination } = await mgmt.users.list({
    page: 1,
    limit: 50,
    search: '',
  })
 
  return (
    <ul>
      {users.map((u) => (
        <li key={u.id}>{u.email}</li>
      ))}
    </ul>
  )
}

Permessi Richiesti

Pagine Correlate

• Console: Utenti e Ruoli — Guida visiva all’interfaccia di gestione utenti della Console Admin
• Importazione ed Esportazione Utenti — Importazione massiva da CSV o JSON
• SCIM 2.0 Provisioning — Provisioning automatico da Okta, Azure AD e IdP simili
• Claim JWT Personalizzati — Inietta i metadati utente negli access token