Finalità (purposeId) utilizzata per una fruizione di API

Per ottenere un token dalla PDND un applicativo mittente deve aver registrato una finalità che descrive la motivazione per cui vuole richiedere la fruizione del servizio e il numero di richieste giornaliere che intende effettuare. La creazione di una finalità si completa con l’ottenimento di un suo identificativo univoco denominato «purposeId».

Negli scenari di configurazione attuabili su GovWay il purposeId può essere indicato in differenti modi, descritti in questa sezione, a seconda della modalità con cui viene definito il campo “Purpose ID” all’interno della Token Policy di negoziazione con la PDND descritta nei passi di configurazione della sezione Fruizione ID_AUTH_REST_01 (PDND).

Le modalità supportate sono le seguenti:

• statica: il valore del purposeId può essere fornito staticamente nel campo “Purpose ID” della token policy richiedendo quindi la registrazione di una token policy per ogni finalità;

• fornita dal client: il valore può contenere una keyword risolta a runtime in modo da valorizzare il claim “purposeId” con un valore prelevato dai dati della richiesta. Ad esempio se il censimento dei purposeId viene mantenuto a livello applicativo può essere indicato un header HTTP con cui il richiedente può fornire a GovWay il valore da utilizzare (es. ${header:NOME_HEADER_HTTP}). Si rimanda alla sezione “Valori dinamici” per le varie modalità dinamiche utilizzabili;

• proprietà degli oggetti: di seguito vengono invece fornite alcune indicazioni per mantenere la registrazione del purposeId sul registro di GovWay supportando differenti scenari (per maggiori dettagli si rimanda alla sezione Accesso alle proprietà delle entità del Registro):

  • 1-1 con la fruizione: registrazione come proprietà “purposeId” della fruizione e riferito nella token policy tramite il valore “${config:purposeId}”;

  • 1-1 con l’applicativo fruitore: registrazione come proprietà “purposeId” di un applicativo fruitore e riferito nella token policy tramite il valore “${clientApplicationConfig:purposeId}” se l’applicativo viene identificato tramite l”Autenticazione Trasporto, o tramite il valore “${tokenClientApplicationConfig:purposeId}” se l’applicativo viene identificato tramite il clientId presente nel token ottenuto dall”Autenticazione Token;

  • N applicativi fruitore censiti sulla fruzione: registrazione di N proprietà “<clientApplicationName>.purposeId” sulla fruizione, una per ogni applicativo fruitore il cui nome va indicato come prefisso della proprietà (è possibile utilizzare la proprietà senza prefisso come finalità di default); nella token policy deve essere utilizzato il valore “${dynamicConfig:apiSearchByClientApplication(purposeId)}” se gli applicativi vengono identificati tramite l”Autenticazione Trasporto, o il valore “${dynamicConfig:apiSearchByTokenClientApplication(purposeId)}” se vengono identificati tramite il clientId presente nel token ottenuto dall”Autenticazione Token;

  • N fruizioni censite sull’applicativo fruitore: registrazione di N proprietà “<nomeApiImpl>.v<versioneApiImpl>.purposeId” sull’applicativo, una per ogni fruizione di API che l’applicativo fruisce indicando il nome come prefisso della proprietà (è possibile utilizzare la proprietà senza prefisso come finalità di default); nella token policy deve essere utilizzato il valore “${dynamicConfig:clientApplicationSearch(purposeId)}” se l’applicativo viene identificato tramite l”Autenticazione Trasporto, o il valore “${dynamicConfig:tokenClientApplicationSearch(purposeId)}” se viene identificato tramite il clientId presente nel token ottenuto dall”Autenticazione Token.