Documentazione per sviluppatori di Dazr Identity

Le persone possono già usare il loro account Google o Microsoft dentro Dazr Identity, quindi alla Sua app non servono pulsanti Google e Microsoft separati accanto: un pulsante invece di tre.

Discovery ed endpoint

Tutto è descritto nel documento di discovery. Indichi l’issuer alla Sua libreria e troverà da sola il resto.

CosaIndirizzo
Issuerhttps://identity.dazr.eu
Discoveryhttps://identity.dazr.eu/.well-known/openid-configuration
Autorizzazionehttps://identity.dazr.eu/oauth/authorize
Tokenhttps://identity.dazr.eu/oauth/token
Informazioni utentehttps://identity.dazr.eu/oauth/userinfo
Chiavi pubbliche (JWKS)https://identity.dazr.eu/oauth/jwks
Revoca (RFC 7009)https://identity.dazr.eu/oauth/revoke
Introspezione (RFC 7662), solo app web serverhttps://identity.dazr.eu/oauth/introspect
Disconnessione (RP-initiated logout)https://identity.dazr.eu/oauth/logout
Rapporti di verifica, solo app web serverhttps://identity.dazr.eu/oauth/verification-report

Registrare un’app

Un’app nella console sviluppatori di Dazr Identity: client ID, URL di discovery, URI di reindirizzamento, scope e i passaggi per collegarla

Guide all’integrazione

Ogni stack qui sotto usa il proprio supporto standard per OpenID Connect. Le servono tre valori dalla console: il client ID, il client secret (solo per le app web server) e l’URI di reindirizzamento che ha registrato. Il resto arriva dal documento di discovery.

Qualsiasi libreria OpenID Connect

Se il Suo stack non è nell’elenco, funziona qualsiasi client OpenID Connect. Controlli queste impostazioni:

Il flusso

  1. Crei un code_verifier casuale (da 43 a 128 caratteri) e la sua code_challenge = base64url(SHA-256(verifier)). Crei uno state e un nonce casuali. Conservi tutti e tre nella sessione dell’utente.
  2. Reindirizzi all’endpoint di autorizzazione con response_type=code, client_id, redirect_uri, scope (sempre con openid), state, nonce, code_challenge e code_challenge_method=S256.
  3. La persona accede se necessario e vede la schermata di consenso con i dati reali. Se approva, torna al Suo URI di reindirizzamento con code, state e iss. Controlli che state corrisponda e che iss sia https://identity.dazr.eu.
  4. Sul Suo server, invii un POST all’endpoint dei token con grant_type=authorization_code, code, lo stesso redirect_uri e il code_verifier.
  5. Verifichi l’ID token: firma ES256 con una chiave del JWKS (in base al kid), iss, aud = il Suo client ID, exp e il Suo nonce. Usi sub come chiave dell’account.
La schermata di consenso di Dazr Identity per un’app chiamata Ledgerline: elenca il nome, l’indirizzo email e l’organizzazione verificata che l’utente ha scelto di condividere

Il parametro prompt accetta none (risposta immediata con login_required o consent_required se la persona dovrebbe intervenire), login (chiedere alla persona di accedere di nuovo) e consent (mostrare la schermata di consenso anche se era già stata approvata). max_age è supportato. Consenso memorizzato: se la persona ha già approvato gli stessi scope, torna subito alla Sua app. Se in seguito chiede di più, la schermata di consenso mostra solo le novità.

Scope e claim

Chieda solo ciò che Le serve. Al di fuori di questa tabella non esiste nulla: niente contatti, niente password. I file si leggono solo tramite la Dazr Files API, con un proprio scope files.read.

ScopeClaim
openid (obbligatorio)sub: un ID casuale per la persona, uguale per ogni app della Sua organizzazione e diverso per ogni altra organizzazione
profilename (se impostato) e locale
emailemail ed email_verified (sempre true)
addressaddress (formatted, street_address, locality, region, postal_code, country), solo se la persona ne ha salvato uno
organisationsorganisations: le organizzazioni che la persona seleziona nella schermata di consenso, ciascuna con id, name, display_name, website, country, register_number, vat, vat_verified (true solo se il servizio UE VIES ha confermato la partita IVA), verified, verification (veda Organizzazioni verificate) e role (owner, admin o member)
offline_accessnessun claim; riceve anche un refresh token

I claim compaiono nell’ID token per gli scope approvati dalla persona. L’endpoint delle informazioni utente restituisce lo stesso insieme, con i valori attuali.

Organizzazioni verificate

Dazr verifica un’organizzazione solo quando fonti ufficiali provano due cose: chi è la persona e che rappresenta questa organizzazione, con denominazione, numero di registro e partita IVA. Di solito chi amministra l’organizzazione firma una breve dichiarazione con una firma elettronica qualificata (QES) e aggiunge la visura in cui figura; con un estratto sigillato dal registro, come una visura camerale o un estratto KVK olandese, è immediato, altrimenti lo esamina Dazr. Una firma qualificata da sola non rende mai verificata un’organizzazione. Ogni organizzazione nel claim organisations riporta la sua verifica attuale:

Verifica di un’organizzazione in Dazr Identity: il legale rappresentante firma la dichiarazione con una firma qualificata, subito o più tardi via email, oppure carica la visura e un documento d’identità
verification.statusSignificato
unverifiedNon verificata, oppure una verifica non è riuscita, è scaduta o è stata revocata (per esempio dopo una modifica della ragione sociale o del numero di registro).
pendingLa verifica è in corso: a chi rappresenta l’organizzazione è stato chiesto di firmare, manca ancora la visura camerale, oppure Dazr sta esaminando i documenti. method indica la procedura avviata, ad esempio qes (chi rappresenta l’organizzazione firma la dichiarazione), qseal, pec, letter, video o documents.
verifiedVerificata. method è qes_org (firma qualificata, il certificato indica l’organizzazione), extract_sealed (firma qualificata o documento d’identità esaminato, più un estratto sigillato dal registro delle imprese), qes_reviewed (firma qualificata, estratto controllato da Dazr), qseal (il sigillo elettronico qualificato dell’organizzazione), documents, pec (un codice inviato all’indirizzo PEC dell’organizzazione, Italia), letter (un codice spedito per posta alla sede legale), video (una videochiamata con Dazr) o extract. authority indica che cosa ha provato che la persona rappresenta l’organizzazione (veda sotto), e verified_at è un tempo Unix.

