Fruizione ID_AUTH_REST_01 (PDND)

Le richieste che provengono dagli applicativi interni del dominio e sono dirette verso altre amministrazioni verranno arricchite del token di sicurezza “ModI” previsto dall’operazione invocata, come indicato precedentemente nella sezione ID_AUTH_REST_01 tramite la Piattaforma Digitale Nazionale Dati (PDND).

Nella figura “Fig. 157” viene raffigurato lo scenario di fruizione in cui il trust avviene tramite la PDND.

Di seguito vengono descritti tutti i passi di configurazione specifici per l’implementazione del pattern “ID_AUTH_REST_01” mentre si rimanda alla sezione “Profilo “API Gateway”” per la normale registrazione e configurazione di una fruizione di API.

API

La registrazione della API deve essere effettuata agendo nella sezione «ModI - Sicurezza Messaggio», come indicato in Fig. 158:

• selezionare il “Pattern” «ID_AUTH_REST_01»;

• selezionare una “Generazione Token” di tipo “Authorization PDND” per far si che il Token “ID_AUTH” sia negoziato con la PDND.

Token Policy di Negoziazione

Per la configurazione delle fruizioni con un pattern di sicurezza via PDND è necessario registrare una Token Policy di Negoziazione del tipo descritto nella sezione “Signed JWT (PDND)”.

Di seguito vengono riportati tutte le informazioni da registrare nella policy:

• Tipo: SignedJWT;

• PDND: flag attivato;

• URL: endpoint esposto dalla PDND su cui è possibile richiedere lo stacco del voucher alla PDND (Fig. 159):

  • 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 un e-service del catalogo.

  

• JWT Keystore: parametri di accesso al keystore contenente la chiave privata corrispondente alla chiave pubblica registrata sulla PDND durante la registrazione dell’applicativo client. I parametri variano in funzione del tipo di keystore selezionato:

  • “JKS”, “PKCS12”: deve essere definito il path su filesystem dove risiede il keystore, la password per l’accesso al keystore, l’alias con cui è riferita la chiave privata e la password (Fig. 160);

    

  • “JWK Set”: deve essere definito il path su filesystem dove risiede l’archivio json nel formato “JWK Set” e l’identificativo “kid” (alias) con cui è riferita la chiave privata (Fig. 161);

    

  • “Key Pair”: deve essere definito il path su filesystem dove risiedono la chiave privata e pubblica in formato PEM o DER (sono supportati sia i formati pkcs1 che pkcs8) e la password della chiave privata se cifrata (Fig. 162);

    

  • “Definito nell’applicativo ModI”: il keystore utilizzato per firmare l’asserzione JWT inviata alla PDND sarà quello definito nell’applicativo ModI richiedente (scenario descritto nel seguito di questa sezione);

    

  • “Definito nella fruizione ModI”: il keystore utilizzato per firmare l’asserzione JWT inviata alla PDND sarà quello definito nella fruizione ModI (scenario descritto nel seguito di questa sezione);

    

  • Tipi PKCS11: gli altri tipi disponibili sono quelli corrispondenti ai tipi di keystore PKCS11 registrati (”Device PKCS11”).

• JWT Signature: algoritmo di firma

  

• JWT Header:

  • Type (typ): lasciare il valore “JWT”;

  • Key Id (kid): deve essere indicato l’identificativo univoco (KID) ottenuto al termine della registrazione dell’applicativo client sulla PDND. Può essere fornito tramite una delle seguenti modalità:

    • “Personalizzato”: selezionando la modalità “Personalizzato” è possibile indicarlo puntualmente. Il valore può essere definito come costante o contenere parti dinamiche risolte a runtime dal Gateway (”Valori dinamici”);

      

    • “Definito nell’applicativo ModI”: nel caso in cui è stato indicato un keystore definito nell’applicativo ModI, è possibile selezionare una modalità analoga anche per il KID (Fig. 167).

      

      Questa modalità richiede che oltre al keystore, nell’applicativo ModI richiedente venga abilitata anche la sezione “Authorization OAuth” e venga indicato il KID nel campo “Key Id del Certificato” (Fig. 179).

    • “Definito nella fruizione ModI”: nel caso in cui è stato indicato un keystore definito nella fruizione ModI, è possibile selezionare una modalità analoga anche per il KID (Fig. 168).

      

      Questa modalità richiede che oltre al keystore, nella fruizione ModI venga abilitata anche la sezione “Authorization PDND” e venga indicato il KID nel campo “Key Id del Certificato” (Fig. 177).

