Determinazione AGID n. 71/2025 del 29/04/2025

Regole tecniche per il funzionamento della Federazione SPID OpenID Connect

La determinazione AGID contiene regole tecniche e operative per la Federazione SPID OpenID Connect. Il documento disciplina come le entità della federazione si riconoscono, come pubblicano e validano i metadata, quali endpoint devono esporre e quali requisiti di sicurezza e interoperabilità devono rispettare.

Oggetto e finalità

L’atto è finalizzato ad attuare quanto previsto dalle Linee guida OpenID Connect in SPID, in particolare per mantenere e distribuire i metadata dal Registry SPID a tutti i soggetti della federazione e consentire la configurazione reciproca dei sistemi. Le regole riguardano Fornitori di Servizio/RP, Identity Provider/OP, Attribute Authority/AA e Soggetti Aggregatori/SA.

Quadro generale della Federazione

La Federazione SPID OpenID Connect è descritta come un’infrastruttura fiduciaria costruita su un quadro regolatorio e tecnologico comune. AgID svolge il ruolo di Autorità di Federazione e Trust Anchor, cioè il soggetto che norma il funzionamento, pubblica la configurazione della federazione e le attestazioni di riconoscimento dei partecipanti.

Sono definiti i principali ruoli:

• Trust Anchor: pubblica la configurazione della federazione e le dichiarazioni di riconoscimento.
• Intermediario / Soggetto Aggregatore (SA): facilita l’ingresso nella federazione e può operare per conto dei soggetti aggregati.
• Foglia: entità finale del protocollo, cioè RP e OP.
• Entità: partecipante alla federazione, inclusi Trust Anchor, Intermediari e Foglie.

Configurazione della federazione e adesione

La configurazione della Federazione SPID è pubblicata dal Trust Anchor nella propria Entity Configuration, accessibile tramite il path .well-known/openid-federation. Tutti i partecipanti devono acquisire tale configurazione prima dell’esercizio e mantenerla aggiornata giornalmente.

Per aderire alla federazione, una Foglia deve pubblicare la propria Entity Configuration sul corrispondente endpoint well-known. AgID o un Intermediario effettua i controlli amministrativi e tecnici, registra le chiavi pubbliche della Foglia e rilascia un Trust Mark. La Foglia deve poi incorporare il Trust Mark nella propria Entity Configuration come prova dell’avvenuto onboarding. L’autorità superiore pubblica inoltre l’Entity Statement relativo alla Foglia e può imporre una metadata policy.

Fiducia reciproca e Federation Entity Discovery

La fiducia tra le parti è instaurata tramite la raccolta e validazione di Entity Configuration ed Entity Statement, secondo il processo di Federation Entity Discovery e Trust Chain.

Per gli RP, il processo è semplificato perché non sono ammessi intermediari tra OP e Trust Anchor. L’RP ottiene la lista degli OP dal Trust Anchor, recupera le Entity Configuration degli OP, verifica le firme usando la chiave pubblica pubblicata dalla TA, applica le policy sui metadata e conserva il metadata finale con data di scadenza.

Per gli OP, quando arriva una richiesta da un RP non ancora riconosciuto, si avvia la registrazione automatica del client. L’OP recupera la Entity Configuration del RP, valida i Trust Mark, esamina gli authority_hints, percorre la Trust Chain fino al Trust Anchor, applica la metadata policy e salva il metadata finale. Se non vi è alcun Trust Mark riconoscibile per il profilo richiesto, l’autorizzazione va rifiutata. Se viene superato il massimo di intermediari verticali consentito, il processo si interrompe.

Entity Configuration, Entity Statement e claim principali

Il documento distingue tra:

• Entity Configuration (EC): JWT auto-firmato con la configurazione del soggetto stesso.
• Entity Statement (ES): JWT firmato da una autorità superiore che riconosce un discendente.
• Trust Mark (TM): JWT firmato che attesta il possesso di requisiti o profili di fiducia.

Le EC e gli ES devono contenere i claim comuni previsti, tra cui iss, sub, iat, exp, jwks e metadata. Per le Foglie sono richiesti anche authority_hints e trust_marks. Per AgID/TA sono previsti constraints con max_path_length e trust_mark_issuers. Gli Entity Statement possono contenere anche metadata_policy e trust_marks.

Trust Mark: struttura, validazione e revoca

I Trust Mark sono oggetti JSON firmati che attestano la conformità a specifici profili di fiducia e interoperabilità. In SPID sono obbligatori e fungono da primo filtro per l’instaurazione della fiducia.

Sono definiti:

• i profili supportati per RP, OP, SA e AA;
• i claim obbligatori dei Trust Mark (iss, sub, id, iat, exp), oltre a campi opzionali come logo_uri e ref;
• i claim aggiuntivi specifici, come organization_type, id_code, email, organization_name e, per i SA, sa_profile;
• per le AA, anche policy_uri, tos_uri, claims e service_documentation.