Solo quando lo stato è verified, verification.authority (e authority nei webhook) indica come è stato provato il legame tra la persona e l’organizzazione. Ogni verifica è una prova documentata, controllata una volta alla data indicata. Non garantisce la solvibilità o la condotta dell’organizzazione e non mostra a chi appartiene l’organizzazione.

verification.authorityChe cosa prova
certificateProva documentata che la richiesta è stata firmata con una firma elettronica qualificata, o sigillata con un sigillo elettronico qualificato, il cui certificato indica l’organizzazione e il suo numero di registro. Dazr ha controllato il certificato sulle liste di fiducia dell’UE e l’eventuale revoca.
register_extractProva documentata che un amministratore o un rappresentante legale ha confermato la richiesta, con una firma elettronica qualificata o con un documento d’identità controllato da Dazr, e che una visura sigillata dal registro delle imprese, di non oltre 3 mesi, lo indica.
reviewedProva documentata che un amministratore o un rappresentante legale ha confermato la richiesta, con una firma elettronica qualificata o con un documento d’identità, e che una persona di Dazr ha controllato una visura, di non oltre 3 mesi, che lo indica.
pecProva documentata che qualcuno con accesso all’indirizzo di posta elettronica certificata (PEC) dell’organizzazione, come risulta dal registro delle imprese, ha confermato la richiesta con un codice monouso.
letterProva documentata che qualcuno con accesso alla posta della sede legale ha confermato la richiesta con un codice monouso che Dazr vi ha spedito per lettera.
videoProva documentata che una persona di Dazr ha visto, in una videochiamata, il documento d’identità della persona che ha confermato la richiesta e un estratto ufficiale che la indica come amministratore o rappresentante legale.

Le stesse definizioni sono nei termini d’uso, nella sezione 7 delle Condizioni per sviluppatori e in ogni report di verifica.

Il booleano verified resta per compatibilità ed è uguale a verification.status === 'verified'. Ogni organizzazione ha anche un id, lo stesso usato dai webhook.

Quando lo stato è pending o verified, verification.report_url è l’indirizzo del suo rapporto di verifica.

"organisations": [{
  "id": "org_3k9x2m0q8w1v5t7a", "name": "Conti Logistica S.r.l.", "country": "IT",
  "register_number": "REA MI1234567", "vat": "IT12345678903", "vat_verified": true,
  "display_name": "Conti", "website": "https://conti.example",
  "verified": false, "verification": { "status": "pending", "method": "qes" }, "role": "owner"
}]

role e l’appartenenza vengono rilette a ogni rinnovo del token e a ogni richiesta user info: dopo un cambio di ruolo la risposta successiva contiene il nuovo ruolo, e un’organizzazione che la persona ha lasciato o da cui è stata rimossa non viene più inclusa. Se un amministratore dell’organizzazione scollega la Sua app, l’organizzazione viene esclusa dai token emessi prima, finché un membro non la condivide di nuovo con la Sua app in un nuovo accesso. display_name e website sono null se l’organizzazione non li ha impostati; name è sempre la ragione sociale.

Paesi e tempi

Possono verificarsi le organizzazioni dei 27 Paesi dell’UE, di Norvegia, Islanda, Liechtenstein, Svizzera e Regno Unito. La modalità più rapida dipende dal Paese:

PaeseVerifica delle organizzazioniVerifica aziendale
ItaliaImmediata con una firma qualificata e una visura sigillata dal registro delle imprese, oppure in pochi minuti con un codice all’indirizzo PEC dell’aziendaUna visura di non oltre 3 mesi, controllata da una persona di Dazr, di solito entro un giorno lavorativo
Paesi BassiImmediata con una firma qualificata e un estratto KVK certificato digitalmenteDal registro KVK, controllato da una persona di Dazr, di solito entro un giorno lavorativo
Austria, BelgioImmediata con una firma qualificata e un estratto sigillato dal registro delle impreseUn estratto ufficiale di non oltre 3 mesi, controllato da una persona di Dazr, di solito entro un giorno lavorativo
Norvegia, Danimarca, Finlandia, Francia, Polonia, CechiaImmediata con una firma qualificata il cui certificato indica l’organizzazione; altrimenti un estratto e un documento, controllati da una persona di Dazr, di solito entro un giorno lavorativoDal registro delle imprese online, controllato da una persona di Dazr, di solito entro un giorno lavorativo
Regno UnitoUn estratto e un documento, controllati da una persona di Dazr, di solito entro un giorno lavorativoDa Companies House, controllato da una persona di Dazr, di solito entro un giorno lavorativo
Tutti gli altri Paesi supportatiImmediata con una firma qualificata il cui certificato indica l’organizzazione; altrimenti un estratto e un documento, controllati da una persona di Dazr, di solito entro un giorno lavorativoUn estratto ufficiale di non oltre 3 mesi, controllato da una persona di Dazr, di solito entro un giorno lavorativo
OvunqueUn codice per posta (100 € + IVA, da 3 a 10 giorni lavorativi) o una videochiamata (200 € + IVA)Una videochiamata (200 € + IVA) se il rappresentante non ha la fotocamera sul telefono

I tempi sono indicativi, non garantiti. Automatica significa che regole documentate decidono quando ogni controllo è chiaro; se uno non lo è, interviene una persona di Dazr, di solito entro un giorno lavorativo. La pagina di aiuto per chi deve verificarsi indica quale estratto del registro procurarsi in ogni Paese.

Richiedi un’organizzazione verificata

