Panoramica

DTZ Identity gestisce tre cose: Ruoli, Identità e Autenticazioni per ogni risorsa che esiste all’interno di un Contesto. I contesti sono le unità organizzative in DTZ; ogni entità appartiene a uno di essi e il controllo degli accessi fluisce attraverso di esso.

Diagramma ER delle entità Identity

Concetti fondamentali

Contesto

Un Contesto (context-…) è il contenitore per le tue applicazioni, servizi e fatturazione. Il creatore viene automaticamente assegnato come Context Admin, e un’identità di servizio come admin@{context_id}.dtz.rocks viene fornita per l’automazione.

Identità

Un’Identità è un principal (utente umano o account di servizio). Le assegnazioni di ruoli saranno legate alle identità.

Ruoli (Astratti vs. Concreti)

  • I ruoli astratti sono insiemi riutilizzabili di permessi definiti da ogni servizio DTZ (per esempio, “containers admin”, “objectstore admin”, “billing admin”).
  • I ruoli concreti sono ruoli astratti vincolati a un ambito (sia un Contesto sia un’Identità) ed espressi come URI di ruolo. Questi sono quelli che assegni effettivamente.

Esempi di URI di ruoli concreti:

  • Ambito Contesto: https://dtz.rocks/containers/admin/{context_id}
  • Ambito Identità: https://dtz.rocks/identity/admin/{identity_id}

Questa separazione mantiene la logica dei permessi coerente pur rendendo le assegnazioni consapevoli del contesto.

Ambiti dei ruoli

Ruoli con ambito Identità

Influenzano azioni sull’identità stessa (per esempio, chi può impostare una password o creare chiavi API per un’identità).

Esempi comuni:

  • https://dtz.rocks/identity/admin/{identity_id}
  • https://dtz.rocks/billing/admin/{identity_id}
  • https://dtz.rocks/identity/assume/{identity_id}

Ruoli con ambito Contesto

Influenzano azioni all’interno di un contesto (deployment, log, object store, ecc.).

Esempi comuni:

  • https://dtz.rocks/context/admin/{context_id}
  • https://dtz.rocks/containers/admin/{context_id}
  • https://dtz.rocks/objectstore/admin/{context_id}
  • https://dtz.rocks/observability/admin/{context_id}
  • https://dtz.rocks/containerregistry/admin/{context_id}
  • https://dtz.rocks/rss2email/admin/{context_id}

Ogni servizio DTZ può definire i propri nomi e ambiti dei ruoli; gli URI sopra sono rappresentativi.

Come vengono valutate le autorizzazioni

  1. Autenticarsi (chi sei).
  2. Risolvere i ruoli concreti per il chiamante (URI di ruolo sull’identità).
  3. Autorizzare in base alla corrispondenza di un URI di ruolo richiesto con l’ambito di destinazione (contesto o identità) e l’azione.

Esempio: assegnare e utilizzare un ruolo

  1. Assegna il ruolo astratto “containers admin” a uno specifico contesto → ottieni un ruolo concreto:

https://dtz.rocks/containers/admin/context-abc123

  1. Associa quel ruolo all’identità alice@example.com.
  2. Quando Alice chiama l’API Containers all’interno di context-abc123, l’URI del ruolo corrisponde e l’azione è autorizzata. Lo stesso ruolo non concede diritti in altri contesti.

Autenticazione

DTZ supporta diversi metodi di autenticazione; usa quello più adatto al tuo client e ambiente.

Chiavi API

  • Le chiavi vengono create nell’interfaccia Identity e sono vincolate a un contesto e a un’identità.
  • Inviate tramite header:

X-API-KEY: YOUR_API_KEY

  • Alcune integrazioni di terze parti che non possono impostare header possono passare apiKey come parametro di query (usare solo quando inevitabile).

Token Bearer (login con password)

Ottieni un JWT inviando username/password con POST, poi invia Authorization: Bearer ….

Richiesta token:

POST https://identity.dtz.rocks/api/2021-02-21/token/auth
Content-Type: application/json

{
"username": "user",
"password": "password"
}

Usa il token:

curl -H "Authorization: Bearer eyJhb..." \
  https://identity.dtz.rocks/api/2021-02-21/me

Puoi anche usare il JWT come cookie chiamato dtz-auth. L’autenticazione Basic è supportata per alcuni endpoint (apikey:apikey-1234).

Checklist per iniziare

  • Crea o seleziona un Contesto per la tua app.
  • Decidi quali ruoli astratti servono alla tua app e legali a ruoli concreti nei giusti ambiti (Contesto vs. Identità).
  • Assegna quei ruoli concreti alle identità (utenti/account di servizio) che ne hanno bisogno.