La validazione può essere:

• statica, tramite il certificato dell’emittente, il contenuto del claim sub e la scadenza;
• dinamica, interrogando l’endpoint trust mark status dell’emittente.

La revoca è possibile in qualsiasi momento; in caso di revoca, la validazione dinamica fallisce, mentre quella statica può continuare a risultare positiva fino a rotazione delle chiavi dell’emittente.

Metadata OIDC per OP, RP, TA/SA e AA

Il testo dettaglia i metadata che devono comparire nella Entity Configuration dei diversi soggetti.

Per gli OP:

• metadata federation_entity con dati organizzativi e endpoint federativi;
• metadata openid_provider con requisiti aggiuntivi, tra cui metodi di autenticazione, response types, scopes, grant types, supporto a private_key_jwt, S256, automatic client registration e altri parametri richiesti.

Per gli RP:

• metadata federation_entity con dati organizzativi e endpoint federativi;
• metadata openid_relying_party con requisiti sugli algoritmi di firma/cifratura, token_endpoint_auth_method private_key_jwt e client_registration_types automatic.

Per TA e SA:

• metadata federation_entity con endpoint di fetch, list, resolve e trust mark status, oltre a homepage, policy, logo e contacts.

Per le AA:

• metadata federation_entity;
• metadata oauth_resource;
• se le risorse sono protette, anche oauth_authorization_server.

Metadata policy

TA e Intermediari devono pubblicare una metadata policy per i propri discendenti, applicata a cascata. La policy specifica quali valori o insiemi di valori sono consentiti per i metadata discendenti.

Sono indicate policy minime per:

• TA verso RP: vincoli su jwks, grant types, algoritmi di firma e cifratura, token_endpoint_auth_method e client_registration_types;
• TA verso SA: analoghi vincoli, applicati poi ai RP aggregati;
• SA verso RP: almeno il vincolo sui jwks;
• TA verso OP: un set più ampio di vincoli, compresi response types, scopes, acr_values, subject_types, claims/request parameters e algoritmi supportati.

Soggetti aggregatori

I SA possono operare in modalità:

• Light/trasparente, registrando RP preesistenti e conformi a OIDC-FED;
• Full/proxy, costruendo un’interfaccia di autenticazione e federazione per conto degli aggregati.

Nel caso Full il client_id dell’aggregato incorpora un identificativo tratto dai codici presenti nell’id_code del Trust Mark. Sono descritti anche gli endpoint che il SA può/esprime per gli aggregati, tra cui entity configuration e callback di autorizzazione.

Endpoint di federazione

Tutti i partecipanti devono esporre:

• .well-known/openid-federation per la Entity Configuration;
• resolve entity statement endpoint per pubblicare metadata finali, Trust Mark e Trust Chain già calcolati.

TA e Intermediari devono inoltre esporre:

• fetch entity statement endpoint;
• trust mark status endpoint;
• entity listing endpoint, con il parametro aggiuntivo entity_type come filtro.

Sicurezza, errori, log e chiavi

L’atto disciplina i principali codici di errore federativi, tra cui temporarily_unavailable, invalid_client, unauthorized_client, invalid_request e not_found, con i relativi HTTP status code.

Sono inoltre previsti:

• obbligo di registrare nei log la Trust Chain relativa alla transazione;
• pubblicazione dello storico delle chiavi pubbliche di federazione del TA su /.well-known/openid-federation-jwks;
• regole sugli algoritmi crittografici supportati, con RSA minimo 2048 bit e preferenza per 4096 bit;
• algoritmi obbligatori, raccomandati e vietati per firma, key encryption e content encryption.

Differenze rispetto a OIDC Federation 1.0 e buone pratiche

SPID introduce alcune specificità rispetto allo standard OIDC Federation 1.0:

• supporta solo automatic_client_registration;
• rende obbligatoria l’esposizione dei Trust Mark;
• non supporta alcuni claim negli Entity Statement, che se presenti sono ignorati.

Tra le buone pratiche indicate vi sono:

• usare chiavi separate per OpenID Core e Federation;
• aggiornare i metadata aggiungendo nuove chiavi senza rimuovere immediatamente le vecchie;
• consentire, in caso di indisponibilità temporanea dei servizi, un periodo di grazia fino a 24 ore per l’uso di Trust Chain scadute, con tentativi periodici di rinnovo.

Valutazione complessiva

L’atto ha natura chiaramente regolatoria e tecnica, non meramente gestionale. Introduce uno schema completo e vincolante per l’operatività della Federazione SPID OpenID Connect, con impatti diretti su amministrazioni, fornitori ICT, operatori identity e service provider, in particolare su onboarding, fiducia, metadata, sicurezza e interoperabilità.