Nella console imposti Richiedi un’organizzazione verificata su Verifica avviata o Verificata, oppure lo chieda per singola richiesta con acr_values=urn:dazr:org:verification-started o acr_values=urn:dazr:org:verified (vale la più rigorosa delle due). La Sua app deve anche richiedere lo scope organisations.

L’impostazione Richiedi un’organizzazione verificata nella console sviluppatori: non richiesta, verifica avviata o verificata

Chi non ha un’organizzazione idonea la completa nello stesso accesso: il nome, l’organizzazione (con la partita IVA controllata in VIES), poi la verifica. Può firmare subito, farsi inviare la dichiarazione per email o indicare un’altra persona che firma. Poi seleziona l’organizzazione nella schermata di consenso (si possono selezionare solo organizzazioni idonee) e torna al Suo URI di reindirizzamento.

Se deve ancora firmare qualcun altro, la persona torna con stato pending, anche se ha chiesto Verificata: riceve un codice, il claim dice pending e l’acr dell’ID token è urn:dazr:org:verification-started invece di urn:dazr:org:verified. Decida sempre in base a verification.status, mai sul fatto che l’accesso sia riuscito. Con prompt=none riceve interaction_required quando il requisito non è soddisfatto.

Le modifiche all’impostazione valgono dal prossimo accesso. Chi ha già effettuato l’accesso non viene disconnesso: le risposte di refresh, l’endpoint userinfo e i webhook riportano sempre lo stato attuale, quindi li usi per reagire alle sessioni esistenti.

Webhook

Aggiunga un URL del webhook (https) nella console. Vede il segreto di firma una sola volta; può sostituirlo. Dazr invia organisation.verification.updated quando un’organizzazione che uno dei Suoi utenti ha condiviso con la Sua app diventa pending, verified, failed o unverified. Le app che non hanno mai ricevuto un’organizzazione tramite consenso non ne sanno nulla.

POST /your/webhook
Content-Type: application/json
Dazr-Event: organisation.verification.updated
Dazr-Delivery: dlv_8Fq2…
Dazr-Signature: t=1791021600,v1=5e0c…

{ "id": "evt_…", "type": "organisation.verification.updated", "created": 1791021600,
  "data": { "organisation": { "id": "org_3k9x2m0q8w1v5t7a", "name": "Conti Logistica S.r.l.", "country": "IT" },
            "status": "verified", "method": "qes_org", "authority": "certificate", "verified_at": 1791021598,
            "report_url": "https://identity.dazr.eu/oauth/verification-report?org=org_3k9x2m0q8w1v5t7a",
            "subjects": ["Xo1c…"] } }

status è pending, verified, failed o unverified. subjects sono i valori sub, nella Sua app, delle persone che hanno condiviso questa organizzazione con essa. Controlli la firma prima di fidarsi del contenuto:

import crypto from 'node:crypto';
// raw = the request body exactly as received (a string), header = the Dazr-Signature header
function verifyDazrSignature(raw, header, secret) {
  const m = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(header || '');
  if (!m || Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false; // reject old deliveries
  const want = crypto.createHmac('sha256', secret).update(m[1] + '.' + raw).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(want), Buffer.from(m[2]));
}

Risponda con un 2xx entro 8 secondi. Altrimenti Dazr riprova dopo circa 5 minuti, 30 minuti, 2, 6, 12 e 24 ore, poi segna la consegna come non riuscita. Ogni tentativo ha lo stesso ID Dazr-Delivery, quindi ignori i duplicati. La console elenca le consegne recenti, può reinviarne una e può inviare un evento di prova (webhook.test). Funziona anche interrogare periodicamente l’endpoint userinfo.

Organizzazioni e ruoli nella Sua app

In un portale per clienti aziendali, colleghi ogni organizzazione di Dazr a un account cliente (un tenant) nella Sua app, e il ruolo della persona in quell’organizzazione a un ruolo nella Sua app.

  1. Richieda lo scope organisations. Ogni organizzazione che la persona seleziona arriva con il suo id, role (owner, admin o member) e verification.
  2. Usi come chiave del tenant organisations[].id, mai il nome o la partita IVA: possono cambiare.
  3. Colleghi il ruolo, per esempio owner e admin al Suo ruolo di amministratore e member al Suo ruolo utente. Lo rilegga a ogni accesso e a ogni rinnovo del token: i ruoli cambiano e le persone se ne vanno.
  4. Sblocchi le funzioni aziendali solo quando verification.status è verified, o kyb.status è approved dove Le serve la verifica aziendale.
// claims: the ID token claims or the user info response
const ROLE = { owner: 'tenant_admin', admin: 'tenant_admin', member: 'tenant_user' };

const memberships = (claims.organisations || []).map((o) => ({
  tenantId: o.id,                              // e.g. org_3k9x2m0q8w1v5t7a
  role: ROLE[o.role] || 'tenant_user',
  verified: o.verification?.status === 'verified',
  businessVerified: o.kyb?.status === 'approved',
}));

Con Keycloak

Quando Keycloak fa da broker per Dazr Identity (veda la guida a Keycloak), aggiunga i mapper nella scheda Mappers dell’identity provider, con sync mode Force. Keycloak legge questi percorsi dalla risposta user info, e un percorso può indicare una posizione in una lista: organisations[0] è la prima organizzazione selezionata dalla persona. Per un portale con un account cliente per persona basta; se le persone lavorano per più organizzazioni, le faccia selezionare una sola, o legga l’elenco completo nella Sua app.

Tipo di mapperClaimRisultato
Attribute Importerorganisations[0].idAttributo utente dazr_org_id: la chiave del tenant
Attribute Importerorganisations[0].nameAttributo utente dazr_org_name
Claim to Roleorganisations[0].role, valore del claim ownerRuolo di realm o di client tenant_admin
Claim to Roleorganisations[0].role, valore del claim adminRuolo di realm o di client tenant_admin
Claim to Roleorganisations[0].role, valore del claim memberRuolo di realm o di client tenant_user
Claim to Roleorganisations[0].verification.status, valore del claim verifiedRuolo verified_business

