Panoramica

DTZ Identity gestisce tre elementi: Roles, Identities, e Authentications per ogni risorsa che vive all’interno di un Context. I Context sono le unità organizzative in DTZ; ogni entità appartiene a uno, e il controllo degli accessi fluisce attraverso di esso.

Diagramma delle relazioni delle entità di Identity

Concetti principali

Context

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

Identities

Una Identity è un principal (utente umano o account di servizio). Associerai gli assegnamenti di ruolo alle identities.

Ruoli (astratti vs. concreti)

  • I ruoli astratti sono insiemi di permessi riutilizzabili definiti da ciascun servizio DTZ (es., “containers admin”, “objectstore admin”, “billing admin”).
  • I ruoli concreti sono ruoli astratti vincolati a uno scope (o un Context o una Identity) ed espressi come role URI. Questi sono quelli che assegni realmente.

Esempi di role URI concreti:

  • Scope Context: https://dtz.rocks/containers/admin/{context_id}
  • Scope Identity: https://dtz.rocks/identity/admin/{identity_id}

Questa separazione mantiene la logica dei permessi coerente rendendo però gli assegnamenti sensibili al contesto.

Scope dei ruoli

Ruoli scoped all’Identity

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

Esempi comuni:

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

Ruoli scoped al Context

Influenzano azioni all’interno di un context (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 scope di ruolo; le URI sopra sono rappresentative.

Come vengono valutati i permessi

  1. Autenticarsi (chi sei).
  2. Risolvere i ruoli concreti per il chiamante (role URI presenti sull’identity).
  3. Autorizzare in base a se un role URI richiesto corrisponde allo scope target (context o identity) e all’azione.

Esempio: assegnare e usare un ruolo

  1. Assegna l’astratto “containers admin” a uno specifico context → ottieni un ruolo concreto:

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

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

Autenticazione

DTZ supporta più metodi di autenticazione; usa quello che si adatta al tuo client e ambiente.

API Keys

  • Le chiavi vengono create nell’Identity UI e sono scoperte su un context e un’identity.
  • Inviare 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 (usarne l’uso solo se inevitabile).

Bearer token (login con password)

Ottieni un JWT facendo POST con username/password, 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"
}

Usare 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. Il basic auth è supportato per alcuni endpoint (apikey:apikey-1234).

Checklist per iniziare

  • Crea o seleziona un Context per la tua app.
  • Decidi quali ruoli astratti servono alla tua app e vincolali in ruoli concreti agli scope appropriati (Context vs. Identity).
  • Assegna quei ruoli concreti alle identities (utenti/account di servizio) che ne hanno bisogno.