API PDND

Introduzione

La PDND mette a disposizione delle API che consentono tra le varie funzionalità:

• GET /keys/{kid}: di ottenere la chiave pubblica rispetto al kid indicato nel parametro della url; questa risorsa viene utilizzata da GovWay per poter validare i token con pattern “INTEGRITY_REST_02” e/o pattern di audit “AUDIT_REST_01” o “AUDIT_REST_02” in cui il trust avviene tramite PDND, in cui l’identificativo kid è presente all’interno del token.

• GET /events/keys: consente di ottenere informazioni relative alle modifiche delle chiavi crittografiche registrate sulla PDND; la risorsa viene utilizzata da GovWay per mantenere aggiornata la cache locale delle chiavi scaricate dalla PDND.

• GET /clients/{clientId}: consente di ottenere le informazioni associate al clientId indicato nel parametro della url; la risorsa viene utilizzata da GovWay per arricchire le informazioni tracciate sul mittente.

• GET /organizations/{organizationId}: consente di ottenere le informazioni associate all’organizzazione indicata nel parametro della url; la risorsa viene utilizzata da GovWay per arricchire le informazioni tracciate sul mittente.

L’endpoint di esposizione delle API e la specifica OpenAPI, come indicato nella sezione API PDND - Dove si trovano?, sono reperibili all’interno della sezione «Fruizione > I tuoi client api interop» e variano in funzione dell’ambiente in cui ci si trova.

Per poter fruire delle API delle PDND deve essere registrato sulla PDND un client di tipo “api interop” caricando il certificato di firma che verrà utilizzato per richiedere il token. Al termina della registrazione si otterrà un identificativo univoco della propria identità (”client_id” o “sub”) e un identificativo associato al certificato caricato (”kid”).

Configurazione di GovWay

Per consentire a GovWay di utilizzare le risorse precedentemente descritte, viene fornita built-in la fruizione con profilo di interoperabilità “ModI” e nome “api-pdnd” (figura Fig. 153) da finalizzare negli aspetti descritti di seguito.

• Endpoint di esposizione delle API della PDND: nella sezione “connettore” deve essere indicata la corretta url di esposizione delle API PDND (figura Fig. 154):

  • ambiente di collaudo: https://api.uat.interop.pagopa.it/1.0

  • ambiente di produzione: https://api.interop.pagopa.it/1.0

  Nota

  Le url indicate potrebbero variare; si raccomanda di ottenere sempre dalla PDND le url aggiornate come indicato nella sezione API PDND - Dove si trovano?.

  

• Token Policy di negoziazione del voucher: nella precedente sezione “connettore” si è potuto vedere come sia stata associata al connettore una Token Policy di Negoziazione del tipo descritto nella sezione “Signed JWT”. La token policy “api-pdnd” riferita (figura Fig. 155) deve essere finalizzata nei seguenti aspetti:

  • Url: deve essere indicato l’endpoint di negoziazione del voucher esposto dalla PDND:

    • ambiente di collaudo: https://auth.uat.interop.pagopa.it/token.oauth2

    • ambiente di produzione: https://auth.interop.pagopa.it/token.oauth2

    Nota

    Le url indicate potrebbero variare; si raccomanda di ottenere sempre dalla PDND le url aggiornate come indicato nella sezione Richiesta di un voucher spendibile presso le API di Interoperabilità dove viene indicato che l’URL dell’endpoint cambia in funzione dell’ambiente e sarà chiaramente visibile sull’interfaccia all’interno del back office.

  • Audience: deve essere indicato il corretto valore atteso dal servizio della PDND, valore che cambia in funzione dell’ambiente:

    • ambiente di collaudo: auth.uat.interop.pagopa.it/client-assertion

    • ambiente di produzione: auth.interop.pagopa.it/client-assertion

    Nota

    I valori indicati potrebbero variare; si raccomanda di ottenere sempre dalla PDND i valori aggiornati.

  

• Materiale crittografico e dati della PDND: nella sezione “ModI” devono essere configurati tutti i parametri relativi al materiale crittografico e ai dati identificativi ottenuti dalla PDND in seguito alla registrazione del client di tipo “api interop” (figura Fig. 156):

  • Key Id (kid) del Certificato: identificativo kid della chiave pubblica;

  • Identificativo: clientId associato alla chiave pubblica;

  • Chiave Privata e Chiave Pubblica: indica il path su file system rispettivamente delle chiavi private e pubbliche in formato PEM o DER (sono supportati sia i formati pkcs1 che pkcs8);

  • Password Chiave Privata: se la chiave privata è cifrata deve essere indicata la password.

  Nota

  Tramite il campo “Tipo” è possibile utilizzare un tipo di archivio differente dalla coppia di chiavi pubblica e privata come un keystore “PKCS12”, “JKS” o un archivio json “JWK”.

  