Poi aggiunga un mapper User Attribute per dazr_org_id al client scope della Sua app in Keycloak, così la Sua app riceve la chiave del tenant nei token di Keycloak, accanto ai ruoli.

Verifica aziendale (KYB)

La verifica aziendale, spesso chiamata KYB (know your business), è il livello di garanzia più alto, sopra la verifica dell’organizzazione. Aggiunge il registro delle imprese, un controllo del documento con selfie dal vivo per la persona che agisce per l’azienda (il rappresentante), e il controllo dell’azienda e del rappresentante sulle liste delle sanzioni e delle persone politicamente esposte (PEP). I titolari effettivi non ne fanno parte.

Costa 25 € + IVA per organizzazione, una sola volta. Paga l’organizzazione, oppure la Sua app paga per i suoi clienti con il credito prepagato. Se si ferma prima che venga controllato un documento, il pagamento viene rimborsato per intero.

Verifica aziendale in Dazr Identity su un computer: passo 3 di 5, un grande codice QR per scattare le foto con il telefono, le due foto che seguono e lo stato del telefono in tempo reale
  1. Dati della società. La forma giuridica, e il numero di registro e la sede legale dai dati legali dell’organizzazione, confermati da chi avvia la verifica.
  2. Pagamento. 25 € + IVA tramite Mollie, con fattura nella pagina dell’organizzazione. Quando la Sua app paga con il suo credito prepagato, l’organizzazione salta questo passaggio.
  3. Documento e selfie. Chi avvia la verifica è amministratore o rappresentante legale, oppure ne indica uno, che riceve via email un link con un codice monouso (valido 14 giorni, promemoria dopo 2 e 7 giorni), conferma il proprio ruolo e può aggiungere una procura. Il rappresentante scatta una foto di un passaporto (la pagina con la foto), carta d’identità o permesso di soggiorno (il fronte) e un selfie frontale, dal vivo con la fotocamera della pagina; non si può caricare nulla. Un modello di IA legge il documento; Dazr controlla le date e il nome, e per un passaporto la zona a lettura ottica (cifre di controllo ICAO 9303). Una persona di Dazr confronta il selfie con la foto del documento. Su un computer il passo mostra un codice QR che passa lo scatto a un telefono, e il computer prosegue da solo. Senza fotocamera sul telefono, il rappresentante può prenotare una videochiamata con Dazr (200 € + IVA, rimborsati per intero se Dazr annulla o non offre orari).
  4. Controllo nel registro delle imprese. Nome, stato e amministratori dal registro ufficiale dove è online (Norvegia, Danimarca, Finlandia, Francia, Paesi Bassi, Polonia, Cechia e Regno Unito), altrimenti da un estratto ufficiale di non oltre 3 mesi, che Dazr legge automaticamente.
  5. Controlli su sanzioni e PEP. L’azienda e il rappresentante sulle liste di sanzioni di UE, ONU e OFAC e sulle persone politicamente esposte. Se la banca dati PEP non è disponibile, una ricerca del solo nome su Wikidata dà un’indicazione. L’esito PEP è registrato nel claim e nel report e non blocca mai l’approvazione.
  6. Decisione. Una persona di Dazr confronta il selfie con la foto del documento e decide, con gli esiti delle regole di rischio documentate: mostrano quando il controllo del documento non riesce, un nome compare in una lista di sanzioni, il registro non riporta il rappresentante o l’azienda non è confermata. Chi esamina può approvare, respingere con una motivazione, chiedere all’organizzazione altre informazioni o ripetere un controllo, di solito entro un giorno lavorativo. I casi ad alto rischio richiedono due persone. Nessun caso viene respinto automaticamente.

Le organizzazioni approvate vengono ricontrollate ogni giorno sulle liste delle sanzioni e ogni 30 giorni sullo stato PEP. Una nuova corrispondenza con le sanzioni riporta la verifica in esame; una nuova corrispondenza PEP viene segnalata e la verifica resta approvata. In entrambi i casi la Sua app ne viene informata.

Una verifica aziendale approvata è una prova documentata che un amministratore o un rappresentante legale, di cui sono stati controllati il documento d’identità e un selfie dal vivo, ha confermato la richiesta, che il registro delle imprese o un estratto ufficiale di non oltre 3 mesi mostra l’azienda, e che l’azienda e quella persona sono state controllate sulle liste delle sanzioni e delle persone politicamente esposte. I titolari effettivi non vengono controllati.

Il claim kyb

Ogni organizzazione nel claim organisations contiene kyb, e verification.assurance_level riassume entrambi i livelli: none, basic (organizzazione verificata) o kyb (verifica aziendale approvata).

kyb.statusSignificato
noneNessuna verifica aziendale, oppure l’ultima è stata annullata o è scaduta.
in_progressAvviata: l’organizzazione sta completando i passi.
in_reviewInviata e in esame da Dazr, oppure tornata in esame dopo una nuova corrispondenza nello screening.
approvedApprovata. Solo allora il claim contiene verified_claims.
rejectedNon approvata. L’organizzazione può avviarne una nuova.

Dopo l’approvazione, verified_claims segue il formato OpenID Connect for Identity Assurance:

"kyb": {
  "status": "approved",
  "report_url": "https://identity.dazr.eu/oauth/verification-report?org=org_3k9x2m0q8w1v5t7a",
  "verified_claims": {
    "verification": {
      "trust_framework": "dazr_kyb", "assurance_level": "kyb", "time": "2026-10-06T09:14:03.000Z",
      "verification_process": "kyb_7Tq2…",
      "evidence": [
        { "type": "electronic_record", "check_details": [{ "check_method": "data", "organization": "no-brreg" }] },
        { "type": "document", "check_details": [{ "check_method": "vpip" }, { "check_method": "pvr" }],
          "note": "ID document and a live, front-facing selfie of the representative; beneficial owners are not part of this verification" }
      ]
    },
    "claims": {
      "legal_name": "Fjordline Logistikk AS", "country": "NO", "registration_number": "912345678",
      "beneficial_owners": "not_verified",
      "started_by_representative": false,
      "screening": { "result": "no_match_found", "pep_checked": true, "last_screened_at": "2026-10-06T03:23:00.000Z" },
      "risk_level": "low"
    }
  }
}