• JWT Payload:

  • Client ID, Issuer e Subject: l’identificativo univoco dell’applicativo client (”client_id” o “sub”) ottenuto al termine della registrazione dell’applicativo sulla PDND deve essere configurato nei tre campi indicati tramite una delle seguenti modalità:

    • indicati nella token policy:

      

    • in alternativa nel caso in cui sia stato indicato un keystore definito nell’applicativo ModI, è possibile selezionare una modalità analoga anche per la tripla clientId/issuer/subject (Fig. 170).

      

      Questa modalità richiede che oltre al keystore, nell’applicativo ModI richiedente venga abilitata anche la sezione “Authorization OAuth” e venga indicato il clientId nel campo “Identificativo” (Fig. 179).

    • infine nel caso in cui sia stato indicato un keystore definito nella fruizione ModI, è possibile selezionare una modalità analoga anche per la tripla clientId/issuer/subject (Fig. 171).

      

      Questa modalità richiede che oltre al keystore, nella fruizione ModI venga abilitata anche la sezione “Authorization PDND” e venga indicato il clientId nel campo “Identificativo” (Fig. 168).

  • Gli altri campi presenti nella sezione “JWT Payload” rappresentano (Fig. 172):

    • Audience: indica il servizio di stacco del voucher della PDND. Il valore, fornito dalla PDND, è indipendente dal servizio per cui si vuole richiedere un voucher e varia solamente in funzione dell’ambiente di validazione o produzione della PDND stessa:

      • 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.

    • Identifier: consente di configurare la modalità di valorizzazione del claim “jti” presente all’interno del token di richiesta inviato alla PDND. Si suggerisce di valorizzare il campo con la keyword “${transaction:id}” al fine di utilizzare l’identificativo di transazione della richiesta;

    • Time to Live (secondi): consente di indicare la durate del token di richiesta inviato alla PDND (es. 100 sec);

    • Purpose ID: identificativo univoco della finalità, ottenuto dalla PDND, per cui si intende fruire di un servizio. La modalità di configurazione varia a seconda dello scenario che si desidera supportare come descritto nella sezione “Finalità (purposeId) utilizzata per una fruizione di API”.

    • Informazioni Sessione: consente di valorizzare il claim “sessionInfo” previsto dalla PDND. La valorizzazione può essere statica o formata da parti dinamiche risolte a runtime dal Gateway (per maggiori dettagli Valori dinamici).

    

• Dati Richiesta:

  • Resource: indicare l’audience/url del servizio per cui si vuole richiedere un voucher;

  • Client ID: indicare il medesimo valore inserito nel campo “Client ID” della sezione “JWT Payload”;

  

  Per quanto concerne il campo “Client ID”, nel caso in cui sia stato indicato un keystore definito nell’applicativo ModI, è possibile selezionare una modalità analoga anche per il campo “Client ID” (Fig. 174).

  

  Nel caso invece in cui sia stato indicato un keystore definito nella fruizione ModI, è possibile selezionare una modalità analoga anche per il campo “Client ID” (Fig. 175).

  

Fruizione

Una volta effettuata la registrazione della Token Policy, per utilizzarla in una fruizione è sufficiente associarla al connettore della fruizione come descritto nella sezione Autenticazione Token e mostrato nella figura Fig. 176.

Nel caso sia stata configurata l’opzione “definito nella fruizione ModI” per il keystore, il KID o l’identificativo client nella token policy di negoziazione selezionata è possibile configurare tali parametri nella sezione “ModI - Authorization PDND” come mostrato nella figura Fig. 177.

Maggiori dettagli sulla configurazione del keystore nella fruizione vengono forniti nella sezione “Keystore di firma definito nella fruizione”.

Applicativo Client

La registrazione dell’applicativo avviene come già descritto nella sez. Creazione di un applicativo.

Le ulteriori configurazioni descritte di seguito sono necessarie solamente se si intende associare all’applicativo richiedente il keystore utilizzato per la firma del token di sicurezza. Non sono invece necessari ulteriori passi di configurazione se il keystore viene definito nella fruizione o nella token policy e si rimanda rispettivamente alle sezioni “Keystore di firma definito nella fruizione” e “Keystore di firma definito nella token policy” per ulteriori dettagli di questi scenari.

In questo contesto sarà necessario specificare il dominio «Interno» dell’applicativo e procedere all’inserimento dei dati nel form «ModI - Sicurezza Messaggio - KeyStore» (Fig. 178).

I dati da inserire definiscono il keystore contenente la coppia di chiavi utilizzata per firmare i token di sicurezza:

• Modalità: il keystore può essere fornito tramite differenti modalità

  • “File System”: deve essere fornito il Path assoluto su file system del keystore;

  • “Archivio”: viene effettuato l’upload del keystore;

  • “HSM”: consente di selezionare uno dei tipi di keystore PKCS11 registrati (”Device PKCS11”);

• Tipo: il formato del keystore:

  • “JKS” o “PKCS12” (disponibile con modalità “File System” e “Archivio”): viene richiesta la definizione della password per l’accesso al keystore nel campo Password, l’alias con cui è riferita la chiave privata nel keystore nel campo Alias Chiave Privata e la password della chiave privata nel campo Password Chiave Privata;

  • “JWK Set” (disponibile con modalità “File System”): deve essere definito il path su filesystem dove risiede l’archivio json nel formato “JWK Set” e l’identificativo “kid” (alias) con cui è riferita la chiave privata nel campo Alias Chiave Privata;

  • “Key Pair” (disponibile con modalità “File System”): deve essere definito il path su filesystem dove risiedono la chiave privata e pubblica in formato PEM o DER (sono supportati sia i formati pkcs1 che pkcs8) e la password della chiave privata se cifrata nel campo Password Chiave Privata;

  • Tipi PKCS11 (disponibile con modalità “HSM”): i tipi disponibili sono quelli corrispondenti ai tipi di keystore PKCS11 registrati (”Device PKCS11”).

• Certificato: nel caso di modalità “File System”, con tipi di keystore “JKS” o “PKCS12”, o nel caso di modalità “HSM” consente di caricare il certificato corrispondente alla chiave privata del keystore. Il Certificato, altrimenti disponibile solamente a runtime sui nodi run di GovWay, viene utilizzato sia per motivi di ricerche filtrate sulla console che per consentire l’identificazione dell’applicativo su API erogate da altri soggetti di dominio interno in un contesto MultiTenant (”Multi-Tenant”).

Oltre ai dati che definiscono il keystore, nella sezione “Authorization OAuth”, è possibile definire aspetti che riguardano il KID o l’identificativo client da inserire nella richiesta del voucher alla PDND nel caso sia stata configurata l’opzione “definito nell’applicativo ModI” nella token policy di negoziazione per i suddetti campi, come mostrato nella figura Fig. 179.