🏠 Home

Onboarding in IT Wallet

Nota: L'esempio seguente utilizza i dati di PagoPA per illustrare la procedura di Onboarding, ma la stessa procedura si applica a qualsiasi entità che desideri effettuare l'onboarding nella federazione IT Wallet.

Passo 1: Invio della Richiesta di Onboarding via E-mail

Per avviare il processo di Onboarding, l'entità deve inviare una richiesta via e-mail all'indirizzo identitadigitale@pec.ipzs.it includendo le seguenti informazioni:

🆔 Federation Entity Identifier

Nell'e-mail occorre fornire un URL univoco che identifica l'entità sulla rete.

Esempio: https://foo11.blob.core.windows.net/foo

📧 PEC

Nell'e-mail occorre indicare l'indirizzo PEC ufficiale dell'entità.

Esempio: pagopaspa@pec.pagopa.it

🆔 Codice identificativo

Nell'e-mail occorre specificare un codice identificativo differente a seconda della natura dell'entità:

  • Entità privata: fornire il Codice Fiscale o la Partita IVA.
  • Entità pubblica: specificare il Codice IPA.

Esempio per entità pubblica (PagoPA): Codice IPA: 5N2TR557

🔑 Federation Entity Public Key (JWK)

Nell'e-mail occorre fornire la chiave pubblica ellittica, in formato JSON Web Key (JWK), che l'entità intende utilizzare nelle operazioni di firma dei propri Entity Configuration (EC), ovvero la Federation Entity Public Key dell'entità.

Esempio:

{
    "kid": "NsXymfIILEPR5Y0t",
    "kty": "EC",
    "x": "gXY4FApFJCj91Gpb1K9GEIouTq2X3L0K64Iq0ob4l_g",
    "y": "l-6dcrIrFVdrzoY9cRJv9zNuFOR3MsDz6TSDhB0xEo4",
    "crv": "P-256"
}

