Skip to main content

Configurazione Keycloak per la Piattaforma

Panoramica​

La piattaforma utilizza Keycloak come identity provider per gli utenti amministrativi (RS256). I token Keycloak vengono validati dall'API Gateway tramite JWKS. Questa guida descrive come creare e configurare il realm, i client e i claim personalizzati necessari.

Creazione del Realm​

Creare un realm dedicato alla piattaforma. Il nome predefinito e pos-enterprise.

  1. Accedere alla console admin di Keycloak (https://<KEYCLOAK_HOST>/auth/admin)
  2. Cliccare Create Realm
  3. Impostare il nome: pos-enterprise
  4. Abilitare il realm

Il realm name deve corrispondere alla variabile ambiente KEYCLOAK_REALM del backend.

Configurazione Client​

Creare un client per la admin console e uno per eventuali integrazioni:

  1. In Clients, cliccare Create Client
  2. Client ID: pos-admin (o il nome desiderato)
  3. Client Protocol: openid-connect
  4. Access Type: public per SPA (admin console Vue.js) oppure confidential per integrazioni server-side
  5. Valid Redirect URIs: https://admin.example.com/*
  6. Web Origins: https://admin.example.com

Per client confidential, annotare il Client Secret dalla tab Credentials.

Gruppi e Ruoli​

La piattaforma estrae il contesto utente (tenant, reseller, ruolo) dalla gerarchia dei gruppi Keycloak, non dai realm roles. La struttura consigliata:

/resellers
  /RESELLER_CODE
    /tenants
      /TENANT_ID
        /roles
          /admin
          /manager
          /viewer

L'API Gateway chiama extractContextFromGroups(decoded.groups) per estrarre tenantId, resellerCode e role dal percorso del gruppo piu specifico assegnato all'utente.

Realm Roles Consigliati​

Aggiungere i seguenti realm roles per compatibilita:

  • platform-admin -- Accesso globale a tutti i tenant
  • reseller-admin -- Gestione tenant del proprio reseller
  • tenant-admin -- Amministrazione singolo tenant

Claims Personalizzati​

Per popolare ctx.meta.user correttamente, assicurarsi che il token contenga i claim groups. Creare un Protocol Mapper nel client:

  1. Aprire il client pos-admin e andare nella tab Client Scopes (o Mappers)
  2. Aggiungere un mapper:
    • Name: groups
    • Mapper Type: Group Membership
    • Token Claim Name: groups
    • Full group path: ON
    • Add to ID token: ON
    • Add to access token: ON

Variabili Ambiente Backend​

Configurare le seguenti variabili nel file .env del backend:

KEYCLOAK_URL=https://auth.example.com/auth
KEYCLOAK_REALM=pos-enterprise
# Per sviluppo locale senza Keycloak:
SKIP_AUTH=true
DEV_TENANT_ID=demo

L'API Gateway utilizza KEYCLOAK_URL e KEYCLOAK_REALM per costruire l'endpoint JWKS (/realms/{realm}/protocol/openid-connect/certs) e validare la firma RS256 dei token.

Verifica Configurazione​

Dopo la configurazione, verificare il flusso completo:

# Ottenere un token
curl -X POST "https://auth.example.com/auth/realms/pos-enterprise/protocol/openid-connect/token" \
  -d "grant_type=password&client_id=pos-admin&username=admin@demo.com&password=secret"

# Usare il token verso l'API
curl -X GET "https://api.example.com/api/tenant-management/list" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Se la risposta e 200 OK con i dati del tenant, la configurazione e corretta.

FAQ​

D: Posso usare un Keycloak esistente condiviso con altri sistemi? R: Si, basta creare un realm dedicato. La piattaforma non interferisce con altri realm sullo stesso server Keycloak.

D: Cosa succede se SKIP_AUTH e true in produzione? R: Tutte le richieste vengono autenticate come dev-user con tenant demo. Non usare mai SKIP_AUTH=true in ambienti di produzione.

D: Come aggiungo un nuovo utente admin per un tenant? R: Creare l'utente in Keycloak, assegnarlo al gruppo /resellers/RESELLER/tenants/TENANT_ID/roles/admin. L'API Gateway estrarra automaticamente tenantId e ruolo dal gruppo.

Vedi Anche​

Questa pagina ti è stata utile?