beneficial_owners è sempre not_verified: la verifica aziendale riguarda l’azienda e la persona che agisce per lei, non chi la possiede. started_by_representative indica se chi l’ha avviata è anche il rappresentante il cui documento è stato controllato, o se lo ha invitato via email. Il claim non contiene mai nomi, date di nascita o dati dei documenti. Restano nel report di audit, che la Sua app può scaricare per le organizzazioni condivise con lei.

Richiedere la verifica aziendale

Nella console, imposti Richiedi un’organizzazione verificata su Verifica aziendale (KYB), oppure la richieda per singola richiesta con acr_values=urn:dazr:org:kyb. Chi non la ha ancora segue tutti i passi nello stesso accesso, una schermata alla volta, e prosegue nella Sua app appena Dazr l’ha approvata; fino ad allora riceve un’email all’approvazione e accede di nuovo. L’acr dell’ID token è urn:dazr:org:kyb solo dopo l’approvazione di un’organizzazione, quindi controlli sempre kyb.status === 'approved' prima di sbloccare qualcosa che la richiede.

Webhook per la verifica aziendale

Lo stesso evento organisation.verification.updated viene inviato quando cambia lo stato della verifica aziendale, anche dopo un nuovo screening. I dati aggiungono:

"kyb": { "status": "approved", "approved_at": 1791021598, "risk_level": "low" },
"assurance_level": "kyb"

La verifica aziendale da sola

Un’organizzazione può anche avviare da sé la verifica aziendale, su https://identity.dazr.eu/verify/business?org=…, con un link dalla sua pagina in Dazr Identity, senza che un’app la chieda. Il risultato è lo stesso: una verifica per organizzazione, su cui può contare ogni app con cui l’organizzazione è condivisa. Le immagini dei documenti d’identità e dei selfie vengono cancellate 30 giorni dopo la decisione; gli esiti e il report si conservano per 5 anni dalla fine della verifica, come richiedono le norme antiriciclaggio.

Come si decide

Una persona di Dazr decide ogni verifica aziendale, di solito entro un giorno lavorativo, e confronta il selfie con la foto del documento. Esamina il caso più da vicino quando si verifica uno di questi punti:

Tutto il resto viene registrato e non blocca mai l’approvazione. Una possibile persona politicamente esposta (PEP) viene segnalata come screening.pep possible_match nel claim e nel rapporto; se la banca dati PEP non è disponibile, riporta indication_only o not_screened. Se il registro non indica amministratori, authority è declared_by_representative. Decide Lei se serve un’adeguata verifica rafforzata.

Paesi senza registro online

Nei paesi senza registro consultabile in tempo reale, come Italia, Germania, Spagna o Belgio, l’organizzazione carica un estratto ufficiale (una visura camerale, un Handelsregisterauszug, una nota simple). Dazr lo legge automaticamente e verifica ragione sociale, numero di registro, data (non oltre 3 mesi) e amministratori indicati. Se corrisponde, viene approvato come con un registro online; se non corrisponde o non è leggibile, passa a un revisore. In una visura sigillata viene verificato anche il sigillo del registro.

PEP, poteri e segnalazioni nel claim

Campo in verified_claims.claimsSignificato
screening.pepno_match_found, possible_match (segnalato, non bloccante), indication_only (solo una ricerca per nome su Wikidata) o not_screened.
authorityCiò che ha mostrato che il rappresentante può agire: register, extract, dazr_verification o declared_by_representative.
flagsPresente quando c’è qualcosa da guardare: pep_possible_match, high_risk_country.

Rapporti di verifica per gli audit

Per ogni organizzazione condivisa con la Sua app può ottenere un rapporto su come e quando Dazr l’ha verificata, per il Suo fascicolo di audit. Esiste finché l’organizzazione è verificata, e mentre la verifica è in corso, con quanto fatto fino a quel momento.

Un rapporto non contiene mai immagini o numeri di documenti d’identità, codici monouso, l’indirizzo PEC, indirizzi email o indirizzi diversi dalla sede legale.

Report di esempio

Due report di esempio con un’organizzazione e persone inventate, così il Suo team compliance vede cosa riceve. Sono firmati con una chiave di esempio, non con le chiavi di Dazr: li verifichi con la chiave pubblica di esempio qui sotto, mai con il JWKS di produzione.

Ottenere un rapporto

Si autentichi con il client ID e il client secret, come all’endpoint dei token: HTTP Basic (client_secret_basic) o il corpo del form di una POST (client_secret_post). Non metta mai il secret nell’URL. Usi l’id dell’organizzazione dai claim o dai webhook, oppure direttamente il verification.report_url che contengono.

curl -u "$DAZR_CLIENT_ID:$DAZR_CLIENT_SECRET" -o report.pdf \
  "https://identity.dazr.eu/oauth/verification-report?org=org_3k9x2m0q8w1v5t7a&format=pdf&lang=en"
ParametroSignificato
orgL’id dell’organizzazione.
formatpdf (predefinito) o jws, gli stessi dati come JSON firmato.
langLingua del PDF: en (predefinita), nl, it, de, fr, es o pl.
docAl posto del rapporto: declaration, la dichiarazione firmata da chi rappresenta l’organizzazione (solo con firma o sigillo qualificato), oppure extract, la visura camerale.

Si possono ottenere solo le organizzazioni che almeno uno dei Suoi utenti ha condiviso con la Sua app tramite consenso. Qualsiasi altra organizzazione risponde 404, come una che non esiste o non ha una verifica; un client secret sbagliato risponde 401. Le app senza client secret non possono ottenere rapporti. I download hanno un limite di frequenza e ognuno compare, con il nome della Sua app, nell’attività dell’organizzazione per i suoi amministratori. Nella console, la pagina della Sua app elenca le organizzazioni collegate con gli stessi download.

