Procedura di autenticazione delle TPP¶

E' qui descritta la procedura di "on-boarding" per la TPP che intende fornire servizi di pagamento agli utenti di A-Tono Payment Institute S.p.A.

La procedura consta di tre fasi:

censimento, da eseguire una tantum
autenticazione, da eseguire ogni volta si debba creare una sessione di lavoro
accessoalla risorsa, da eseguire per ogni interazione con i nostri sistemi

graph LR
    C(Censimento) --> Au(Autenticazione)
    Au --> Ac(Accesso)

Censimento¶

La fase di censimento serve a inserire nei nostri sistemi il numero di autorizzazione di cui al comma 2, dell'articolo 34 del Regolamento Delegato (UE) 2018/389 della Commissione del 27 novembre 2017 e ad associarvi le autorizzazioni cui ha diritto, estratte dal registro ABE di cui all'articolo 15 della Direttiva (UE) 2015/2366 del Parlamento Europeo e del Consiglio del 25 novembre 2015.

A tal scopo è necessario munirsi di certificato qualificato eIDAS QWAC (cioè per l'autenticazione di sito web) rilasciato da una QTSP riconosciuta a livello europeo e censita negli appositi registri mantenuti dall'ABE a norma del comma 4 dell'articolo 22 del Regolamento (UE) n. 910/2014 del Parlamento Europeo e del Consiglio del 23 luglio 2014.

Quindi si dovrà invocare una tantum l'API self-service

https://api.drop-pay.io/auth/realms/droppay/tpp/register`

con metodo POST inserendo nel body della richiesta un oggetto JSON vuoto (cioè, la stringa "{}") e utilizzando, per la connessione, il certificato eIDAS per la mutua autenticazione a livello TLS:

sequenceDiagram
    participant T as TPP
    participant S as DropPay

    T->>S: Request over HTTPS

    Note over T,S: POST /auth/realms/droppay/tpp/register
    Note over T,S: {}

    S-->>T: Response

    Note over T,S: Status Code = 204, 200 or 4xx

In risposta si riceverà una delle due alternative seguenti:

un body vuoto nel caso di HTTP Status Code 204 a indicare il successo dell'operazione
un oggetto JSON
- contenente ulteriori informazioni utili alla fase di censimento nel caso di HTTP Status Code 200 a indicare il successo dell'operazione (previsto in futuro)
- contenente un oggetto error costituito come mostrato di seguito in caso di HTTP Status Code 4xx a indicare il fallimento dell'operazione

{
  "error": {
    "code": 101,
    "description": "not a qualified certificate"
  }
}

Alcune possibili cause d'errore sono:

il certificato scaduto o invalido
la mancanza delle autorizzazioni necesssarie per operare sul territorio italiano
la TPP è già censita

Attenzione

Per certi tipi d'errore, quali certificato scaduto o firmato da QTSP non riconosciuta, la comunicazione potrebbe fallire a livello TLS, ossia, prima ancora che si possa avere la possibilità di scambiare messaggi HTTP.

In questa evenienza sarà possibile contattarci all'indirizzo psd2-tpp@drop-pay.com e comunicarci i problemi riscontrati.

Si noti che poichè la TPP è identificata dal numero di autorizzazione assegnatole dalle autorità competenti dello Stato membro di appartenenza, in caso di rinnovo del certificato eIDAS non è necessario ripetere la fase di censimento.

Autenticazione¶

La fase di autenticazione permette di instaurare una sessione di lavoro per operare sui conti di un determinato utente.

La sessione è identificata da un "access token" che dev'essere usato durante la successiva fase di accesso alle API operative.

Per ottenere l'access token bisogna inviare una richiesta all'API

https://api.drop-pay.io/auth/realms/droppay/protocol/openid-connect/token

con il metodo POST contenente i seguenti parametri:

grant_type=password
username valorizzato con l'identificativo dell'utente, che ha la sintassi di un MSISDN italiano.
password valorizzato con la password dell'utente

MSISDN Italiano

Un "MSISDN italiano" è un numero di telefono in formato internazionale ITU.T E.164, cioè, comprensivo di prefisso internazionale 39 (Italia) e privo dei prefissi di selezione (00, +, ecc.). Per esempio : 393351234567

Per la connessione HTTPS instaurata tra le due parti, la TPP dovrà utilizzare il certificato eIDAS per la mutua autenticazione a livello TLS.

sequenceDiagram
    participant T as TPP
    participant S as DropPay

    T->>S: Request over HTTPS

    Note over T,S: POST /auth/realms/droppay/protocol/openid-connect/token
    Note over T,S: grant_type=password username=393331234567 password=somesecrettoken

    S-->>T: Response

    Note over T,S: Status Code = 200 or 4xx

Se l'autenticazione riesce, in risposta si otterrà un oggetto JSON, per esempio:

{
  "access_token": "eyJhbGciOi...DsMCHs09og",
  "expires_in": 300,
  "refresh_expires_in": 1800,
  "refresh_token": "eyJhbGciOi...rPmNR4Xn5E",
  "token_type": "bearer",
  "not-before-policy": 1533282000,
  "session_state": "04293183-cbba-42ca-9187-edce59a8c22e",
  "scope":"tpp"
}

In caso d'errore si otterrà un diverso oggetto JSON contenente una descrizione del problema riscontrato, per esempio:

{
  "error": "invalid_grant",
  "error_description": "Invalid user credentials"
}

La durata dell'access token è di cinque minuti, scaduti i quali bisogna generarne uno nuovo. A tal scopo, insieme all'access token è fornito anche un refresh token.

Per generare un nuovo access token, bisogna inviare una richiesta all'API

`https://api.drop-pay.io/auth/realms/droppay/protocol/openid-connect/token

con il metodo POST contenente i seguenti parametri:

grant_type=refresh_token
refresh_token valorizzato con il refresh token

sequenceDiagram
    participant T as TPP
    participant S as DropPay

    T->>S: Request over HTTPS

    Note over T,S: POST /auth/realms/droppay/protocol/openid-connect/token
    Note over T,S: grant_type=refresh_token refresh_token=eyJhbGciOi...rPmNR4Xn5E

    S-->>T: Response

    Note over T,S: Status Code = 200 or 4xx

Il formato della risposta (errori inclusi) è lo stesso di quella del caso precedente.

Se inutilizzato, il refresh token scade dopo 30 minuti. Dopodiché la sessione terminerà e sarà necessario aprirne una nuova utilizzando le credenziali dell'utente. Se invece il refresh token viene utilizzato, è possibile prolungare la durata della sessione fino a un massimo di 10 ore.

Maggiori dettagli sul contenuto degli oggetti JSON restituiti sono presenti nelle sezioni 4.3 e 5 della specifica tecnica OAuth 2.0 (Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, October 2012).

Autenticazione del client

Il client TPP non deve specificare i parametri client_id nè client_secret nel body delle richieste HTTP nè nell'header Authorization. L'identificazione avviene per mezzo del certificato eIDAS utilizzato per instaurare la connessione HTTPS.

Accesso alle risorse¶

Access Token - JWT format

L'access token è fornito nel formato JWT (https://jwt.io/) e, una volta decodificato, fornisce le informazioni riportate nell'esempio sottostante:

- header: {
   "alg": "RS256",
   "typ": "JWT",
   "kid": "DJdfAXaCnYNxgTNeYQp0bwzJhbIJqLUH9gpunRmCNvw"
 }
- body: {
   "jti": "7c9bd8c2-edb1-45fb-a1a4-6c4090d36251",
   "exp": 1555337307,
   "nbf": 0,
   "iat": 1555337007,
   "iss": "https://api.drop-pay.io/auth/realms/droppay",
   "sub": "f:fb05e6a5-e3db-44e7-9e9d-7d56cd5d38a9:477",
   "typ": "Bearer",
   "azp": "db2ffeac6c0f402b87712530981e9871",
   "auth_time": 0,
   "session_state": "28b39feb-b921-44de-ac9e-4294de71c2cf",
   "acr": "1",
   "realm_access": {
     "roles": [
       "Aa", "Ac", "Ad", "Af", "Ag", "Ai", "Aj", "Al", "An", "Ao", "AA", "AB", "AD", "AE", "AG", "AH",
       "AJ", "AK", "AL", "AM", "AN", "AO", "AQ", "AR", "AT", "AU", "AV", "AW", "AX", "AY"
     ]
   },
   "scope": "mdpapp",
   "preferred_username": "393351234567",
   "druid_userid":477,
   "droppay_identity": "DPI19487191",
   "droppay_accounts": "IT86M3606400001393351234567,IT89M3606400001I05034550166"
   "apn": "DropPay Mobile App"
 }

E' rilevante per gli scopi della TPP il claim droppay_accounts che fornisce la lista degli IBAN dei conti sui quali l'utente può operare. Il valore dell'IBAN selezionato dall'utente dopo l'autenticazione consente di invocare le API indicando il conto designato sul quale l'operazione deve essere eseguita.

In questa fase è possibile accedere ai servizi offerti dalle nostre API.

La richiesta HTTP dovrà contenere nell'header Authorization l'access token ottenuto durante la fase di autenticazione. Per questa fase, non è richiesto l'uso del certificato eIDAS per la mutua autenticazione. L'autenticazione avverrà per mezzo dell'access token.

sequenceDiagram
    participant T as TPP
    participant S as DropPay

    T->>S: Request over HTTPS

    Note over T,S: Authorization: Bearer eyJhbGciOi...DsMCHs09og

    S-->>T: Response

Per maggiori informazioni riguardo la struttura delle richieste operative, delle risposte e delle possibili condizioni d'errore, si veda la documentazione delle specifiche API (DropPay API Reference):

PISP - Pagamenti - DropPay API Push
AISP - Informazioni sui conti DropPay API Account Info