📄 CSR (PKCS #10)

È necessario allegare alla richiesta una CSR (Certificate Signing Request), in formato PKCS #10, contenente la Federation Entity Public Key dell'entità, al fine di richiedere al Trust Anchor l'emissione di un certificato X.509 che certifica tale chiave.

La CSR deve rispettare le seguenti condizioni:

  • Contenere la Federation Entity Public Key da certificare;
  • Essere firmata con la chiave privata corrispondente alla Federation Entity Public Key contenuta nella CSR;
  • Definire il Subject del certificato X.509 che il Trust Anchor dovrà rilasciare; questo Subject deve presentare i seguenti attributi:
    • Country (C): Codice ISO a due lettere dello Stato dove è ubicata l'entità (es. C=IT);
    • State (ST): Regione dove è ubicata l'entità (es. ST=Lazio);
    • Locality (L): Città di ubicazione dell'entità (es. L=Roma);
    • Organization Name (O): Denominazione legale dell'entità (es. O=PagoPA S.p.A.);
    • Organization Unit (OU): Reparto interno dell'entità, facoltativo (es. OU=Identità Digitali);
    • Common Name (CN): Deve corrispondere al Federation Entity Identifier senza schema https:// (es. CN=foo11.blob.core.windows.net/foo);
    • emailAddress: Deve corrispondere alla PEC (es. emailAddress=pagopaspa@pec.pagopa.it).

Esempio:

-----BEGIN CERTIFICATE REQUEST-----
MIIBTTCB9QIBADCBkjELMAkGA1UEBhMCSVQxDjAMBgNVBAgMBUxhemlvMQ0wCwYD
VQQHDARSb21hMRYwFAYDVQQKDA1QYWdvUEEgUy5wLkEuMSQwIgYDVQQDDBtmb28x
MS5ibG9iLmNvcmUud2luZG93cy5uZXQxJjAkBgkqhkiG9w0BCQEWF3BhZ29wYXNw
YUBwZWMucGFnb3BhLml0MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEgXY4FApF
JCj91Gpb1K9GEIouTq2X3L0K64Iq0ob4l/iX7p1ysisVV2vOhj1xEm/3M24U5Hcy
wPPpNIOEHTESjqAAMAoGCCqGSM49BAMCA0cAMEQCIF5En5RWaQbdwGnslgqztry3
fODzjO0xCA5AZ0qDZxTNAiAd/a6erYHQjMnEraYnkmZGug2gR2eiCQoyUzKi3+I5
jA==
-----END CERTIFICATE REQUEST-----

Puoi visualizzare il contenuto di questa CSR di esempio con strumenti come OpenSSL:

#!/bin/bash
openssl req -in richiesta.csr -noout -text

Il comando restituirà qualcosa di simile a:

Certificate Request:
    Data:
        Version: 0 (0x0)
        Subject: C = IT, ST = Lazio, L = Roma, O = PagoPA S.p.A., CN = foo11.blob.core.windows.net, emailAddress = pagopaspa@pec.pagopa.it
        Subject Public Key Info:
            Public Key Algorithm: id-ecPublicKey
                Public-Key: (256 bit)
                ...
    Attributes:
        ...
    Signature Algorithm: ecdsa-with-SHA256
        ...
    Signature Value:
        ...
Attenzione:
Prima di inviare la richiesta di Onboarding tramite e-mail, occorre assicurarsi che nel proprio endpoint /.well-known/openid-federation sia stato pubblicato un Entity Configuration (EC) firmato con la propria chiave privata corrispondente alla Federation Entity Public Key fornita nella richiesta di Onboarding.

L'EC deve includere nel payload:
Info:
Il Trust Anchor registra internamente il Federation Entity Identifier dell'entità convertendolo tutto in minuscolo.

Passo 2: Ricezione della Risposta alla Richiesta di Onboarding via E-mail

A seguito dell'invio della richiesta da parte dell'entità, il Trust Anchor procederà con:

Una volta completate queste operazioni, l'entità riceverà in risposta dal Trust Anchor una e-mail contenente una catena di certificati dove il primo elemento della catena è il certificato X.509 richiesto che certifica la Federation Entity Public Key dell'entità e il secondo elemento della catena è il certificato X.509 Self-Signed del Trust Anchor da utilizzare per validare il primo certificato (entrambi i certificati della catena sono espressi in formato DER codificato in Base64).

Esempio:

[
    "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"
]


Nota: In caso di non superamento dei controlli, l'entità riceverà una e-mail di risposta dove sono riportate le problematiche rilevate dal Trust Anchor che occorrerà sanare prima di effettuare una nuova richiesta di Onboarding.
Info:
Richiamando l'endpoint /list del Trust Anchor non sarà presente il Federation Entity Identifier dell'entità all'interno del JSON Array di risposta in quanto il processo di Onboarding non è ancora concluso.

Passo 3: Aggiornamento del proprio Entity Configuration (EC) e richiamo del Resolve endpoint

L'entità, dopo aver ricevuto dal Trust Anchor l'e-mail di risposta alla sua richiesta di Onboarding contenente la catena di certificati X.509, dovrà:

Passo 4: Ricezione della Resolve Response

A seguito della Resolve Request trasmessa dall'entità, il Trust Anchor procederà con:

In caso di risposta con status code 200 OK, l'Onboarding dell'entità si è concluso con successo e l'entità è tenuta a validare il JWT contenuto nella Resolve Response ricevuta e ad estrarre dal payload la propria trust chain e i propri metadati validati dal Trust Anchor.

Nota: Nel caso in cui l'endpoint /resolve del Trust Anchor risponda con uno status code 400 o 404, l'entità dovrà provvedere a sanare la problematica descrita nel messaggio di risposta prima di richiamare nuovamente l'endpoint /resolve del Trust Anchor. Per status code diversi da 400 e 404, occorre inviare una email a identitadigitale@pec.ipzs.it e segnalare la problematica.
Info:
Richiamando l'endpoint /list del Trust Anchor sarà ora presente il Federation Entity Identifier dell'entità all'interno del JSON Array di risposta.