Verificare il JSON firmato

Con format=jws riceve un JWS compatto (ES256, header typ dazr-verification-report+jwt), firmato con le stesse chiavi degli ID token. I claim sono iss, iat, jti (l’ID del documento), sub (l’id dell’organizzazione), aud (il Suo client ID) e report, i dati. Il PDF contiene lo stesso JWS nell’ultima pagina e nei metadati (DazrVerificationReport), così anche un PDF si può verificare offline.

import { createRemoteJWKSet, jwtVerify } from 'jose';

const jwks = createRemoteJWKSet(new URL('https://identity.dazr.eu/oauth/jwks'));
// jws = the response body of format=jws, or the text from the PDF metadata
const { payload } = await jwtVerify(jws, jwks, {
  issuer: 'https://identity.dazr.eu',
  audience: process.env.DAZR_CLIENT_ID,
  typ: 'dazr-verification-report+jwt',
});
console.log(payload.report.verification.status, payload.report.verification.authority);

Far controllare la firma a chi fa l’audit

Per una firma o un sigillo qualificato, doc=declaration restituisce la dichiarazione firmata esattamente come è stata caricata: un PDF firmato (PAdES) o un file .p7m (CAdES). Chi fa l’audit può validarla in modo indipendente con il validatore DSS demo della Commissione europea: carica il file, lascia la politica di validazione predefinita e avvia la validazione. Il risultato mostra se la firma è qualificata (QESig, o QESeal per un sigillo), chi ha firmato e il prestatore di servizi fiduciari dall’elenco di fiducia UE. doc=extract restituisce la visura camerale; una visura sigillata dal registro si valida allo stesso modo.

Il rapporto è una prova per il Suo fascicolo di audit. Le imprese regolamentate restano responsabili della propria adeguata verifica della clientela.

Dazr conserva la dichiarazione firmata, la visura e i dati del rapporto finché l’organizzazione è verificata e per 5 anni dopo la fine della verifica o l’eliminazione dell’organizzazione. Conservi le Sue copie per tutto il tempo richiesto dalle Sue regole.

Chiavi per i rapporti vecchi

I rapporti sono firmati con le stesse chiavi degli ID token, e queste chiavi cambiano. Ogni chiave che ha firmato un rapporto resta pubblicata su https://identity.dazr.eu/oauth/jwks/archive, con dazr_status current, previous o retired, per almeno 5 anni dopo l’ultimo utilizzo. Verifichi un rapporto vecchio con l’archivio quando il suo kid non è più nel JWKS.

Verifica dell’identità (KYC)

Attivi Consenti la verifica dell’identità quando un accesso la richiede nella console, poi chieda una persona verificata con acr_values=urn:dazr:person:kyc. Oppure spunti Richiedi la verifica dell’identità a ogni accesso. Senza nessuna delle due impostazioni, il valore acr viene ignorato e non viene addebitato nulla. Non serve uno scope in più. Durante l’accesso, la persona scatta con il telefono una foto dal vivo del documento e un selfie; un computer mostra un codice QR. Dazr legge il documento, confronta i volti e controlla il nome sulle liste di sanzioni di UE, ONU e OFAC. Una persona di Dazr esamina ogni controllo, di solito entro un giorno lavorativo.

Ogni verifica costa 1,50 € IVA esclusa, dal saldo della Sua organizzazione. La persona non paga mai. Una verifica resta valida 12 mesi. Quando un’altra app la chiede, la persona acconsente su una schermata di consenso invece di scattare nuove foto, e quell’app paga 1,50 €, una volta per verifica. Se la Sua app la chiede di nuovo con prompt=consent, o per un accesso con una verifica che ha già ricevuto, è gratuito.

L’ID token e le user info contengono il claim kyc, e acr è urn:dazr:person:kyc:

"kyc": {
  "verified": true, "verified_at": 1791356184, "valid_until": 1822892184,
  "given_name": "ANNA", "family_name": "LINDQVIST", "birthdate": "1985-03-15",
  "nationality": "NO", "document_country": "NO",
  "sanctions": { "status": "no_match", "screened_at": 1791356184, "lists": ["eu", "un", "ofac"] }
}

sanctions.status è no_match, oppure cleared_by_review quando un nome in lista era simile e un revisore ha stabilito che non è questa persona. Immagini e numeri dei documenti non vengono mai condivisi. Dopo 12 mesi il claim dice "verified": false: la chieda di nuovo.

Le verifiche sono reali e a pagamento anche mentre la Sua app è in test.

Credito

La Sua organizzazione può pagare la verifica aziendale dei Suoi clienti. Nella console apra la Sua app e spunti Paghiamo noi la verifica aziendale dei nostri clienti. Il prezzo viene scalato dal credito della Sua organizzazione: un unico credito per tutte le app dell’organizzazione e per le API Dazr a pagamento. Una verifica costa 25 € IVA esclusa. Se il credito non basta, il cliente paga come al solito e i Suoi amministratori ricevono un’email.

La Sua app paga solo per un accesso che chiede la verifica aziendale, e una volta per organizzazione cliente. Quanto un’app paga al giorno per la verifica dell’identità e aziendale ha un limite: 250 € IVA esclusa, a meno che non lo modifichi nella console in Limite giornaliero per le verifiche. Raggiunto il limite, fino al giorno dopo le nuove verifiche dell’identità vengono rifiutate, i Suoi clienti pagano da sé la verifica aziendale e i Suoi amministratori ricevono un’email.

Modalità di prova

Finché la Sua app non è pubblica, una verifica aziendale avviata da un accesso a quell’app dà un esito di prova. Nessun pagamento, nessuna foto del documento, nessun revisore, e la verifica reale dell’organizzazione non cambia. Le ultime quattro cifre del numero di registro o della partita IVA dell’organizzazione scelgono l’esito:

Ultime quattro cifreEsitokyb.status
0001 o qualsiasi altro numeroApprovataapproved
0002Non approvatarejected
0003Inviata a un revisorein_review
0004Corrispondenza con le sanzioniin_review
0005Scadutanone

Gli esiti di prova contengono test: true nel claim, nel webhook e nel rapporto, e li vede solo la Sua app finché non è pubblica. I numeri di registro sono unici su Dazr, quindi usi il Suo, per esempio un numero KVK olandese come 1234 0002. Dalla console può anche inviare un webhook di prova per ogni esito.

Token e durata

TokenDurata e regole
Codice di autorizzazione60 secondi, monouso, legato al Suo client, all’URI di reindirizzamento e alla challenge PKCE. Usare un codice due volte revoca i token che ha generato.
Access token10 minuti. Un JWT firmato (ES256, typ at+jwt) con aud = il Suo client ID. Lo invii come Authorization: Bearer.
ID token10 minuti. ES256, con iss, sub, aud, exp, iat, auth_time, nonce e amr quando noto.
Refresh tokenSolo con offline_access. Cambia a ogni utilizzo: salvi sempre quello nuovo. Inviare di nuovo un vecchio refresh token revoca l’intero accesso. Scade dopo 30 giorni di inutilizzo e al massimo dopo 180 giorni.

Le chiavi di firma vengono sostituite. Scelga sempre la chiave in base al kid dal JWKS e ricarichi il JWKS quando trova un kid sconosciuto.

Come ha effettuato l’accesso la persona

Il campo amr dell’ID token (RFC 8176) indica come ha effettuato l’accesso la persona: ["otp"] per un codice monouso via email, ["hwk", "user"] per una passkey con verifica dell’utente e ["fed"] per Google o Microsoft.

Lingua

Invii ui_locales con la richiesta di autorizzazione, per esempio ui_locales=de-AT de en. La prima lingua supportata da Dazr viene usata per le schermate di accesso e di consenso. Le lingue supportate sono in ui_locales_supported nel documento di discovery.

Lo scope sign

Lo scope sign nel documento di discovery è solo per la Dazr Sign API. Permette a un’app di inviare documenti da firmare per conto della persona; lo attivi nel portale Dazr Sign. Sign in with Dazr Identity non ne ha bisogno.

Dazr Files API e WebDAV (sola lettura)

La Dazr Files API permette alla Sua app di elencare e scaricare file da Dazr Files, per esempio per farne il backup. È in sola lettura: nessuna richiesta può caricare, modificare, spostare, condividere o eliminare nulla. La attivi per la Sua app nella console, nella pagina dell’app sotto Dazr Files API. Usa la stessa app, lo stesso Client ID e lo stesso secret di Accedi con Dazr Identity, e gli stessi token di accesso.

Ci sono due modi. Un titolare o un amministratore di un’organizzazione approva la Sua app per i file condivisi dell’organizzazione, e il Suo server ottiene token senza una persona (ideale per backup non presidiati). Oppure una persona autorizza la Sua app con lo scope files.read, e l’app legge i file personali di quella persona.

Il riferimento completo, con ogni endpoint, esempi, errori, limiti, il feed delle modifiche e la configurazione WebDAV per rclone e Synology, è nella documentazione della Dazr Files API.

Impostazioni dell’organizzazione che influiscono sull’accesso

Errori

Se client ID e URI di reindirizzamento sono validi, gli errori tornano al Suo URI di reindirizzamento come error, error_description, state e iss: per esempio invalid_request (come PKCE mancante o plain), invalid_scope, unsupported_response_type, access_denied (la persona ha annullato, oppure l’app è in test e la persona non è un membro), login_required, consent_required e interaction_required (con prompt=none, quando manca un’organizzazione verificata richiesta). Con un client sconosciuto o un URI di reindirizzamento non registrato, Dazr mostra una pagina di errore e non reindirizza mai. L’endpoint dei token risponde con errori JSON come invalid_client, invalid_grant e unsupported_grant_type.

Disconnessione

Per disconnettere qualcuno, invii la persona all’endpoint di disconnessione con id_token_hint (o client_id), un eventuale post_logout_redirect_uri registrato nelle impostazioni dell’app e state. Dazr chiede se vuole uscire anche da Dazr Identity su quel dispositivo, poi la rimanda indietro. Revochi all’endpoint di revoca i refresh token che non Le servono più.

Test e messa online

Una nuova app è in fase di test: possono accedere solo i membri della Sua organizzazione e la schermata di consenso lo indica. Per andare online, faccia verificare la Sua organizzazione in Dazr Identity, aggiunga un URI di reindirizzamento https:// e richieda una revisione nella console. Modificare nome, finalità, informativa privacy o dati di un’app online richiede una nuova revisione.

Trasferire un’app a un’altra organizzazione

Un’app può passare a un’altra organizzazione registrata su Dazr, per esempio dopo una cessione o una riorganizzazione. Chi possiede o amministra l’organizzazione avvia il trasferimento con Trasferisci app nelle impostazioni dell’app, in Dazr Identity o nel portale Sign. Chi possiede o amministra l’altra organizzazione accetta o rifiuta entro 14 giorni. Fino ad allora chi invia può annullare e non cambia nulla.

Il pulsante

Usi il testo “Sign in with Dazr Identity” e il logo Dazr come qui sotto. Può modificarne le dimensioni, non il logo, i colori o il testo. Lo colleghi a una Sua route che avvia il flusso.

