7. Infrastruttura del Registro¶
L'ecosistema IT-Wallet opera attraverso un'infrastruttura di registro che fornisce definizioni dati standardizzate, registrazione delle entità e capacità di scoperta delle Credenziali. Il sistema di registro consiste di molteplici componenti interconnessi che supportano il ciclo di vita completo delle operazioni degli Attestati Elettronici dall'onboarding delle entità alla presentazione delle Credenziali.
L'architettura di registro affronta la standardizzazione semantica, la gestione della fiducia federata e i requisiti di scoperta delle Credenziali attraverso componenti di registro specializzati che assicurano interoperabilità e conformità attraverso l'ecosistema.
7.1. Panoramica dell'Architettura del Registro¶
Il Registro del Sistema IT-Wallet comprende sei componenti principali:
Registro dei Claims: Definizioni semantiche standardizzate per attributi individuali delle Credenziali, tipi di dati e regole di validazione.
Registro delle Fonti Autentiche (AS): Catalogo dei fornitori di dati registrati con le loro capacità dichiarate e claims disponibili.
Registro di Federazione: Elenco autorevole delle entità fidate che partecipano alla federazione con le loro configurazioni tecniche.
Catalogo degli Attestati Elettronici: Meccanismo di scoperta pubblico per i tipi di Credenziali disponibili con i loro metadati e informazioni di emissione.
Registro degli Schema: Elenco autorevole degli schemi di Credenziali.
Tassonomia: Sistema di classificazione gerarchico che organizza le Credenziali per dominio e scopo.
Questi componenti di registro sono interconnessi e mantenuti dall'Organismo di Supervisione per garantire coerenza, sicurezza e conformità normativa attraverso l'ecosistema.
7.2. Endpoint di Scoperta del Registro¶
Il Trust Anchor DEVE fornire un meccanismo di scoperta per tutti i componenti di registro attraverso endpoint well-known standardizzati che forniscono metadati e informazioni di scoperta API REST per gestire operazioni complesse come paginazione e filtraggio.
Il Trust Anchor DEVE pubblicare metadati di scoperta del registro all'endpoint .well-known/it-wallet-registry con supporto per la negoziazione del contenuto:
Content-Type Predefinito:
application/jwt(JWT firmato che garantisce autenticità e integrità)Content-Type Alternativo:
application/json(JSON semplice per scopi di sviluppo/debug)
Inoltre, il Registro del Sistema IT-Wallet DEVE usare due pattern di accesso distinti:
API di Registro Dati: DEVONO supportare capacità di paginazione e filtraggio.
Infrastruttura di Fiducia della Federazione: come definito in L'Infrastruttura di Trust.
Di seguito è fornito un esempio non normativo.
GET /.well-known/it-wallet-registry HTTP/1.1
Host: trust-anchor.eid-wallet.example.it
Accept: application/jwt
HTTP/1.1 200 OK
Content-Type: application/jwt
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
GET /.well-known/it-wallet-registry HTTP/1.1
Host: trust-anchor.eid-wallet.example.it
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json
Struttura del payload JWT (decodificato):
{
"registry_version": "1.0",
"last_updated": "2024-03-15T10:30:00Z",
"endpoints": {
"claims_registry": "https://trust-anchor.eid-wallet.example.it/api/v1/claims",
"authentic_sources": "https://trust-anchor.eid-wallet.example.it/api/v1/authentic-sources",
"credential_catalog": "https://trust-anchor.eid-wallet.example.it/api/v1/credential-catalog",
"taxonomy": "https://trust-anchor.eid-wallet.example.it/api/v1/taxonomy",
"schema_registry": "https://trust-anchor.eid-wallet.example.it/api/v1/schemas",
"federation_list": "https://trust-anchor.eid-wallet.example.it/list",
"federation_fetch": "https://trust-anchor.eid-wallet.example.it/fetch",
"federation_resolve": "https://trust-anchor.eid-wallet.example.it/resolve",
"federation_trust_mark_status": "https://trust-anchor.eid-wallet.example.it/trust_mark_status",
"federation_historical_keys": "https://trust-anchor.eid-wallet.example.it/historical-jwks"
},
"content_negotiation": ["application/json", "application/jwt"]
}
7.3. Registro dei Claims¶
Il Registro dei Claims fornisce definizioni semantiche standardizzate per attributi individuali delle Credenziali, tipi di dati e regole di validazione. Questo registro serve come fondamento semantico per la standardizzazione degli attributi delle Credenziali attraverso l'ecosistema IT-Wallet, lavorando in coordinamento con il componente Tassonomia per la classificazione gerarchica.
L'Organismo di Supervisione DEVE mantenere il Registro dei Claims per garantire coerenza semantica e conformità normativa attraverso l'ecosistema. Il registro DEVE contenere:
Claims Standardizzati: Definizioni semantiche per tutti gli attributi delle Credenziali con tipi di dati e regole di validazione.
Mappature di Interoperabilità: Definizioni di alias per claims che usano terminologia diversa tra standard (es. ISO18013-5
place_of_birthmappato al canonicobirth_place).Formati Dati: Tipi di dati standardizzati (string, date, numeric, boolean, email, url, image, array, object) con pattern di validazione.
Il Registro dei Claims DEVE garantire:
Coerenza Semantica: Previene conflitti tra claims duplicati o sovrapposti attraverso l'ecosistema.
Interoperabilità Transfrontaliera: Garantisce conformità UE e interpretazione coerente dei claims.
Validazione degli Schema: Fornisce definizioni autorevoli per la validazione dei claims attraverso tutti gli scenari delle Credenziali.
Allineamento Normativo: Si coordina con il quadro normativo nazionale ed europeo.
Scenari Credential-Agnostic: Supporta scenari dove convenienza dell'utente ed efficienza operativa aziendale sono prioritari rispetto a conformità normativa e tracce di audit.
Nota
Il Registro dei Claims definisce le proprietà semantiche degli attributi individuali, ma NON DEVE specificare capacità di divulgazione selettiva. La divulgazione selettiva dipende dalle implementazioni del formato delle Credenziali (SD-JWT VC, mDoc), dalle configurazioni tecniche dell'emittente e dal contesto di presentazione. Queste capacità sono specificate a livello di tipo di Credenziale all'interno del Catalogo degli Attestati Elettronici e implementate durante i flussi di presentazione delle Credenziali.
7.3.1. Utilizzo del Registro dei Claims¶
Il Registro dei Claims DEVE supportare il ciclo di vita completo dell'ecosistema:
Durante il Processo di Onboarding:
Registrazione AS: Le Fonti Autentiche dichiarano i claims disponibili dal registro standardizzato durante la registrazione delle capacità.
Registrazione CI: Gli Emittenti di Credenziali selezionano le entità AS in base ai claims richiesti e registrano i tipi di Credenziali per la pubblicazione nel catalogo.
Registrazione RP: Le Relying Parties specificano i requisiti di autorizzazione usando domini/scopi per tipi di Credenziali specifici e/o attributi dell'Utente.
Durante le Attività Operative:
Emissione di Credenziali: Le definizioni dei claims garantiscono una rappresentazione dati coerente attraverso diversi tipi di Credenziali.
Richieste di Presentazione: Le RP fanno riferimento ai claims per la validazione dello schema e la verifica dell'autorizzazione in scenari sia credential-specific che credential-agnostic.
Applicazione delle Policy: Le policy di autorizzazione sfruttano le classificazioni dominio/scopo per il controllo degli accessi.
7.3.2. Struttura del Registro dei Claims¶
Il Registro dei Claims mantiene definizioni tecniche, indipendenti dalla lingua, per la coerenza semantica attraverso l'ecosistema. Le localizzazioni rivolte all'utente per nomi e descrizioni dei claims sono fornite attraverso i bundle di localizzazione del Catalogo degli Attestati Elettronici, abilitando un supporto multilingue efficiente senza compromettere l'integrità strutturale del registro.
Un esempio non normativo della struttura del Registro dei Claims è fornito di seguito:
{
"registry_version": "1.0",
"claims": {
"given_name": {
"type": "string",
"description": "Person's given name(s) as appears on official documents",
"aliases": ["first_name", "forename", "given_names"],
"max_length": 100,
"validation": {
"pattern": "^[\\p{L}\\s\\-\\'\\.']+$",
"min_length": 1
}
},
"family_name": {
"type": "string",
"description": "Person's family name as appears on official documents",
"aliases": ["last_name", "surname", "family_names"],
"max_length": 100,
"validation": {
"pattern": "^[\\p{L}\\s\\-\\'\\.']+$",
"min_length": 1
}
},
"birth_date": {
"type": "date",
"description": "Date of birth in ISO 8601 format",
"format": "YYYY-MM-DD",
"validation": {
"min_date": "1900-01-01",
"max_date": "current_date"
}
},
"birth_place": {
"type": "string",
"description": "Place of birth as registered in official records",
"aliases": ["place_of_birth"],
"max_length": 100
},
"tax_code": {
"type": "string",
"description": "Italian fiscal identification code (Codice Fiscale)",
"validation": {
"pattern": "^[A-Z]{6}[0-9]{2}[A-Z][0-9]{2}[A-Z][0-9]{3}[A-Z]$",
"length": 16
}
},
"personal_administrative_number": {
"type": "string",
"description": "ANPR unique person identifier",
"validation": {
"pattern": "^[A-Z0-9]+$"
}
},
"document_number": {
"type": "string",
"description": "Document serial number or identifier",
"validation": {
"pattern": "^[A-Z0-9]+$",
"max_length": 20
}
},
"issue_date": {
"type": "date",
"description": "Document issue date",
"format": "YYYY-MM-DD",
"validation": {
"max_date": "current_date"
}
},
"expiry_date": {
"type": "date",
"description": "Document expiry date",
"format": "YYYY-MM-DD",
"validation": {
"min_date": "current_date"
}
},
"driving_privileges": {
"type": "array",
"description": "Array of authorized vehicle categories with details",
"items": {
"type": "object",
"properties": {
"vehicle_category_code": {
"type": "string",
"enum": ["AM", "A1", "A2", "A", "B", "BE", "C", "CE", "D", "DE"]
},
"issue_date": {"type": "date", "format": "YYYY-MM-DD"},
"expiry_date": {"type": "date", "format": "YYYY-MM-DD"},
"restrictions": {"type": "string", "description": "Category-specific restrictions"}
}
}
},
"portrait": {
"type": "string",
"format": "binary",
"description": "Person's photograph as binary string (JPEG or JPEG2000)",
"encoding": "base64",
"content_type": ["image/jpeg", "image/jp2"],
"validation": {
"max_size_bytes": 50000,
"min_width": 100,
"min_height": 100
}
},
"issuing_authority": {
"type": "string",
"description": "Authority that issued the document",
"max_length": 100
},
"issuing_country": {
"type": "string",
"description": "Country code that issued the document",
"validation": {
"pattern": "^[A-Z]{2}$",
"length": 2
}
}
}
}
7.4. Registro delle Fonti Autentiche¶
L'Organismo di Supervisione DEVE mantenere il Registro delle Fonti Autentiche per abilitare l'accesso coordinato ai dati e l'emissione di Credenziali attraverso l'ecosistema. Il Registro AS DEVE contenere almeno:
Informazioni sull'Organizzazione: Dettagli dell'entità legale, stato normativo e ruolo autorevole all'interno di domini specifici.
Capacità dei Dati: Disponibilità dichiarata dei claims che fanno riferimento a definizioni standardizzate dal Registro dei Claims con le corrispondenti classificazioni della Tassonomia.
Metodi di Integrazione: Meccanismi di accesso tecnico (PDND per AS pubblici, API personalizzate per AS privati).
Scopi Previsti: Tipi di Credenziali supportati e contesti aziendali per il coordinamento AS-CI.
Garanzia della Qualità dei Dati: Stato autorevole, frequenza di aggiornamento e capacità di traccia di audit.
Il Registro AS DEVE garantire:
Accesso Coordinato ai Dati: Abilita la scoperta da parte dei CI di dati appropriati dalle Fonti Autentiche per l'emissione di Credenziali.
Integrazione AS-CI: Facilita flussi di lavoro di approvazione e coordinamento dell'accesso ai dati tra entità.
Garanzia della Qualità: Mantiene lo stato autorevole e l'affidabilità dei dati attraverso diversi domini.
Conformità Normativa: Supporta i requisiti di trasparenza della pubblica amministrazione e coordinamento del settore privato.
Nota
Il Registro delle Fonti Autentiche è un registro tecnico e non pubblico che fornisce linee guida per l'Emittente di Credenziali per il provisioning delle Credenziali.
7.4.1. Utilizzo del Registro delle Fonti Autentiche¶
Il Registro AS supporta il coordinamento dell'ecosistema durante tutto il ciclo di vita operativo:
- Durante il Processo di Onboarding:
Auto-Dichiarazione AS: Le Fonti Autentiche registrano le capacità prima che esistano tipi di Credenziali nel catalogo.
Scoperta CI: Gli Emittenti di Credenziali cercano entità AS in base ai claims richiesti e ai tipi di Credenziali previsti.
Coordinamento delle Approvazioni: Le entità AS valutano e approvano le richieste di accesso dei CI per la fornitura di dati.
- Durante le Attività Operative:
Risoluzione della Fonte Dati: I sistemi CI fanno riferimento al Registro AS per l'accesso ai dati in tempo reale durante l'emissione delle Credenziali.
Validazione della Qualità: Le informazioni del Registro AS supportano la verifica dell'origine dei dati e i requisiti di audit.
Gestione dell'Integrazione: Gli endpoint tecnici e i metodi di accesso abilitano la comunicazione standardizzata AS-CI.
7.4.2. Coordinamento AS Pubblici vs Privati¶
L'architettura del Registro AS supporta diversi pattern di coordinamento che riflettono requisiti operativi distinti:
AS della Pubblica Amministrazione (Integrazione Standardizzata): Le entità governative forniscono dati autorevoli attraverso meccanismi regolamentati:
Integrazione PDND:
"integration_method": "pdnd_eservice"per l'accesso standardizzato ai dati governativi.Conformità Normativa: Requisiti di trasparenza completi con pubblicazione nel catalogo pubblico.
Requisiti di Audit: Tracciabilità completa per i processi di emissione di Credenziali governative.
AS del Settore Privato (Integrazione Flessibile): Le entità private forniscono dati specializzati attraverso accordi personalizzati:
API Personalizzate:
"integration_method": "custom_api"per pattern di accesso ai dati specifici dell'azienda.Divulgazione Selettiva: Visibilità pubblica limitata con flussi di lavoro di approvazione specifici per CI.
Flessibilità Aziendale: Integrazione su misura che supporta diversi casi d'uso del settore privato.
Questo approccio abilita sia la trasparenza normativa per la pubblica amministrazione che la flessibilità aziendale per le entità del settore privato mantenendo l'accesso coordinato ai dati attraverso l'ecosistema.
7.4.3. Struttura del Registro AS¶
Durante la registrazione, le Fonti Autentiche dichiarano le loro capacità prima che esistano tipi di Credenziali nel catalogo. Questa dichiarazione stabilisce le fondamenta per la successiva registrazione CI e creazione dei tipi di Credenziali.
7.4.3.1. Schema dell'Identificatore Univoco AS¶
A ciascuna Fonte Autentica DEVE essere assegnato un identificatore univoco che segue lo schema URL HTTPS definito di seguito. Questo identificatore è usato per fare riferimento alle entità AS attraverso il sistema di registro e nel Catalogo degli Attestati Elettronici, garantendo coerenza con i pattern di identificazione delle entità OpenID Federation.
Schema dell'Identificatore AS:
https://{organization_domain}[/{optional_path}]
Componenti dello Schema:
organization_domain: Dominio DNS controllato dall'organizzazione
optional_path: Componente di percorso aggiuntivo per servizi o dipartimenti specifici
L'identificatore AS DEVE seguire queste regole normative:
Protocollo HTTPS: DEVE usare lo schema HTTPS per la sicurezza e la verifica della fiducia
Proprietà del Dominio: L'organizzazione DEVE controllare il dominio DNS usato nell'identificatore
Univocità: Garantita attraverso l'univocità del namespace DNS
Stabilità: DOVREBBE rimanere stabile nel tempo per evitare la rottura dei riferimenti
Risolvibilità: L'URL DOVREBBE essere risolvibile (anche se non è richiesto servire contenuto)
Esempi di identificatori AS conformi:
https://motorizzazione.gov.example: Pubblico - Ministero dei Trasporti, Dip. Motorizzazione
https://registry.anpr.example: Pubblico - Anagrafe Nazionale della Popolazione Residente
https://api.bank.example/auth-source: Privato - Servizi Finanziari Banca di Esempio
7.4.3.2. Parametri del Registro delle Fonti Autentiche¶
Il Registro delle Fonti Autentiche DEVE contenere i seguenti parametri per ciascuna Fonte Autentica registrata:
Nome del Campo |
Descrizione |
|---|---|
version |
RICHIESTO. La versione del Registro delle Fonti Autentiche (es., |
last_modified |
RICHIESTO. Il timestamp che indica quando l'elenco è stato aggiornato l'ultima volta (es., |
authentic_sources |
RICHIESTO. Un Array JSON dove ogni elemento è un Oggetto JSON che rappresenta un'entità Fonte Autentica. Ogni oggetto contiene i parametri definiti nella tabella "Parametri delle Fonti Autentiche" sottostante, inclusi identificazione dell'entità, informazioni organizzative, capacità dei dati e metodi di integrazione. |
Parametro |
Tipo |
Descrizione |
|---|---|---|
entity_id |
string |
RICHIESTO. Identificatore univoco che segue lo schema normativo: |
organization_info |
JSON object |
RICHIESTO. Dettagli dell'entità legale e metadati organizzativi. |
organization_info.organization_name |
string |
RICHIESTO. Nome legale dell'organizzazione. |
organization_info.organization_type |
string |
RICHIESTO. Classificazione dell'entità: |
organization_info.ipa_code |
string |
RICHIESTO solo per AS Pubblici. Codice di registrazione IPA per entità governative. |
organization_info.legal_identifier |
string |
RICHIESTO. Identificatore di registrazione legale (Codice Fiscale/Partita IVA, o identificatore nazionale equivalente per entità straniere). |
organization_info.homepage_uri |
string |
RICHIESTO. URL che punta alla homepage dell'organizzazione. |
organization_info.contacts |
String Array |
RICHIESTO. Array di indirizzi email di contatto tecnici/amministrativi. |
organization_info.policy_uri |
string |
RICHIESTO. URL al documento della politica sulla privacy. |
organization_info.tos_uri |
string |
RICHIESTO solo per AS Privati. URL al documento dei termini di servizio. |
organization_info.organization_country |
string |
RICHIESTO. Codice paese a due lettere ISO 3166-1 alpha-2 dell'organizzazione. |
organization_info.logo_uri |
string |
OPZIONALE. URL all'immagine del logo dell'organizzazione. |
organization_info.logo_uri#integrity |
string |
CONDIZIONALE. Digest crittografico della risorsa immagine del logo per la verifica dell'integrità. RICHIESTO se |
organization_info.logo_uri_extended |
string |
RICHIESTO. URL all'immagine del logo esteso dell'organizzazione. |
organization_info.logo_uri_extended#integrity |
string |
CONDIZIONALE. Digest crittografico della risorsa immagine del logo esteso per la verifica dell'integrità. RICHIESTO se |
data_capabilities |
JSON Objects Array |
RICHIESTO. Array contenente specifiche delle capacità dei dati. |
data_capabilities[].dataset_id |
string |
RICHIESTO. L'identificatore univoco del dataset nell'ambito della Fonte Autentica, che PUÒ essere usato come parametro di query per il servizio |
data_capabilities[].data_origin |
string |
OPZIONALE. Nome leggibile dall'uomo dell'origine dati specifica o del dipartimento che fornisce i dati. |
data_capabilities[].domains |
String Array |
RICHIESTO. Dominio della tassonomia (es., |
data_capabilities[].intended_purposes |
String Array |
RICHIESTO. Scopi aziendali serviti (es., |
data_capabilities[].available_claims |
String Array |
RICHIESTO. Claims disponibili da questa capacità di dati. |
data_capabilities[].available_claims.claim_name |
string |
RICHIESTO. Contiene il nome del claim. |
data_capabilities[].available_claims.order |
number |
RICHIESTO. Definisce l'ordine in cui l'informazione verrebbe mostrata. |
data_capabilities[].available_claims.mandatory |
boolean |
RICHIESTO. Definisce se un claim è sempre disponibile o no. |
data_capabilities[].integration_method |
string |
RICHIESTO. Framework di autorizzazione usato per l'accesso ai dati. DEVE essere |
data_capabilities[].integration_endpoint |
string |
RICHIESTO. Punto di accesso al servizio (endpoint PDND per AS Pubblici, endpoint API per AS Privati). |
data_capabilities[].api_specification |
string |
RICHIESTO. URL al documento di specifica OAS3 per questa capacità di dati. |
data_capabilities[].data_provision |
JSON object |
OPZIONALE. Capacità di fornitura dati e specifiche dei tempi. |
data_capabilities[].data_provision.immediate_flow |
boolean |
RICHIESTO. Indica se la Fonte Autentica supporta la fornitura immediata di dati. |
data_capabilities[].data_provision.deferred_flow |
boolean |
RICHIESTO. Indica se la Fonte Autentica supporta la fornitura differita di dati. |
data_capabilities[].data_provision.max_response_time_minutes |
integer |
CONDIZIONALE. Tempo massimo in minuti per la Fonte Autentica per rispondere a una richiesta di fornitura dati differita. RICHIESTO se |
data_capabilities[].data_provision.notification_methods |
String Array |
CONDIZIONALE. Array di metodi di notifica supportati dalla Fonte Autentica per la fornitura dati differita, come |
data_capabilities[].user_information |
string |
OPZIONALE. Una stringa contenente informazioni leggibili dall'uomo sulla Credenziale Digitale rilevanti per l'Utente. Questa stringa DEVE essere fornita dalla Fonte Autentica al Trust Anchor durante l'onboarding e DEVE essere formattata usando il formato Markdown come definito in RFC 7763. La formattazione Markdown può essere testo semplice o una combinazione di testo e link. Ad esempio, se il database della Fonte Autentica contiene solo i dati richiesti per gli attributi della Credenziale Digitale registrati dopo una data specifica, questa informazione DEVE essere trasmessa al Trust Anchor in questa stringa Markdown. |
data_capabilities[].service_documentation |
string |
OPZIONALE. URL che punta alla documentazione del servizio della Fonte Autentica. |
data_capabilities[].update_frequency |
string |
OPZIONALE. Indica con quale frequenza la Fonte Autentica aggiorna i suoi dati. Valori possibili: |
data_capabilities[].logo_uri |
string |
OPZIONALE. URL all'immagine del logo relativa ai dati forniti. |
data_capabilities[].logo_uri#integrity |
string |
CONDIZIONALE. Digest crittografico della risorsa immagine del logo per la verifica dell'integrità. RICHIESTO se |
data_capabilities[].background_image |
JSON object |
OPZIONALE. Oggetto contiene informazioni sull’immagine di sfondo da visualizzare insieme ai dati forniti. L’oggetto include i parametri |
data_capabilities[].watermark_image |
JSON object |
OPZIONALE. Oggetto contiene informazioni sull’immagine di filigrana da visualizzare insieme ai dati forniti. L’oggetto include i parametri |
data_capabilities[].background_color |
string |
OPZIONALE. Stringa che rappresenta il colore di sfondo da visualizzare insieme ai dati forniti |
data_capabilities[].contacts |
String Array |
OPZIONALE. Indirizzi email di contatto del servizio clienti. |
7.4.3.3. Esempio del Registro AS¶
Un esempio non normativo della struttura del Registro AS è fornito di seguito:
{
"version": "1.0",
"last_modified": "2025-03-15T12:00:00Z",
"authentic_sources": [
{
"entity_id": "https://motorizzazione.gov.example",
"organization_info": {
"organization_name_l10n_id": "authentic_source1.name",
"organization_type": "public",
"ipa_code": "m_inf",
"legal_identifier": "80192770587",
"organization_country": "IT",
"homepage_uri": "https://www.gov.example/transport",
"policy_uri": "https://www.gov.example/transport/privacy-policy",
"logo_uri": "https://trust-registry.it-wallet.example.it/logos/{ipa_code}/image.svg",
"logo_uri#integrity": "sha-256-a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3",
"logo_extended_uri": "https://trust-registry.it-wallet.example.it/logos/{ipa_code}/extended-image.svg",
"logo_extended_uri#integrity": "sha-256-a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3",
"contacts": [
"registry@gov.example",
"technical-support@gov.example"
]
},
"data_capabilities": [
{
"dataset_id": "38832801",
"data_origin_l10n_id": "authentic_source1.dataset1.origin",
"domains": [
"IDENTITY",
"AUTHORIZATION"
],
"intended_purposes": [
"DRIVING_LICENSE",
"PERSON_IDENTIFICATION"
],
"available_claims": [
{
"claim_name": "given_name",
"order": 1,
"mandatory": true
},
{
"claim_name": "family_name",
"order": 2,
"mandatory": true
},
{
"claim_name": "birth_date",
"order": 3,
"mandatory": true
},
{
"claim_name": "birth_place",
"order": 4,
"mandatory": false
},
{
"claim_name": "document_number",
"order": 5,
"mandatory": true
},
{
"claim_name": "issue_date",
"order": 6,
"mandatory": true
},
{
"claim_name": "expiry_date",
"order": 7,
"mandatory": true
},
{
"claim_name": "driving_privileges",
"order": 8,
"mandatory": true
},
{
"claim_name": "portrait",
"order": 9,
"mandatory": false
},
{
"claim_name": "un_distinguishing_sign",
"order": 10,
"mandatory": false
},
{
"claim_name": "document_iss_country",
"order": 11,
"mandatory": true
},
{
"claim_name": "document_iss_authority",
"order": 12,
"mandatory": true
}
],
"integration_method": "pdnd",
"integration_endpoint": "https://api.gov.example/transport/driving-license",
"api_specification": "https://docs.gov.example/transport/api-oas3.yaml",
"data_provision": {
"immediate_flow": true,
"deferred_flow": false
},
"user_information_l10n_id": "authentic_source1.dataset1.userinfo",
"service_documentation": "https://docs.gov.example/transport/api-docs",
"update_frequency": "real_time",
"logo_uri": "https://trust-registry.it-wallet.example.it/logos/{dataset_id}/image.svg",
"logo_uri#integrity": "sha-256-b1946ac92492d2347c6235b4d2611184e2a3f8b8c8f8f8e8f8f8f8f8f8f8f8f8",
"contacts": [
"citizen-support@gov.example"
],
"background_image": {
"uri": "https://trust-registry.it-wallet.example.it/images/{dataset_id}/image.svg",
"uri#integrity": "3GGZJH7igkyeprXI9Plm3dQsWMYOeuz0MaEK34PC7sOtLfgeoK9scXOvMeiACF8Tk2WOT36NsYCPduoLyOD1Sg=="
},
"watermark_image": {
"uri": "https://trust-registry.it-wallet.example.it/images/{dataset_id}/imag-watermark.svg",
"uri#integrity": "3GGZJH7igkyeprXI9Plm3dQsWMYOeuz0MaEK34PC7sOtLfgeoK9scXOvMeiACF8Tk2WOT36NsYCPduoLyOD1Sg=="
},
"background_color" : "#12107c"
}
]
},
{
"entity_id": "https://api.bank.example/auth-source",
"organization_info": {
"organization_name_l10n_id": "authentic_source2.name",
"organization_type": "private",
"legal_identifier": "12345678901",
"homepage_uri": "https://www.bank.example",
"contacts": [
"digital-credentials@bank.example",
"api-support@bank.example"
],
"policy_uri": "https://www.bank.example/privacy-policy",
"tos_uri": "https://www.bank.example/terms-of-service",
"organization_country": "IT",
"logo_uri": "https://trust-registry.it-wallet.example.it/logos/{legal_identifier}/image.svg",
"logo_uri#integrity": "sha-256-a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3"
},
"data_capabilities": [
{
"dataset_id": "38854801",
"data_origin_l10n_id": "authentic_source2.dataset1.origin",
"domains": [
"FINANCIAL"
],
"intended_purposes": [
"BANK_ACCOUNT",
"INCOME_CERTIFICATE"
],
"available_claims": [
{
"claim_name": "given_name",
"order": 1,
"mandatory": true
},
{
"claim_name": "family_name",
"order": 2,
"mandatory": true
},
{
"claim_name": "birth_date",
"order": 3,
"mandatory": false
},
{
"claim_name": "tax_code",
"order": 4,
"mandatory": true
},
{
"claim_name": "account_holder_name",
"order": 5,
"mandatory": true
},
{
"claim_name": "iban",
"order": 6,
"mandatory": true
},
{
"claim_name": "account_status",
"order": 7,
"mandatory": false
},
{
"claim_name": "account_opening_date",
"order": 8,
"mandatory": false
},
{
"claim_name": "bank_name",
"order": 9,
"mandatory": true
},
{
"claim_name": "bank_code",
"order": 10,
"mandatory": true
}
],
"integration_method": "oauth2",
"integration_endpoint": "https://api.bank.example/psd2/v1/accounts",
"api_specification": "https://api.bank.example/docs/psd2-openapi.yaml",
"data_provision": {
"immediate_flow": true,
"deferred_flow": false
},
"user_information_l10n_id": "authentic_source2.dataset1.userinfo",
"update_frequency": "daily"
},
{
"dataset_id": "38854802",
"data_origin_l10n_id": "authentic_source2.dataset2.origin",
"domains": [
"FINANCIAL"
],
"intended_purposes": [
"PAYMENT_HISTORY"
],
"available_claims": [
{
"claim_name": "given_name",
"order": 1,
"mandatory": true
},
{
"claim_name": "family_name",
"order": 2,
"mandatory": true
},
{
"claim_name": "tax_code",
"order": 3,
"mandatory": true
},
{
"claim_name": "transaction_history",
"order": 4,
"mandatory": true
},
{
"claim_name": "average_balance",
"order": 5,
"mandatory": false
},
{
"claim_name": "credit_score_indicator",
"order": 6,
"mandatory": false
}
],
"integration_method": "oauth2",
"integration_endpoint": "https://api.bank.example/psd2/v1/transactions",
"api_specification": "https://api.bank.example/docs/psd2-openapi.yaml",
"data_provision": {
"immediate_flow": false,
"deferred_flow": true,
"max_response_time_minutes": 1440,
"notification_methods": [
"push",
"poll"
]
},
"user_information_l10n_id": "authentic_source2.dataset2.userinfo",
"service_documentation": "https://docs.bank.example/psd2-api",
"update_frequency": "weekly"
}
]
}
]
}
Nota
Per una gestione migliore e più efficiente della localizzazione delle informazioni contenute nel Catalogo degli Attestati Elettronici, un'Entità che lo consulta DOVREBBE:
Scaricare la versione base del Catalogo degli Attestati Elettronici (compatta, senza localizzazioni) usando l'endpoint
.well-known/authentic-sources.Determinare la lingua preferita dell'Utente.
Scaricare solo i bundle di localizzazione necessari.
Unire dinamicamente il contenuto localizzato con la struttura del Catalogo degli Attestati Elettronici.
Un esempio non normativo di output di un bundle di localizzazione è fornito di seguito:
{
"authentic_source1.name": "Ministry of Infrastructure and Transport",
"authentic_source1.dataset1.origin": "MIT -- General Directorate for Motorization",
"authentic_source1.dataset1.userinfo": "###### Driving License\nVehicle registration data is available for licenses issued after January 1, 2020. For older licenses, contact the local motorization office.",
"authentic_source2.name": "Example Bank S.p.A.",
"authentic_source2.dataset1.origin": "Example data origin 1",
"authentic_source2.dataset1.userinfo": "###### Information on data availability\nFinancial data access requires customer consent and is subject to PSD2 regulations. Account information is available for active accounts only.",
"...": "..."
}
I bundle di localizzazione DEVONO essere disponibili all'URI specificato nell'attibuto localization_info.bundles_base_uri del Catalogo degli Attestati Elettronici. Ogni bundle locale DEVE essere accessibile seguendo il pattern di denominazione {locale_code}.json, dove {locale_code} è sostituito con il codice locale corrispondente dall'array available_locales.
Un esempio non normativo dell'URI di localizzazione italiana per il bundle sarebbe https://trust-registry.eid-wallet.example.it/.well-known/authentic-sources/it.json.
Le Entità DOVREBBERO verificare l'integrità dei bundle di localizzazione scaricati utilizzando il metodo di digest e i valori specificati nel claim localization_info.integrity. Questo garantisce che i dati di localizzazione non siano stati manomessi durante la trasmissione.
7.4.4. Coordinamento AS-CI¶
Dopo la registrazione AS, il Registro AS abilita gli Emittenti di Credenziali a scoprire entità AS adatte e richiedere l'approvazione dell'integrazione. Questo processo di coordinamento è dettagliato in Processo di Integrazione AS-CI.
7.5. Registro di Federazione¶
Il Registro di Federazione fornisce l'infrastruttura di fiducia crittografica per tutti i partecipanti dell'ecosistema IT-Wallet. Il Registro di Federazione mantiene l'elenco autorevole delle entità fidate e il loro stato operativo usando endpoint specifici della federazione come definito in Endpoint API di Federazione.
7.5.1. Ruolo di Integrazione del Registro¶
All'interno dell'architettura del Registro del Sistema IT-Wallet, il Registro di Federazione serve come livello di validazione della fiducia per:
Autenticazione delle Entità: Valida l'identità crittografica di tutti i partecipanti prima delle operazioni di registro
Verifica della Catena di Fiducia: Fornisce la fondazione crittografica per la validazione delle entità Emittenti di Credenziali, Relying Parties e Fornitori di Wallet
Verifica della Conformità: Mantiene Trust Marks che attestano la conformità normativa e lo stato operativo
7.5.2. Accesso al Registro di Federazione¶
Le operazioni del Registro di Federazione sono accessibili attraverso gli endpoint di federazione del Trust Anchor come dettagliato in Endpoint API di Federazione. L'architettura di scoperta del registro fornisce informazioni sugli endpoint di federazione tramite l'endpoint di scoperta del registro descritto in Endpoint di Scoperta del Registro.
Nota
Gli endpoint di federazione sono disponibili sia attraverso il meccanismo di scoperta del registro (per l'accesso unificato al registro) che attraverso l'Entity Configuration del Trust Anchor a .well-known/openid-federation (per operazioni specifiche della federazione). Entrambe le fonti forniscono gli stessi URL degli endpoint ma servono diversi pattern di scoperta: scoperta del registro per l'orientamento iniziale nell'ecosistema, Entity Configuration per la conformità standard OpenID Federation 1.0.
Per le specifiche tecniche complete dei protocolli di federazione, configurazioni delle entità, meccanismi di valutazione della fiducia e validazione della catena di fiducia, vedere L'Infrastruttura di Trust.
7.6. Catalogo degli Attestati Elettronici¶
Il Catalogo degli Attestati Elettronici è il registro di tutte gli Attestati Elettronici disponibili riconosciute all'interno dell'ecosistema IT-Wallet. È pubblicato dal Trust Anchor e pubblicamente disponibile da tutte le Entità attraverso un endpoint di Federazione specializzato. Agisce come un punto di riferimento unico per tutti gli attori coinvolti nel processo di emissione, verifica e utilizzo degli Attestati Elettronici.
Il Catalogo degli Attestati ElettroniciCatalogo degli Attestati Elettronici mira a:
Facilitare la scoperta degli Attestati Elettronici per gli Utenti.
Standardizzare la descrizione tecnica e funzionale degli Attestati Elettronici.
Abilitare l'interoperabilità tra diversi Emittenti e Relying Parties.
Semplificare il processo di integrazione per Fornitori di Wallet e Relying Parties.
Garantire la fiducia nell'ecosistema attraverso informazioni verificabili e affidabili.
Fornire trasparenza sull'ecosistema degli Attestati Elettronici disponibili.
Le principali Entità coinvolte nel Catalogo degli Attestati Elettronici sono:
Trust Anchor: Gestisce e mantiene il Catalogo degli Attestati Elettronici, garantendone l'autenticità e l'integrità.
Organismo di Supervisione: Interagisce con il Trust Anchor e il Catalogo degli Attestati Elettronici per monitorare la fase di registrazione garantendo sicurezza e privacy secondo le normative nazionali/europee, mantenendo tutte le informazioni affidabili e aggiornate.
Emittenti di Attestati Elettronici: Le entità autorizzate a emettere Attestati Elettronici, registrandole nel Catalogo.
Relying Parties: Usano il Catalogo degli Attestati Elettronici per raccogliere tutte le informazioni necessarie sulgli Attestati Elettronici che intendono richiedere durante la fase di presentazione.
Fornitori di Wallet: Accedono al Catalogo degli Attestati Elettronici per identificare gli Attestati Elettronici disponibili e per recuperare tutte le informazioni necessarie per integrarle nelle loro Soluzioni Wallet.
Utenti: Gli Utenti che usano indirettamente il Catalogo degli Attestati Elettronici attraverso le loro Istanze Wallet per scoprire e richiedere Attestati Elettronici.
Fonti Autentiche: Le Entità che detengono i dati originali che sono attestati nelgli Attestati Elettronici. Forniscono supporto agli Emittenti nella registrazione degli Attestati Elettronici nel Catalogo.
Fig. 7.1 Diagramma Entità-Relazione del Catalogo degli Attestati Elettronici.¶
La seguente tabella riassume le informazioni principali che DEVONO essere fornite dal Catalogo degli Attestati Elettronici:
Informazioni relative a |
Descrizione |
|---|---|
Metadati della Credenziale Digitale |
Informazioni identificative essenziali e caratteristiche della Credenziale Digitale, inclusi:
|
Emittenti di Attestati Elettronici |
Dettagli sull'organizzazione autorizzata a emettere la Credenziale Digitale, come:
|
Fonti Autentiche |
Informazioni sulla fonte dati autorevole. |
Specifica Tecnica |
Dettagli tecnici, inclusi:
|
Termini d'Uso |
Condizioni e limitazioni per l'uso della Credenziale Digitale, come:
|
Il Trust Anchor DEVE pubblicare e mantenere aggiornate tutte le informazioni all'endpoint .well-known del Catalogo degli Attestati Elettronici garantendo affidabilità, autenticità e integrità dei dati. In particolare, il Catalogo degli Attestati Elettronici, i claims e la tassonomia DEVONO essere disponibili attraverso l'endpoint .well-known/credential-catalog.
7.6.1. Gerarchia degli Attestati Elettronici¶
gli Attestati Elettronici riconosciute all'interno dell'ecosistema IT-Wallet sono classificate e standardizzate gerarchicamente secondo i seguenti domini e scopi principali. Scopi aggiuntivi POSSONO essere aggiunti man mano che l'ecosistema IT-Wallet cresce.
Dominio |
Scopo |
Descrizione |
|---|---|---|
IDENTITY |
|
Credenziali che stabiliscono o verificano l'identità di una persona, inclusi documenti di identità fisici e digitali legalmente riconosciuti dalle leggi nazionali. |
AUTHORIZATION |
|
Credenziali che concedono permessi, diritti o autorizzazioni specifici per eseguire determinate attività o accedere ad aree riservate. |
EDUCATION |
|
Credenziali relative a risultati educativi, qualifiche e riconoscimento di formazione professionale. |
HEALTH |
|
Credenziali relative all'accesso sanitario, storia medica, copertura assicurativa e documenti sanitari. |
FINANCIAL |
|
Credenziali che attestano stato finanziario, livelli di reddito, tassazione, informazioni bancarie o situazione economica di individui o famiglie. |
MEMBERSHIP |
|
Credenziali che confermano affiliazione con organizzazioni, partecipazione a programmi o stato di membership. |
ATTESTATION |
|
Credenziali che forniscono dichiarazioni ufficiali, conferme di stato o certificazioni rilasciate da autorità. |
Ogni Credenziale DEVE specificare domini e scopi per abilitare sia Scenari Credential-Specific che Scenari Credential-Agnostic secondo i requisiti della Relying Party e i pattern di richiesta di presentazione:
Scenari Credential-Specific (Primari per Settori Governativi/Regolamentati): Le RP richiedono tipi di Credenziali specifici per requisiti di conformità e audit, includendo ad esempio:
Servizi Governativi:
"vct_values": ["urn:eudi:pid:it:1"]per la verifica dell'identità specifica del PID.Controlli di Polizia:
"docType": "org.iso.18013.5.1.mDL"per la verifica della patente di guida.KYC Bancario: Tipi di Credenziali specifici richiesti dalle normative finanziarie.
Servizi Sanitari:
"vct_values": ["urn:eudi:european_disability_card:it:1"]per l'accesso ai benefici per disabilità conforme all'UE.
Scenari Credential-Agnostic (Tipici per Business Privato): Le RP richiedono claims specifici indipendentemente dalla fonte della Credenziale per efficienza operativa, come:
Consegna E-commerce: Qualsiasi Credenziale, tra quelle a cui è autorizzato ad accedere, contenente
given_name,family_name,addressper la spedizione.Abbonamenti: Qualsiasi Credenziale, tra quelle a cui è autorizzato ad accedere, con
given_name,Personalizzazione del Servizio: Applicazioni aziendali che richiedono dati personali di base senza forti requisiti sulla fonte.
Questo approccio consente:
Autorizzazione basata su policy usando mappature dominio/scopo.
Registrazione RP flessibile supportando sia le esigenze di conformità governativa che i requisiti operativi aziendali.
7.6.2. Struttura del Catalogo degli Attestati Elettronici¶
Il contenuto del Catalogo degli Attestati Elettronici è protetto in un JWS che contiene i seguenti parametri dell'header JOSE:
Header JOSE |
Descrizione |
Riferimento |
|---|---|---|
typ |
RICHIESTO. DEVE essere impostato a |
[RFC 7515 Sezione 4.1.9]. |
alg |
RICHIESTO. Un identificatore di algoritmo di firma digitale come da registro IANA "JSON Web Signature and Encryption Algorithms". DEVE essere uno degli algoritmi supportati nella Sezione Algoritmi Crittografici e NON DEVE essere impostato a |
[RFC 7515 Sezione 4.1.1]. |
kid |
RICHIESTO. Identificatore univoco della chiave pubblica. |
[RFC 7515 Sezione 4.1.4]. |
x5c |
OPZIONALE. Contiene il Certificato di chiave pubblica X.509 o la catena di Certificati [RFC 5280] corrispondente alla chiave usata per firmare digitalmente il JWS. Quando il valore del parametro header kid è presente, DEVE fare riferimento alla stessa chiave pubblica crittografica del foglio usata con il Certificato X.509. |
[RFC 7515 Sezione 4.1.6.]. |
cty |
RICHIESTO. DEVE essere impostato a |
[RFC 7515 Sezione 4.1.6.]. |
Il payload JWS contiene i seguenti parametri:
Nome del Campo |
Descrizione |
|---|---|
version |
RICHIESTO. Versione del formato del Catalogo degli Attestati Elettronici. |
last_modified |
RICHIESTO. Timestamp dell'ultima modifica al Catalogo degli Attestati Elettronici. |
iss |
RICHIESTO. Identificatore dell'emittente del Catalogo degli Attestati Elettronici. |
credentials |
RICHIESTO. Array contenente definizioni di Credenziali Digitali. |
Ogni elemento dell'array credentials contiene almeno le seguenti informazioni:
Nome del Campo |
Descrizione |
|---|---|
version |
RICHIESTO. Versione della definizione della Credenziale Digitale. |
credential_type |
RICHIESTO. Identificatore univoco del tipo di Credenziale Digitale. Per il PID DEVE essere |
credential_name |
RICHIESTO. Nome leggibile dall'uomo della Credenziale Digitale. |
legal_type |
RICHIESTO. Classificazione legale della Credenziale (es., |
restriction_policy |
OPZIONALE. Restrizioni legali sulle Soluzioni Wallet e/o Emittenti di Credenziali autorizzati a richiedere/emettere la Credenziale Digitale.
|
pricing_policy |
OPZIONALE. Informazioni sul prezzo della Credenziale Digitale, inclusi:
|
validity_info |
Informazioni sulla validità della Credenziale Digitale, inclusi almeno:
|
authentication |
RICHIESTO. Requisiti di autenticazione della Credenziale Digitale.
|
purposes |
RICHIESTO. Array di scopi di utilizzo per cui la Credenziale Digitale può essere usata, definendo contesti di utilizzo specifici e claims richiesti per ciascuno scopo, come:
|
issuers |
RICHIESTO. Array di informazioni rilevanti sugli Emittenti di Credenziali autorizzati, inclusi dati amministrativi e tecnici come nome dell'Organizzazione, un riferimento al documento di specifica API e meccanismi di emissione supportati (ad esempio il supporto del flusso differito). |
authentic_sources |
RICHIESTO. Array di oggetti JSON delle Fonti Autentiche che fanno riferimento alle Fonti Autentiche autorizzate. Ogni oggetto DEVE contenere l'identificatore dell'entità AS e l'identificatore specifico della capacità di dati:
|
Nota
L'unione di credential_type e version DEVE essere univoca nel Catalogo delle Credenziali.
L'esempio corrispondente del Catalogo delle Credenziali Digitali decodificato in JSON sia per l'header che per il payload è il seguente:
{
"typ":"JOSE",
"alg":"ES256",
"kid":"e9bc097a-ce51-4036-9562-d2ade882db0d",
"cty":"application/json"
}
{
"version": "1.0",
"last_modified": "2025-03-15T12:00:00Z",
"iss": "https://trust-registry.eid-wallet.example.it",
"credentials": [{
"version": "1.0",
"credential_type": "mDL",
"credential_name_l10n_id": "mDL.name",
"legal_type": "pub-eaa",
"restriction_policy": {
"allowed_wallet_ids": [
"https://wallet-provider.example.org/wallet_solution",
"https://wallet-provider2.example.org/wallet_solution"
],
"allowed_issuer_ids": [
"https://issuer.example.org"
]
},
"pricing_policy": {
"models": [{
"pricing_type": "verification_based",
"price": 0.01,
"currency": "EUR"
}],
"pricing_model_uri": "https://example.com/pricing"
},
"validity_info": {
"max_validity_days": 365,
"status_methods": [
"status_list"
],
"allowed_states": {
"0x00" : "VALID",
"0x01" : "INVALID",
"0x02" : "SUSPENDED",
"0x03" : "UPDATE",
"0x0B" : "ATTRIBUTE_UPDATE"
}
},
"authentication": {
"user_auth_required": true,
"min_loa": "high",
"supported_schemes": [
"it-wallet"
]
},
"purposes": [{
"id": "DRIVING_LICENSE"
},
{
"id": "PERSON_IDENTIFICATION"
}
],
"issuers": [{
"id": "https://issuer.example.org",
"organization_name_l10n_id": "mDL.issuer1.name",
"organization_code": "ci_example_it",
"organization_country": "IT",
"contacts": [
"mailto:informazioni@example.it",
"mailto:protocollo@pec.example.it"
],
"legal_type": "pub-eaa",
"homepage_uri": "https://issuer.example.org",
"logo_uri": "https://issuer.example.org/logo.svg",
"policy_uri": "https://issuer.example.org/privacy",
"tos_uri": "https://issuer.example.org/terms",
"service_documentation": "https://issuer.example.org/.well-known/service-doc",
"issuance_flows": {
"deferred_flow": true,
"max_deferred_issuance_time_minutes": 1440,
"notification_methods": [
"push",
"polling"
]
}
}],
"authentic_sources": [{
"id": "https://motorizzazione.gov.example",
"dataset_id": "38832801"
}]
}]
}
Nota
Per una gestione migliore e più efficiente della localizzazione delle informazioni contenute nel Catalogo degli Attestati Elettronici, un'Entità che lo consulta DOVREBBE:
Scaricare la versione base del Catalogo degli Attestati Elettronici (compatta, senza localizzazioni) usando l'endpoint
.well-known/credential-catalog.Determinare la lingua preferita dell'Utente.
Scaricare solo i bundle di localizzazione necessari.
Unire dinamicamente il contenuto localizzato con la struttura del Catalogo degli Attestati Elettronici.
Un esempio non normativo di output di un bundle di localizzazione è fornito di seguito:
{
"mDL.name": "Driving License",
"mDL.issuer1.name": "Example of Credential Issuer",
"...": "..."
}
I bundle di localizzazione DEVONO essere disponibili all'URI specificato nell'attibuto localization_info.bundles_base_uri del Catalogo degli Attestati Elettronici. Ogni bundle locale DEVE essere accessibile seguendo il pattern di denominazione {locale_code}.json, dove {locale_code} è sostituito con il codice locale corrispondente dall'array available_locales.
Un esempio non normativo dell'URI di localizzazione italiana per il bundle sarebbe https://trust-registry.eid-wallet.example.it/.well-known/credential-catalog/it.json.
Le Entità DOVREBBERO verificare l'integrità dei bundle di localizzazione scaricati utilizzando il metodo di digest e i valori specificati nel claim localization_info.integrity. Questo garantisce che i dati di localizzazione non siano stati manomessi durante la trasmissione.
7.6.3. Decentralizzazione delle Informazioni di Visualizzazione e dei Claims¶
La fonte canonica per le caratteristiche di visualizzazione e la struttura dei claims è determinata dai Metadati dell'Emittente di Credenziali (Entity Configuration).
La logica complessiva per presentare una Credenziale è:
Il Wallet/Relying Party recupera il Catalogo degli Attestati Elettronici leggero per scoprire il credential_type disponibile e l'entity_id dei loro Emittenti di Credenziali.
Recupera i Metadati dell'Emittente di Credenziali completi (Entity Configuration) dall'entity_id scoperto.
I Metadati dell'Emittente di Credenziali DEVONO contenere le caratteristiche di visualizzazione complete (loghi, colori) e le informazioni dettagliate dello schema (tramite link ai Metadati di Tipo appropriati o direttamente nella configurazione). L'Emittente costruisce questi metadati in base ai suggerimenti forniti dalla Fonte Autentica (tramite il Registro AS) e le specifiche dello schema standard (tramite il Registro degli Schema).
7.7. Tassonomia¶
La Tassonomia fornisce le fondamenta semantiche per l'interoperabilità degli Attestati Elettronici mantenendo il vocabolario autorevole per organizzare le Credenziali all'interno dell'ecosistema IT-Wallet. La tassonomia è neutrale rispetto al formato delle Credenziali e ha l'obiettivo di facilitare le integrazioni degli Attestati Elettronici nelle Soluzioni Tecniche IT-Wallet.
La tassonomia fornisce, in una singola risorsa, il sistema di classificazione gerarchica che organizza domini e scopi che possono essere applicati ai tipi di Credenziali, supportando la valutazione delle policy di autorizzazione e la standardizzazione a livello di ecosistema.
Obiettivi della Tassonomia:
Fondamento Semantico: Stabilire vocabolario standardizzato per domini e scopi in tutto l'ecosistema
Framework delle Policy: Abilitare decisioni di autorizzazione strutturate basate sulla classificazione gerarchica
Interoperabilità: Garantire interpretazione coerente delle classificazioni delle Credenziali
Estensibilità: Supportare l'evoluzione dell'ecosistema con nuovi domini e scopi
Conformità Transfrontaliera: Allinearsi con i requisiti normativi UE e gli standard internazionali
Struttura della Tassonomia:
La tassonomia mantiene una struttura gerarchica a due livelli:
Domini: Classificazione di livello superiore che rappresenta aree funzionali ampie (ad esempio, IDENTITY, AUTHORIZATION, FINANCIAL)
Scopi: Casi d'uso specifici delle Credenziali all'interno di ogni dominio (ad esempio, PERSON_IDENTIFICATION, DRIVING_LICENSE, BANK_ACCOUNT) per i quali le Credenziali possono essere utilizzate
Supporto alla Localizzazione:
La tassonomia supporta ambienti multilingue attraverso il pattern del suffisso _l10n_id, abilitando una gestione efficiente della localizzazione per interfacce utente e implementazioni transfrontaliere.
Utilizzo della Tassonomia:
Registro degli Attributi: Catalogo degli attributi individuali
Registro AS: Le Fonti Autentiche dichiarano capacità di fornitura dati utilizzando classificazioni della tassonomia
Catalogo degli Attestati Elettronici: I tipi di Credenziali specificano domini e scopi supportati
Policy di Autorizzazione: La valutazione delle policy sfrutta la struttura della tassonomia per decisioni di controllo degli accessi
La tassonomia è accessibile attraverso l'endpoint dedicato della tassonomia come definito nel meccanismo di discovery del registro ed è mantenuta dall'Organismo di Supervisione per garantire conformità normativa e coerenza semantica.
Un esempio non normativo della struttura della Tassonomia è fornito di seguito:
{
"version": "1.0",
"last_modified": "2025-04-10T12:00:00Z",
"id": "urn:taxonomy:it-wallet",
"localization": {
"default_locale": "it",
"available_locales": ["en", "it", "fr", "de"],
"base_uri": "https://trust-registry.eid-wallet.example.it/.well-known/l10n/taxonomy/",
"version": "1.0.0"
},
"name_l10n_id": "taxonomy.name",
"description_l10n_id": "taxonomy.description",
"domains": [
{
"id": "IDENTITY",
"name_l10n_id": "domain.identity.name",
"description_l10n_id": "domain.identity.description",
"purposes": [
{
"id": "PERSON_IDENTIFICATION",
"name_l10n_id": "purpose.person_identification.name",
"description_l10n_id": "purpose.person_identification.description"
},
{
"id": "ELECTRONIC_RESIDENCY",
"name_l10n_id": "purpose.electronic_residency.name",
"description_l10n_id": "purpose.electronic_residency.description"
}
]
},
{
"id": "AUTHORIZATION",
"name_l10n_id": "domain.authorization.name",
"description_l10n_id": "domain.authorization.description",
"purposes": [
{
"id": "DRIVING_LICENSE",
"name_l10n_id": "purpose.driving_license.name",
"description_l10n_id": "purpose.driving_license.description"
},
{
"id": "PROFESSIONAL_LICENSE",
"name_l10n_id": "purpose.professional_license.name",
"description_l10n_id": "purpose.professional_license.description"
},
{
"id": "TRAVEL_DOCUMENT",
"name_l10n_id": "purpose.travel_document.name",
"description_l10n_id": "purpose.travel_document.description"
},
{
"id": "ACCESS_PERMIT",
"name_l10n_id": "purpose.access_permit.name",
"description_l10n_id": "purpose.access_permit.description"
}
]
},
{
"id": "EDUCATION",
"name_l10n_id": "domain.education.name",
"description_l10n_id": "domain.education.description",
"purposes": [
{
"id": "ACADEMIC_DEGREE",
"name_l10n_id": "purpose.academic_degree.name",
"description_l10n_id": "purpose.academic_degree.description"
},
{
"id": "CERTIFICATE",
"name_l10n_id": "purpose.certificate.name",
"description_l10n_id": "purpose.certificate.description"
},
{
"id": "TRAINING_RECOGNITION",
"name_l10n_id": "purpose.training_recognition.name",
"description_l10n_id": "purpose.training_recognition.description"
}
]
},
{
"id": "HEALTH",
"name_l10n_id": "domain.health.name",
"description_l10n_id": "domain.health.description",
"purposes": [
{
"id": "INSURANCE_CARD",
"name_l10n_id": "purpose.insurance_card.name",
"description_l10n_id": "purpose.insurance_card.description"
},
{
"id": "DISABILITY_CARD",
"name_l10n_id": "purpose.disability_card.name",
"description_l10n_id": "purpose.disability_card.description"
},
{
"id": "MEDICAL_PRESCRIPTION",
"name_l10n_id": "purpose.medical_prescription.name",
"description_l10n_id": "purpose.medical_prescription.description"
}
]
},
{
"id": "FINANCIAL",
"name_l10n_id": "domain.financial.name",
"description_l10n_id": "domain.financial.description",
"purposes": [
{
"id": "INCOME_CERTIFICATE",
"name_l10n_id": "purpose.income_certificate.name",
"description_l10n_id": "purpose.income_certificate.description"
},
{
"id": "TAX_STATEMENT",
"name_l10n_id": "purpose.tax_statement.name",
"description_l10n_id": "purpose.tax_statement.description"
},
{
"id": "FAMILY_ECONOMIC_STATUS",
"name_l10n_id": "purpose.family_economic_status.name",
"description_l10n_id": "purpose.family_economic_status.description"
},
{
"id": "BANK_ACCOUNT",
"name_l10n_id": "purpose.bank_account.name",
"description_l10n_id": "purpose.bank_account.description"
},
{
"id": "PAYMENT_HISTORY",
"name_l10n_id": "purpose.payment_history.name",
"description_l10n_id": "purpose.payment_history.description"
}
]
},
{
"id": "MEMBERSHIP",
"name_l10n_id": "domain.membership.name",
"description_l10n_id": "domain.membership.description",
"purposes": [
{
"id": "ASSOCIATION",
"name_l10n_id": "purpose.association.name",
"description_l10n_id": "purpose.association.description"
},
{
"id": "LOYALTY_PROGRAM",
"name_l10n_id": "purpose.loyalty_program.name",
"description_l10n_id": "purpose.loyalty_program.description"
},
{
"id": "CLUB_MEMBERSHIP",
"name_l10n_id": "purpose.club_membership.name",
"description_l10n_id": "purpose.club_membership.description"
}
]
},
{
"id": "ATTESTATION",
"name_l10n_id": "domain.attestation.name",
"description_l10n_id": "domain.attestation.description",
"purposes": [
{
"id": "PUBLIC_STATEMENT",
"name_l10n_id": "purpose.public_statement.name",
"description_l10n_id": "purpose.public_statement.description"
},
{
"id": "CIVIL_STATUS",
"name_l10n_id": "purpose.civil_status.name",
"description_l10n_id": "purpose.civil_status.description"
},
{
"id": "CERTIFICATION",
"name_l10n_id": "purpose.certification.name",
"description_l10n_id": "purpose.certification.description"
}
]
}
]
}
Nota
Per una gestione migliore e più efficiente della localizzazione delle informazioni contenute nel Catalogo degli Attestati Elettronici, un'Entità che lo consulta DOVREBBE:
Scaricare la versione base del Catalogo degli Attestati Elettronici (compatta, senza localizzazioni) usando l'endpoint
.well-known/taxonomy.Determinare la lingua preferita dell'Utente.
Scaricare solo i bundle di localizzazione necessari.
Unire dinamicamente il contenuto localizzato con la struttura del Catalogo degli Attestati Elettronici.
Un esempio non normativo di output di un bundle di localizzazione è fornito di seguito:
{
"domain.identity.name": "Identity",
"domain.identity.description": "Credentials that establish or verify the identity of a person, including physical and digital identity documents legally recognized by national laws.",
"purpose.person_identification.name": "Person identification",
"...": "..."
}
I bundle di localizzazione DEVONO essere disponibili all'URI specificato nell'attibuto localization_info.bundles_base_uri del Catalogo degli Attestati Elettronici. Ogni bundle locale DEVE essere accessibile seguendo il pattern di denominazione {locale_code}.json, dove {locale_code} è sostituito con il codice locale corrispondente dall'array available_locales.
Un esempio non normativo dell'URI di localizzazione italiana per il bundle sarebbe https://trust-registry.eid-wallet.example.it/.well-known/taxonomy/it.json.
Le Entità DOVREBBERO verificare l'integrità dei bundle di localizzazione scaricati utilizzando il metodo di digest e i valori specificati nel claim localization_info.integrity. Questo garantisce che i dati di localizzazione non siano stati manomessi durante la trasmissione.
7.8. Registro degli Schema¶
Il Registro degli Schema è l'inventario autorevole di tutti gli Schema delle Credenziali conosciuti e accettati (JSON Schema per SD-JWT, CBOR Schema per mDOC) all'interno dell'ecosistema IT-Wallet. È gestito dal Trust Anchor e fornisce una singola fonte verificabile per recuperare le specifiche tecniche richieste per analizzare, validare e visualizzare gli Attestati Elettronici.
Obiettivi del Registro degli Schema:
Centralizzazione degli Schema: Fornire un punto di accesso centralizzato per tutti gli schemi tecnici usati dalgli Attestati Elettronici.
Integrità e Autenticità: Garantire l'integrità e l'autenticità dei documenti degli schema attraverso digest crittografici.
Interoperabilità: Facilitare l'integrazione senza soluzione di continuità di Fornitori di Wallet e Relying Parties fornendo versioni di schema coerenti.
Supporto al Ciclo di Vita delle Credenziali: Agire come punto di riferimento verificabile per la validazione dello schema durante l'emissione e la presentazione.
Struttura e Accesso al Registro degli Schema:
Il Registro degli Schema è accessibile tramite l'endpoint di scoperta .well-known/it-wallet-registry sotto il campo schema_registry. Permette la scoperta di URI degli schema e i loro controlli di integrità crittografica.
Nome del Campo |
Descrizione |
|---|---|
version |
RICHIESTO. La versione del Registro degli Schema (es., |
last_modified |
RICHIESTO. Il timestamp che indica quando l'elenco è stato aggiornato l'ultima volta (es., |
schemas |
RICHIESTO. Un Array JSON dove ogni elemento è un Oggetto JSON che rappresenta una definizione di Schema di Credenziale. Ogni oggetto contiene i parametri definiti nella tabella "Parametri della Definizione dello Schema" sottostante, inclusi identificazione dello schema, specifiche del formato, URI e dati di verifica dell'integrità. |
Nome del Campo |
Descrizione |
|---|---|
id |
RICHIESTO. L'identificatore univoco dello schema (es., |
version |
RICHIESTO. La versione della definizione dello schema (es., |
credential_type |
RICHIESTO. L'identificatore univoco del tipo di Credenziale Digitale (es., |
format |
RICHIESTO. Il formato tecnico dello schema (es., |
vct |
CONDIZIONALE. È RICHIESTO se il |
docType |
CONDIZIONALE. È RICHIESTO se il |
schema_uri |
RICHIESTO. L'URI dove può essere recuperato il documento dello schema (es., |
schema_uri#integrity |
RICHIESTO. Digest crittografico del documento dello schema per la verifica dell'integrità. Formato: |
description |
OPZIONALE. Una descrizione leggibile dall'uomo dello schema, che può essere localizzata (es., "Schema tecnico per la mobile Driving License in formato mdoc."). |
Esempio del Registro degli Schema:
Un esempio non normativo del payload del Registro degli Schema:
{
"version": "1.0",
"last_updated": "2025-03-15T12:00:00Z",
"schemas": [
{
"id": "mDL+mso_mdoc+org.iso.18013.5.1.mDL",
"version": "1.0",
"credential_type": "mDL",
"format": "mso_mdoc",
"docType": "org.iso.18013.5.1.mDL",
"schema_uri": "https://trust-registry.it-wallet.example.it/.well-known/schemas/mdoc/mDL",
"schema_uri#integrity": "sha256-c8b708728e4c5756e35c03aeac257ca878d1f717d7b61f621be4d36dbd9b9c16",
"description": "Schema tecnico per la mobile Driving License in formato mdoc."
},
{
"id": "pid+dc+sd-jwt+urn:eudi:pid:it:1",
"version": "1.0",
"credential_type": "pid",
"format": "dc+sd-jwt",
"vct": "urn:eudi:pid:it:1",
"schema_uri": "https://trust-registry.it-wallet.example.it/.well-known/schemas/sd-jwt/pid",
"schema_uri#integrity": "sha256-a1b2c3d4e5f67890...",
"description": "Schema tecnico per la Person Identification Data (PID) in formato SD-JWT."
}
]
}
7.9. Integrazione del Registro e Riferimenti Incrociati¶
I componenti del registro sono interconnessi e lavorano insieme per supportare l'ecosistema completo delle Credenziali:
Registro AS ↔ Tassonomia: Le entità AS dichiarano capacità di fornitura utilizzando classificazioni della tassonomia per la categorizzazione standardizzata.
Registro AS ↔ Catalogo: I tipi di Credenziali fanno riferimento alle capacità AS per la validazione della fonte dati.
Catalogo ↔ Tassonomia: Le voci delle Credenziali specificano domini e scopi dalla tassonomia per discovery e autorizzazione.
Registro della Federazione ↔ Tutti i Componenti: Fornisce validazione del trust crittografico per tutte le operazioni del registro e autenticazione delle entità.
Registro degli Schema ↔ Emittente/RP: Fornisce il collegamento verificabile a tutte le specifiche di formato delle Credenziali conosciute usate nell'ecosistema.
7.10. Utilizzo dell'Infrastruttura di Registro¶
I componenti dell'Infrastruttura di Registro sono progettati per supportare le varie fasi operative dell'ecosistema IT-Wallet, ciascuna coinvolgendo interazioni specifiche tra entità. I principali Percorsi di utilizzo illustrano di seguito le interazioni con l'Infrastruttura di Registro.
7.10.2. Emissione di Credenziali¶
Questo percorso definisce come un Emittente di Credenziali usa l'Infrastruttura di Registro per preparare ed emettere una Credenziale Digitale conforme.
Identificazione dei Requisiti: Il CI consulta il Catalogo degli Attestati Elettronici per i requisiti tecnici del tipo di Credenziale da emettere (es.,
max_validity_days,min_loa).Risoluzione dello Schema e dei Claims:
Il CI consulta il Registro degli Schema per recuperare la specifica tecnica del formato e dello schema (es., JSON Schema per SD-JWT) richiesto dal Catalogo, garantendo validità e integrità tramite l'hash (schema_uri#integrity).
Il CI accede al Registro dei Claims per recuperare le definizioni semantiche standardizzate e i formati dati (tipi di dati) degli attributi necessari (claims).
Recupero dei Dati Autentici:
Il CI consulta il Registro delle Fonti Autentiche (AS) per identificare la Fonte Autentica (AS) autorizzata per il dataset richiesto. Il Registro AS fornisce l'
entity_iddell'AS e i dettagli tecnici dell'interfaccia (integration_endpoint, integration_method).Il CI consulta la specifica dell'endpoint AS per implementare l'integrazione necessaria per recuperare i dati dell'Utente richiesti per popolare la Credenziale Digitale.
Emissione della Credenziale: Il CI usa i dati recuperati, gli schemi validati e i formati specificati per generare e firmare la Credenziale Digitale nel formato corretto (es., SD-JWT o mDOC).
7.10.3. Presentazione e Verifica delle Credenziali¶
Questo percorso descrive come un'Istanza Wallet e una Relying Party (RP) interagiscono con l'Infrastruttura di Registro quando una Credenziale Digitale deve essere presentata da un Utente.
Autorizzazione e Selezione del Wallet:
Il Wallet riceve una Richiesta di Presentazione dall'RP, verifica la validità della richiesta confrontando i claims richiesti con le Policy di Autorizzazione relative all'RP (tramite le definizioni della Tassonomia).
Il Wallet consulta il Catalogo degli Attestati Elettronici per verificare i Domini e Scopi associati ai tipi di Credenziali che detiene, valutando quali Credenziali sono adatte per la richiesta.
Il Wallet verifica se gli attributi richiesti (claims) sono disponibili e autorizzati per la divulgazione in base alla policy della richiesta (scenari Credential-Specific o Credential-Agnostic).
L'Utente autorizza il rilascio degli attributi selezionati, divulgati selettivamente. Il Wallet quindi confeziona e presenta la Credenziale Digitale all'RP.
Scoperta e Integrità:
L'RP riceve la Credenziale Digitale dall'Utente.
L'RP consulta il Registro di Federazione tramite l'endpoint del Trust Anchor (federation_resolve, federation_trust_mark_status) per verificare la fiducia crittografica (Trust Mark) dell'Emittente e del Fornitore di Wallet, come definito nella Sezione L'Infrastruttura di Trust.
L'RP consulta il Registro degli Schema per scaricare lo schema della Credenziale presentata (schema_uri), verificandone l'integrità (schema_uri#integrity).
Validazione dello Schema e della Policy Finale:
L'RP usa lo schema recuperato per validare la struttura della Credenziale e i tipi di dati degli attributi rivelati.
L'RP esegue il controllo finale per garantire che gli attributi presentati siano conformi ai requisiti specifici della richiesta iniziale e della policy di autorizzazione.
Accettazione o Rifiuto: In base alla validazione crittografica, alla conformità dello schema e all'autorizzazione basata su policy, l'RP accetta o rifiuta la Credenziale per l'accesso al servizio.