• Controllo degli Accessi: si può notare come la fruizione riporta uno «stato rosso» che evidenzia una configurazione incompleta nella parte relativa al Controllo degli Accessi. Procedere con la configurazione del Controllo degli Accessi al fine di renderla invocabile secondo la modalità di autenticazione ed autorizzazione desiderata. Le modalità scelte dovranno poi comportare una configurazione adeguata, descritta nel punto successivo, in modo da consentire a GovWay di invocare la fruizione.

• Fruizione dell’API PDND da parte di GovWay: la modalità di invocazione della fruizione viene definita tramite le proprietà presenti nel file «/etc/govway/modipa_local.properties» tutte con prefisso “org.openspcoop2.protocol.modipa.sicurezzaMessaggio.certificati.remoteStore.pdnd.”:

  • baseUrl (obbligatorio): definisce la url invocata per ottenere la chiave pubblica rispetto ad un identificativo kid;

  • connectTimeout e readTimeout (obbligatorio): consentono di impostare rispettivamente i limiti temporali per l’instaurazione di una connessione e la ricezione di una risposta dalla PDND;

  • http.username e http.password (opzionale): se definite GovWay invocherà la fruizione utilizzando le credenziali http basic indicate; la keyword speciale “#none#” è utilizzabile per ridefinire la configurazione allo scopo di disabilitare l’invio delle credenziali.

  • http.header.<nome> (opzionale): consente di inviare http header personalizzati;

  • http.queryParameter.<nome> (opzionale): consente di aggiungere parametri personalizzati alla url invocata;

  • https.keyStore, keyStore.type, keyStore.password, key.alias, key.password (opzionale): le seguenti proprietà consentono di specificare un certificato tls client con cui GovWay invocherà la fruizione delle API PDND.

  • https.hostnameVerifier (opzionale): nel caso in cui la baseUrl indicata sia https consente di attivare o meno la verifica dell’hostname rispetto al CN.

  • https.trustAllCerts (opzionale): nel caso in cui la baseUrl indicata sia https disabilta l’autenticazione del certificato server.

  • https.trustStore, https.trustStore.type, https.trustStore.password, https.trustStore.crl (opzionale): consente di effettuare una autenticazione del certificato server rispetto ai parametri di truststore indicati.

• Pull sulla PDND per ottenere gli eventi relativi alle chiavi: come indicato nella sezione Endpoint di notifica eventi, le API della PDND consentono all’aderente di ottenere una lista di eventi che possono essere utilizzate da GovWay per mantenere aggiornata la cache locale delle chiavi scaricate dalla PDND. Per default la consultazione degli eventi è disabilitata e per abilitarla si deve intervenire sulle proprietà presenti nel file «/etc/govway/govway_local.properties» tutte con prefisso “org.openspcoop2.pdd.gestoreChiaviPDND.”:

  • enabled: impostare a true la proprietà per abilitare la consultazione degli eventi.

  • keys.maxLifeMinutes: indica la vita in minuti di una chiave scaricata dalla PDND e salvata nella cache locale (default: 43200, 30 giorni).

  • events.keys.limit indica il numero massimo di eventi recuperati tramite una singola chiamata alla PDND (default: 100).

  • events.keys.timer.intervalloSecondi: definisce l’intervallo, in secondi, rispetto al quale vengono controllati eventuali nuovi eventi sulla PDND (default: 3600, un’ora).

  • cache.keys.timer.intervalloSecondi: govway dispone di più livelli di cache (che si differenziano se risiedono in RAM o su Database). Questa proprietà definisce l’intervallo, in secondi, rispetto al quale le chiavi presenti nella cache in RAM vengono verificate rispetto alla chiavi presenti nella cache su Database (default: 300, 5 minuti).

• Erogazione: maggiori informazioni sul mittente: le API della PDND consentono anche di ottenere informazioni sull’organizzazione a cui il client afferisce. Tali informazioni possono essere recuperate da GovWay al fine di arricchire le tracce e definire criteri autorizzativi; una volta scaricate vengono mantenute in una cache locale. Per default la consultazione della PDND per ottenere maggiori informazioni sui client è disabilitata e per abilitarla si deve intervenire sulle proprietà presenti nel file «/etc/govway/govway_local.properties» tutte con prefisso “org.openspcoop2.pdd.gestorePDND.”:

  • clientInfo.enabled: impostare a true la proprietà per abilitare la raccolta delle informazioni sul client;

  • clientInfo.maxLifeMinutes: indica la vita in minuti delle informazioni scaricate dalla PDND e salvate nella cache locale (default: 43200, 30 giorni);

  • clients.error.abortTransaction indicazione se far fallire la transazione in caso il recupero delle informazioni sul client fallisca (default: false, vedi Recupero informazioni client tramite API PDND fallito);

  • organizations.error.abortTransaction indicazione se far fallire la transazione in caso il recupero delle informazioni sull’organizzazione fallisca (default: false, vedi Recupero informazioni client tramite API PDND fallito).

  Nota

  La raccolta delle informazioni sul mittente tramite la PDND richiede che la consultazione degli eventi, descritta nel precedente punto, sia stata abilitata nel file «/etc/govway/govway_local.properties» tramite la proprietà “org.openspcoop2.pdd.gestoreChiaviPDND.enabled”