Configurare l'accesso ad Interoperabilità per i servizi SEND

In questo tutorial vedremo in pochi passaggi come puoi configurare l’accesso a Interoperabilità e generare il Voucher per chiamare i servizi SEND.\

1 - Creazione dell’utente tecnico incaricato

La prima cosa che dovrai fare è accedere all’area riservata in produzione (e non di test), e creare l'utente del tecnico incaricato tramite la funzione "Crea Utente", associando ad esso il prodotto "Interoperabilità Collaudo" ed il ruolo "Amministratore":

Questa abilitazione come "Amministratore" viene fornita in ambiente Interoperabilità Collaudo pertanto non impatterà l'ambiente di Produzione.

Per la registrazione dell'utente incaricato sono necessari i dati nome, cognome, codice fiscale ed email.

L'utente del tecnico incaricato dovrà:

Effettuare l'accesso su selfcare di produzione: https://selfcare.pagopa.it/ utilizzando le proprie credenziali SPID associate dall'ente di riferimento al punto precedente.
Selezionare l'Ente di riferimento
Selezionare la card "Interoperabilità"
Selezionare "Collaudo"

A questo punto dovrai cercare l'e-service andando su Fruizione > Catalogo e-service:

Avvia la ricerca dell'e-service di SEND - UAT e clicca su Richiedi fruizione creando una bozza di richiesta dove inserire tutte le informazioni richieste, tra cui gli attributi, che si dividono in:

Attributi certificati: vengono verificati tramite le banche dati delle istituzioni.
Attributi Verificati: vengono verificati dall’erogatore del servizio a seguito dell'invio della documentazione da parte del fruitore.
Attributi Dichiarati: vengono dichiarati da chi effettua la richiesta di fruizione sotto la propria responsabilità

Puoi trovare maggiori dettagli e un videotutorial sugli attributi.

Quando la richiesta di fruizione è stata compilata con successo, clicca su "Inoltra richiesta di fruizione"

Una volta che la richiesta di fruizione è stata inviata, questa verrà esaminata dall'Erogatore che dovrà approvarla. È sempre possibile verificare lo stato delle richieste di fruizione presentate andando su Fruizione > Le tue richieste.

Puoi trovare maggiori dettagli e un videotutorial sulla richiesta di fruizione

3 - Creare una finalità per l’e-service di SEND-UAT

A seguito dell'approvazione della richiesta di fruizione per l'e-service di SEND - UAT è necessario creare una finalità andando su Fruizione > Le tue finalità e cliccando "Aggiungi".

Compilare tutti i dati che appaiono sul Form, in particolare:

e-service da associare: che dovrà corrispondere a quello di SEND - UAT
numero di chiamate stimate API/giorno: corrisponde alla stima di chiamate al giorno che verranno effettuate verso l’erogatore. Questo valore potrà essere aggiornato in seguito e potrebbe essere necessaria l'attivazione manuale da parte dall’erogatore.

Nella pagina successive bisogna compilare la sezione di analisi del rischio ed infine cliccare su "Crea bozza finalità" per pubblicare la finalità.

Puoi trovare maggiori dettagli e un videotutorial sulla creazione di finalità.

4 - Associare un client ad una finalità

Il client è un contenitore di materiale crittografico nel quale vengono inseriti un numero discrezionale di operatori di sicurezza, che sono autorizzati a caricare la chiave pubblica del materiale crittografico in loro possesso.

Per creare un nuovo client bisogna andare nella sezione Fruizione > I tuoi client e-service e cliccando su "Aggiungi"

Compilare tutti i dati che appaiono sul Form, selezionando tra gli operatori quelli abilitati ad operare nel back-office.

Una volta creato un client, sarà possibile associarlo ad una finalità, entrando in Fruizione > Le tue finalità, poi nel tab "Client associati" cliccare su "Aggiungi"\

Infine apparirà un menù a tendina che permette di selezionare i client da associare:

I client possono anche essere riutilizzabili su più finalità e modificati successivamente.

Puoi trovare maggiori dettagli e un videotutorial sul client,

4 - Caricare una chiave pubblica

Prima di caricare una chiave pubblica, entra nella sezione Fruizione > I tuoi client seleziona "Ispeziona" sul client di riferimento ed assicurati che sia presente "IL TOKEN PUÒ ESSERE STACCATO: SI" come segue:

Poi accedi al tab "Chiavi pubbliche" e clicca su "Aggiungi"

Apparirà un pop up che permette di inserire il nome e la chiave pubblica associata al client.

Per generare il materiale crittografico, bisogna aprire il terminale e incollare i comandi che seguono, uno alla volta:

1openssl genrsa -out <nomeChiave>.rsa.pem 2048
2openssl rsa -in <nomeChiave>.rsa.pem -pubout -out <nomeChiave>.rsa.pub
3openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in <nomeChiave>.rsa.pem -out <nomeChiave>.rsa.priv
4

Sostituendo <nomeChiave> con il nome che si vuole dare al file contenente la chiave.

Il comando genererà una coppia di chiave pubblica e privata, ed un certificato che in questo caso non è necessario utilizzare. La chiave pubblica appena ottenuta, deve essere copiata nel riquadro "Chiave pubblica" del pop up del client; quella privata rimarrà in mano all'aderente, che la manterrà al sicuro e la userà per firmare la richiesta per ottenere un voucher dal server autorizzativo di PDND Interoperabilità.

Puoi trovare qui un videotutorial su come generare una chiave pubblica.

5 - Generare un Voucher

A questo punto è necessario generare il Voucher da inserire come Authorization header nelle chiamate verso i servizi B2B di SEND - UAT.

Per prima cosa dovrai costruire una client assertion valida e firmarla con la tua chiave privata (che deve essere l'omologa della chiave pubblica depositata sul client su PDND Interoperabilità del punto sopra) come segue:

Nella prima pagina "Client assertion", potrai selezionare la chiave pubblica di riferimento e generare la client assertion con i comandi script che seguono:

Script di esempio per generare un’asserzione

1# prima di lanciare lo script, pip install jose
2from jose import jwt
3from jose constants import Algorithms
4import datetime
5import argparse
6import uuid
7import os
8def clear()
9is.system(‘clear’)
10

Esempio di utilizzo

1python create_client_assertion.py \
2  --kid=4MS8xEIITr48GB7fCHdOEuTSs5TeBUh2C2BfTgC_BsI \
3  --alg=RS256 \
4  --typ=JWT \
5  --issuer=09c6cce0-0573-4c3c-9c77-525327e52e19 \
6  --subject=09c6cce0-0573-4c3c-9c77-525327e52e19 \
7  --audience=auth.dev.interop.pagopa.it/client-assertion \
8  --purposeId=1659602a-ebe8-4fb5-9585-9465155e51aa \
9  --keyPath=PATH_CHIAVE_PRIVATA
10

Ricorda di modificare la variabile <PATH_CHIAVE_PRIVATA> con il path della chiave privata generata al punto precedente. Per creare la client assertion è possibile utilizzare questo codice.

E' disponibile il corrispettivo codice java della classe per generare la "Client assertion" CreateClientAssertionApp.

Salva l'output ottenuto e vai nella seconda pagina "Stacco access token", dove dovrai lanciare il comando che trovi nella pagina in basso:

Esempio di cURL:

1curl --location --request POST https://auth.dev.interop.pagopa.it/token.oauth2 \
2  --header 'Content-Type: application/x-www-form-urlencoded' \
3  --data-urlencode 'client_id=09c6cce0-0573-4c3c-9c77-525327e52e19' \
4  --data-urlencode 'client_assertion=LA_TUA_CLIENT_ASSERTION' \
5  --data-urlencode 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer' \
6  --data-urlencode 'grant_type=client_credentials'
7

Ricorda di modificare la variabile <LA_TUA_CLIENT_ASSERTION> con l'output ottenuto al punto 1.

Per riprodurre il comando si può anche prendere come esempio questo codice:

Come risposta al comando otterrai una response che contiene access_token, expires_in e token_type.

L'access_token(PDNDVoucher) appena ottenuto corrisponde al Voucher che potrà essere utilizzato nelle chiamate verso i servizi B2B di SEND - UAT inserendolo come Header: "Authorization: Bearer <PDNDVoucher>"

Puoi trovare qui un videotutorial su come ottenere un access token

6 - Chiamare i servizi SEND - UAT

A questo punto per chiamare i servizi PND sarà necessario utilizzare la baseUrl dell'Ambiente UAT: https://api.uat.notifichedigitali.it

Inoltre dovrai generare delle nuove APIKey per l'Ambiente UAT effettuando l'accesso da qui: https://selfcare.uat.notifichedigitali.it/ con le stesse credenziali ottenute in fase di Onboarding, poi selezionare l'Ente di riferimento, fare clic sulla card su Piattaforma Notifiche UAT, e generare le APIKey da utilizzare unitamente al Voucher appena creato.

Hai bisogno di aiuto?

Invia una richiesta di supporto utilizzando SEND - Supporto Enti

SEND - Servizio Notifiche Digitali