<a href="/auth/dazr" style="display:inline-flex;align-items:center;gap:10px;height:44px;padding:0 18px;border-radius:22px;background:#18203a;color:#fff;font: 600 15px/1 'Dazr', system-ui, sans-serif;text-decoration:none">
  <svg width="20" height="20" viewBox="0 0 100 100" aria-hidden="true"><path d="M64.133 21.813 A6.634 6.634 0 0 1 66.455 31.054 A2.552 2.552 0 0 0 67.912 34.849 A36.74 36.74 0 0 1 93.010 60.100 A2.654 2.654 0 0 1 88.914 62.984 A44.91 44.91 0 0 0 62.003 54.621 A3.062 3.062 0 0 0 59.161 56.689 A73.49 73.49 0 0 0 56.170 92.578 A2.654 2.654 0 0 1 51.111 94.052 A36.74 36.74 0 0 1 52.093 63.128 A1.225 1.225 0 0 0 52.182 62.260 L48.938 50.153 A1.429 1.429 0 0 0 47.187 49.142 L35.080 52.387 A1.225 1.225 0 0 0 34.373 52.898 A36.74 36.74 0 0 1 8.083 69.210 A2.654 2.654 0 0 1 6.830 64.091 A73.49 73.49 0 0 0 36.416 43.557 A3.062 3.062 0 0 0 36.785 40.062 A44.91 44.91 0 0 0 16.087 20.937 A2.654 2.654 0 0 1 16.536 15.948 A36.74 36.74 0 0 1 50.954 25.058 A2.552 2.552 0 0 0 54.969 24.423 A6.634 6.634 0 0 1 64.133 21.813 Z" fill="#ffffff"/></svg>
  Sign in with Dazr Identity
</a>

Font Dazr. Il pulsante usa il font Dazr, che può usare liberamente secondo la SIL Open Font License. Dove Dazr non è caricato, viene usato il font di sistema. Scarichi il font Dazr (ZIP con file TTF e WOFF2) per ospitarlo sul Suo sito:

/* woff2 files from the ZIP, copied to /fonts/ on your site */
@font-face { font-family: 'Dazr'; font-weight: 400; font-display: swap;
  src: url('/fonts/dazr-regular-latin.woff2') format('woff2'); }
@font-face { font-family: 'Dazr'; font-weight: 700; font-display: swap;
  src: url('/fonts/dazr-bold-latin.woff2') format('woff2'); }
.dazr-signin { font: 600 15px/1 'Dazr', system-ui, sans-serif; }

Un esempio minimo in Node.js

Node 18 o successivo, senza dipendenze. Un’app web server con client secret; per un client pubblico, tolga l’header Authorization e invii client_id nel corpo.

import crypto from 'node:crypto';
const issuer = 'https://identity.dazr.eu';
const clientId = process.env.DAZR_CLIENT_ID;
const clientSecret = process.env.DAZR_CLIENT_SECRET;
const redirectUri = 'https://app.example.eu/auth/dazr/callback';
const b64url = (buf) => Buffer.from(buf).toString('base64url');

// 1. Start: keep verifier, state and nonce in the user's session.
export function start(session) {
  session.verifier = b64url(crypto.randomBytes(32));
  session.state = b64url(crypto.randomBytes(16));
  session.nonce = b64url(crypto.randomBytes(16));
  const challenge = b64url(crypto.createHash('sha256').update(session.verifier).digest());
  return issuer + '/oauth/authorize?' + new URLSearchParams({
    response_type: 'code', client_id: clientId, redirect_uri: redirectUri,
    scope: 'openid profile email', state: session.state, nonce: session.nonce,
    code_challenge: challenge, code_challenge_method: 'S256',
  });
}

// 2. Callback: check state, exchange the code, verify the ID token.
export async function callback(session, query) {
  if (query.error) throw new Error('sign-in failed: ' + query.error);
  if (query.state !== session.state || query.iss !== issuer) throw new Error('state or issuer mismatch');
  const res = await fetch(issuer + '/oauth/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      Authorization: 'Basic ' + Buffer.from(clientId + ':' + clientSecret).toString('base64'),
    },
    body: new URLSearchParams({ grant_type: 'authorization_code', code: query.code, redirect_uri: redirectUri, code_verifier: session.verifier }),
  });
  const tokens = await res.json();
  if (!res.ok) throw new Error(tokens.error);
  const claims = await verifyIdToken(tokens.id_token, session.nonce);
  return { sub: claims.sub, email: claims.email, name: claims.name, tokens };
}

async function verifyIdToken(idToken, nonce) {
  const [h, p, s] = idToken.split('.');
  const header = JSON.parse(Buffer.from(h, 'base64url'));
  const { keys } = await (await fetch(issuer + '/oauth/jwks')).json();
  const jwk = keys.find((k) => k.kid === header.kid);
  if (!jwk || header.alg !== 'ES256') throw new Error('unknown signing key');
  const ok = crypto.verify('sha256', Buffer.from(h + '.' + p),
    { key: crypto.createPublicKey({ key: jwk, format: 'jwk' }), dsaEncoding: 'ieee-p1363' }, Buffer.from(s, 'base64url'));
  const c = JSON.parse(Buffer.from(p, 'base64url'));
  const now = Math.floor(Date.now() / 1000);
  if (!ok || c.iss !== issuer || c.aud !== clientId || c.exp < now - 30 || c.nonce !== nonce) throw new Error('invalid ID token');
  return c;
}

Limiti

Gli endpoint di autorizzazione e dei token hanno un limite di richieste. Se riceve HTTP 429, attenda e riprovi; non riprovi in un ciclo continuo.

EndpointLimite
/oauth/authorize120 richieste al minuto per indirizzo IP
/oauth/token600 richieste al minuto per indirizzo IP, e 300 al minuto per app
/oauth/userinfo1.200 richieste al minuto per indirizzo IP
/oauth/verification-report120 richieste al minuto per indirizzo IP, e 60 all’ora per app
Verifica aziendale6 avvii all’ora per persona, e 10 al giorno per organizzazione
Webhook di prova30 ogni 10 minuti per persona

I Suoi obblighi

La Sua organizzazione è titolare autonomo del trattamento dei dati che riceve. Le Condizioni per sviluppatori di Dazr Identity stabiliscono cosa può farne, come proteggerli e come segnalare le violazioni. Domande: hello@dazr.eu.

Per la Sua revisione legale e di sicurezza: il pacchetto sicurezza e acquisti.