Integrazione OIDC

DTZ Identity è un provider OpenID Connect (OIDC) conforme agli standard. Qualsiasi servizio che supporta OIDC può delegare l’autenticazione a DTZ, permettendo ai tuoi utenti di accedere con le loro credenziali DTZ esistenti.

Prerequisiti

  • Un account DTZ e almeno un contesto (context-{id})
  • Un servizio o un’applicazione che supporti OIDC / il flusso di autorizzazione OAuth 2.0 (authorization code)

Discovery endpoint

DTZ pubblica un documento di discovery OIDC standard:

https://identity.dtz.rocks/.well-known/openid-configuration

La maggior parte delle librerie client OIDC accetta un URL issuer e recupera automaticamente questo documento per configurarsi. Imposta l’issuer su https://identity.dtz.rocks e lascia che la libreria gestisca la scoperta degli endpoint.

Client credentials

DTZ usa il context ID sia come client_id che come client_secret. Non è necessaria una registrazione separata dell’applicazione.

Parameter Value
client_id Your context ID, e.g. context-abc123
client_secret Same context ID
issuer https://identity.dtz.rocks

Configuration reference

Le seguenti variabili d’ambiente mostrano una tipica integrazione:

OIDC_ISSUER=https://identity.dtz.rocks
OIDC_CLIENT_ID={YOUR_CONTEXT_ID}
OIDC_CLIENT_SECRET={YOUR_CONTEXT_ID}
OIDC_REDIRECT_URI=https://yourapp.example.com/login

I nomi delle variabili possono differire tra librerie e framework; ciò che conta sono i valori sopra.

ID token claims

Dopo uno scambio di token riuscito, l’ID token e l’endpoint userinfo restituiscono i seguenti claim:

Claim Example value Description
sub identity-12345678 Identificatore univoco dell’identità
iss dtz.rocks Issuer del token — sempre dtz.rocks per i token emessi da DTZ
contexts ["abc124"] ID dei contesti a cui l’utente appartiene
roles ["https://dtz.rocks/context/admin/abc123"] URI di ruolo concreti assegnati all’utente

Access control via claims

Usa i valori dei claim per limitare chi può accedere al tuo servizio dopo un login OIDC riuscito.

Limitare a qualsiasi utente DTZ — verifica che iss sia uguale a dtz.rocks:

OIDC_ALLOWED_CLAIM=iss
OIDC_ALLOWED_VALUES=dtz.rocks

Limitare agli utenti di uno specifico contesto — controlla l’array contexts:

OIDC_ALLOWED_CLAIM=scope
OIDC_ALLOWED_VALUES={YOUR_CONTEXT_ID}}

Limitare agli utenti con un ruolo specifico — controlla l’array roles per un concreto URI di ruolo.

Il meccanismo esatto per valutare questi controlli dipende dalla libreria OIDC o dal middleware che utilizzi.

Authorization code flow

  1. Reindirizza l’utente non autenticato all’endpoint authorize di DTZ (risolto tramite discovery).
  2. L’utente si autentica su https://identity.dtz.rocks. Gli utenti già autenticati vengono reindirizzati immediatamente.
  3. Scambia il codice di autorizzazione restituito con i token presso l’endpoint token.
  4. Valida il claim iss dell’ID token e qualsiasi ulteriore claim di controllo accessi.
  5. Concedi o nega l’accesso in base alla tua policy sui claim.

Userinfo endpoint

GET https://identity.dtz.rocks/api/2021-02-21/oauth/userinfo
Authorization: Bearer <access_token>

Restituisce gli stessi claim dell’ID token. Usa questo endpoint quando hai bisogno di recuperare nuovamente valori di claim aggiornati dopo il login iniziale.

  • OAuth 2 overview — come DTZ implementa il flusso di authorization code
  • Roles — comprendere ruoli concreti e astratti
  • Identity overview — contesti, identità e controllo degli accessi