Metadata IdP¶

CieID server è fruibile sia in ambiente di produzione che in ambiente di test/preproduzione. I metadati XML relativi ai due ambienti sono raggiungibili ai seguenti indirizzi:

• Metadati di PRODUZIONE
• Metadati di TEST/PRE-PRODUZIONE

Metadata SP¶

Il Service Provider (SP) deve predisporre un file di metadata conforme allo standard SAML v2. Seguendo la procedura di onboarding implementata dal portale di federazione erogatori di sevizi, deve effettuare il caricamento di tale metadata sugli ambienti di pre-produzione e produzione messi a disposizione dal Ministero dell'Interno (cfr. il Manuale operativo per i fornitori di servizi pubblici e privati per ulteriori dettagli sul processo di onboarding).

Tramite il medesimo portale, è possibile, inoltre, aggiornare un metadata già caricato. É consentito, nell’ambito di una richiesta di federazione, il caricamento di un solo file di metadata per ambiente, e ogni caricamento successivo andrà a sostituire il precedente file di metadata.

Struttura del metadata¶

Un file metadata é strutturato gerarchicamente in un elemento radice <md:EntityDescriptor> (un server SAML che esegue determinati compiti per conto ad esempio di un SP) e uno o piú elementi ad esso associato. Diversamente da quanto prescritto dallo standard SAML v.2, che consente, tramite l'elemento radice md:EntitiesDescriptor>, di inserire in un unico metadata più <md:EntityDescriptor>, lo schema "Entra con CIE" prevede obbligatoriamente un solo elemento <md:EntityDescriptor> come radice del metadata.

1
2
3

<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://service-provider.it/sp">
   [...]
</md:EntityDescriptor>

L'elemento <EntityDescriptor> costituisce il contenitore al cui interno si trovano le regole e le direttive valide solo ed esclusivamente per quel singolo soggetto. É strutturato internamente come una sequenza di elementi tra i quali il Service Provider deve necessariamente inserire i seguenti, tutti obbligatori (e presenti una e una sola sola volta, salvo ove espressamente indicato):

• <Signature> riportante il sigillo elettronico apposto sul metadadata stesso. Per ulteriori informazioni si faccia riferimento al capitolo sull'infrastruttura a chiave pubblica.
• <SPSSODescriptor> contenente le principali informazioni su chiavi crittografiche, URL e binding. Tale elemento descrive il ruolo del Service Provider e gli endpoint tecnici che espone verso gli altri soggetti della federazione.
• <Organization> in cui sono indicati le stringhe identificative dell'organizzazione a cui afferisce il soggetto del metadata.
• Una o due istanze <ContactPerson> in cui sono indicati ulteriori dati identificativi del soggetto cui il metadata SAML si riferisce e di un eventuale soggetto che, in veste di partner tecnologico, ne cura gli aspetti tecnici di federazione, sviluppo e messa in esercizio. I dati contenuti nelle istanze <ContactPerson> sono regolamentati più avanti.

Si consiglia di indicare i namespace XML rilevanti per il metadata SAML (sopratutto quelli utilizzati in più punti del metadata) una tantum nell'elemento radice dello stesso.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

<md:EntityDescriptor
  xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
  xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
  entityID="https://service-provider.it/sp">
    <ds:Signature> [...] </ds:Signature>
    <md:SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
        [...]
    </md:SPSSODescriptor>
    <md:Organization> [...] </md:Organization>
    <md:ContactPerson> [...] </md:ContactPerson>
    [...]
</md:EntityDescriptor>

1
2
3
4
5
6
7

<md:AttributeConsumingService index='0'>
    <md:ServiceName xml:lang=''>urn:uuid:bc212b14-d920-4052-900d-86cc5ab48a3a</md:ServiceName>
    <md:RequestedAttribute Name='name' NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"/>
    <md:RequestedAttribute Name='familyName' NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"/>
    <md:RequestedAttribute Name='dateOfBirth' NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"/>
    <md:RequestedAttribute Name='fiscalNumber' NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"/>
</md:AttributeConsumingService>

1
2
3
4
5
6
7
8

<md:Organization>
    <md:OrganizationName xml:lang="it">Istituto Service Provider</md:OrganizationName>
    <md:OrganizationName xml:lang="en">Service Provider Institute</md:OrganizationName>
    <md:OrganizationDisplayName xml:lang="it">ISP</md:OrganizationDisplayName>
    <md:OrganizationDisplayName xml:lang="en">SPI</md:OrganizationDisplayName>
    <md:OrganizationURL xml:lang="it">https://www.isp.it</md:OrganizationURL>
    <md:OrganizationURL xml:lang="en">https://www.isp.it</md:OrganizationURL>
</md:Organization>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
                     xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
                     xmlns:cie="https://www.cartaidentita.interno.gov.it/saml-extensions"
                     entityID="https://entityidsp">
  <ds:Signature> [...] </ds:Signature>
  <md:SPSSODescriptor AuthnRequestsSigned="true"
                      WantAssertionsSigned="true"
                      protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <md:KeyDescriptor use="signing">
      <ds:KeyInfo>
        <ds:X509Data>
          <ds:X509Certificate> [...] </ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </md:KeyDescriptor>
    <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
                            Location="https://url_esempio_SLO_Redirect" />
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
                                 Location="https://url_esempio_POST"
                                 index="0"
                                 isDefault="true" />
    <md:AttributeConsumingService index="0">
      <md:ServiceName xml:lang="">urn:uuid:86eabbc2-6023-4f8d-a7dc-22401f5ac4fe</md:ServiceName>
      <md:RequestedAttribute Name="name" />
      <md:RequestedAttribute Name="familyName" />
      <md:RequestedAttribute Name="dateOfBirth" />
      <md:RequestedAttribute Name="fiscalNumber" />
    </md:AttributeConsumingService>
  </md:SPSSODescriptor>
  <md:Organization>
    <md:OrganizationName xml:lang="it">Service Provider Privato s.r.l.</md:OrganizationName>
    <md:OrganizationDisplayName xml:lang="it">SPP</md:OrganizationDisplayName>
    <md:OrganizationURL xml:lang="it">https://www.esempio_sp_privato.it</md:OrganizationURL>
  </md:Organization>
  <md:ContactPerson contactType="administrative">
    <md:Extensions>
      <cie:Private/>
      <cie:VATNumber>IT01234567890</cie:VATNumber>
      <cie:FiscalCode>9876543210</cie:FiscalCode>
      <cie:NACE2Code>CODICE_ATECO</cie:NACE2Code>
      <cie:Municipality>CODICE_ISTAT</cie:Municipality>
    </md:Extensions>
    <md:Company>Service Provider Privato s.r.l.</md:Company>
    <md:EmailAddress>esempio_sp_privato@spp.it</md:EmailAddress>
    <md:TelephoneNumber>+39061234567</md:TelephoneNumber>
  </md:ContactPerson>
</md:EntityDescriptor>

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103

<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
                     xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
                     xmlns:cie="https://www.cartaidentita.interno.gov.it/saml-extensions"
                     entityID="https://entityidsp">
  <ds:Signature> [...] </ds:Signature>
  <md:SPSSODescriptor AuthnRequestsSigned="true"
                      WantAssertionsSigned="true"
                      protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <md:KeyDescriptor use="signing">
      <ds:KeyInfo>
        <ds:X509Data>
          <ds:X509Certificate> ... </ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </md:KeyDescriptor>
    <md:KeyDescriptor use="encryption">
        <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
            <ds:X509Data>
                <ds:X509Certificate> [...] </ds:X509Certificate>
            </ds:X509Data>
        </ds:KeyInfo>
    </md:KeyDescriptor>
    <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
                            Location="https://url_esempio_SLO_Redirect" />
    <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" 
                            Location="url_esempio_SLO_POST"/>
    <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" 
                            Location="url_esempio_SLO_SOAP"/>
    <md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</md:NameIDFormat>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
                                 Location="https://url_esempio_POST"
                                 index="0"
                                 isDefault="true" />
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
                                 Location="https://url_esempio_Redirect"
                                 index="1"
                                 isDefault="false" />
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-SOAP"
                                 Location="https://url_esempio_SOAP"
                                 index="2" /> 
    <md:AttributeConsumingService index="0">
      <md:ServiceName xml:lang="">urn:uuid:a83e1df8-0dd3-46c0-b4e3-f6c650177056</md:ServiceName>
      <md:ServiceDescription xml:lang="it">DESCRIZIONE CATEGORIA SERVIZI ONLINE</md:ServiceDescription>
      <md:RequestedAttribute Name="name" />
      <md:RequestedAttribute Name="familyName" />
      <md:RequestedAttribute Name="dateOfBirth" />
      <md:RequestedAttribute Name="fiscalNumber" />
    </md:AttributeConsumingService>
    <md:AttributeConsumingService index="1">
      <md:ServiceName xml:lang="">urn:uuid:bd042d58-d402-4970-83dc-70cd1882bf62</md:ServiceName>
      <md:ServiceDescription xml:lang="en">ATTRIBUTE SET DESCRIPTION</md:ServiceDescription>
      <md:RequestedAttribute Name="name" />
      <md:RequestedAttribute Name="familyName" />
      <md:RequestedAttribute Name="dateOfBirth" />
      <md:RequestedAttribute Name="fiscalNumber" />
    </md:AttributeConsumingService>
    <md:AttributeConsumingService index="2">
      <md:ServiceName xml:lang="">urn:uuid:a16cb8fd-62c6-4ff5-88ea-7dd3bdcb4c4e</md:ServiceName>
      <md:RequestedAttribute Name="name" />
      <md:RequestedAttribute Name="familyName" />
      <md:RequestedAttribute Name="dateOfBirth" />
      <md:RequestedAttribute Name="fiscalNumber" />
    </md:AttributeConsumingService>
  </md:SPSSODescriptor>
  <md:Organization>
    <md:OrganizationName xml:lang="it">Istituto Service Provider</md:OrganizationName>
    <md:OrganizationName xml:lang="en">Service Provider Institute</md:OrganizationName>
    <md:OrganizationDisplayName xml:lang="it">ISP</md:OrganizationDisplayName>
    <md:OrganizationDisplayName xml:lang="en">SPI</md:OrganizationDisplayName>
    <md:OrganizationURL xml:lang="it">https://www.isp.it</md:OrganizationURL>
    <md:OrganizationURL xml:lang="en">https://www.isp.it</md:OrganizationURL>
  </md:Organization>
  <md:ContactPerson contactType="administrative">
      <md:Extensions>
          <cie:Public/>
          <cie:IPACode>codiceIPA_SP</cie:IPACode>
          <cie:IPACategory>categoriaIPA_SP</cie:IPACategory>
          <cie:NACE2Code>codiceATECO_SP</cie:NACE2Code>
          <cie:VATNumber>IT01234567890</cie:VATNumber>
          <cie:FiscalCode>9876543210</cie:FiscalCode>
          <cie:Municipality>codiceISTAT_SP</cie:Municipality>
          <cie:Province>sigla_provincia_SP</cie:Province>
          <cie:Country>IT</cie:Country>                 
      </md:Extensions>
      <md:Company>Istituto Service Provider</md:Company>
      <md:EmailAddress>info@isp.gov.it</md:EmailAddress>
      <md:TelephoneNumber>+390011223344</md:TelephoneNumber>
  </md:ContactPerson>
  <md:ContactPerson contactType="technical">
      <md:Extensions>
          <cie:Private/>
          <cie:VATNumber>IT01234567890</cie:VATNumber>
          <cie:FiscalCode>9876543210</cie:FiscalCode>
          <cie:NACE2Code>codiceATECO_partnerTecnologico</cie:NACE2Code>
          <cie:Municipality>codiceISTAT_partnerTecnologico</cie:Municipality>
          <cie:Province>sigla_provincia_partnerTecnologico</cie:Province>   
          <cie:Country>IT</cie:Country>
      </md:Extensions>
      <md:Company>Partner Tecnologico per Soluzioni di Identità Federata s.r.l.</md:Company>
      <md:EmailAddress>info.cie@partnertecnologicoidfederata.com</md:EmailAddress>
      <md:TelephoneNumber>+390999135792</md:TelephoneNumber>
  </md:ContactPerson>
</md:EntityDescriptor>

Richiesta di autenticazione SAML¶

La richiesta di autenticazione ("request") è inviata dal Service Provider attraverso il browser dell'utente al SingleSignOnService dell'Identity Provider. Il messaggio contenuto in essa deve essere conforme allo standard SAML v2.0 (cfr. Assertions and Protocols for the OASIS SAML V2.0).

L'elemento <AuthnRequest> costituisce il contenitore del messaggio e deve avere i seguenti attributi:

• Destination rappresenta un URL in https che indica l'indirizzo dell'Identity Provider a cui è inviata la richiesta e deve coincidere con uno degli attributi Location presenti nel tag SingleSignOnService riportato nel metadata dell'IdP e relativo al particolare binding utilizzato in fase di richiesta (cfr. Modalitá di trasmissione dei messaggi per ulteriori dettagli). L'Identity Provider verifica tale riferimento e, in caso di esito negativo, la richiesta viene scartata.
• AttributeConsumingServiceIndex riportante un indice posizionale in riferimento alla struttura <AttributeConsumingService> presente nei metadata del Service Provider. A tal proposito si ricorda che gli attributi richiesti nel metadata devono contenere il Minimum Dataset eIDAS.
• AssertionConsumerServiceURL indica la URL a cui inviare il messaggio di risposta alla richiesta di autenticazione (l'indirizzo deve coincidere con quello del servizio riportato dall'elemento <AssertionConsumingService> presente nei metadata del Service Provider);
• ProtocolBinding identifica il tipo di binding e deve essere valorizzato con urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST.
• ForceAuthn è sempre valorizzato con true in quanto si richiede un'autenticazione con massimo livello di sicurezza.
• IssueInstant indica l'istante di emissione della richiesta, in formato UTC (p.es. AAAA-MM-GGThh:mm:ss.sssZ)
• ID univoco basato su un Universally Unique Identifier (UUID) o su una combinazione origine + timestamp (quest'ultimo generato con una precisione di almeno un millesimo di secondo per garantire l'univocità).
• Version coerentemente con la versione di SAML adottata; attualmente la 2.0.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

<samlp:AuthnRequest
  xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
  AttributeConsumingServiceIndex="0"
  AssertionConsumerServiceIndex="0"
  Destination="https://idserver.servizicie.interno.gov.it/idp/profile/SAML2/Redirect/SSO"
  ForceAuthn="true"
  IssueInstant="2020-10-29T12:51:36.123Z"
  ID="..."
  Version="2.0">
    [...]
</samlp:AuthnRequest>

Gli elementi che devono essere presenti all'interno della <AuthnRequest> sono:

• <saml:Issuer>: identifica in maniera univoca il Service Provider. L'elemento deve essere valorizzato come l'attributo entityID riportato nel corrispondente metadata del Service Provider. Prevede, inoltre, i seguenti attributi opzionali:
• NameQualifier, dominio a cui afferisce il soggetto che sta effettuando la richiesta di autenticazione e valorizzato come URL riconducibile al Service Provider;
• Format, se presente deve essere valorizzato con la stringa urn:oasis:names:tc:SAML:2.0:nameid-format:entity.

• <NameIDPolicy> avente l'attributo Format valorizzato con la stringa urn:oasis:names:tc:SAML:2.0:nameid-format:transient, mentre invece non deve essere presente l'attributo AllowCreate.

• <RequestedAuthnContext> (ne è presente una sola occorrenza) specifica i requisiti del contesto di autenticazione di statement di autenticazione restituite in risposta a una richiesta. Esso è valorizzato come segue:

  • mediante l'attributo Comparison, che specifica il metodo di confronto utilizzato per valutare le classi o gli statement di contesto richiesti e può essere valorizzato soltanto come exact (default), ovvero minimum;

  • contenente l'elemento <RequestedAuthnContext>, contiene a sua volta l'elemento <saml:AuthnContextClassRef>, valorizzato con uno dei seguenti valori:

    • https://www.spid.gov.it/SpidL1
    • https://www.spid.gov.it/SpidL2
    • https://www.spid.gov.it/SpidL3

Lo schema di autenticazione "Entra con CIE", nell'ottica di agevolare gli sviluppi implementativi da parte dei Service Provider che giá hanno aderito al Sistema Pubblico di Identità Digitale (SPID), richiede la valorizzazione di tale elemento con una delle suddette stringhe (corrispondenti ai tre livelli di sicurezza SPID), secondo lo specifico livello di sicurezza richiesto (dall'utente o dal SP). Pertanto, per consentire al cittadino di autenticarsi sia a servizi accessibili tramite CIE, che a quelli accessibili tramite qualunque livello di sicurezza SPID, le possibili combinazioni di valori dell'elemento <RequestedAuthnContextClassRef> e dell'attributo-antenato Comparison sono, rispettivamente:

• autenticazione di livello "alto" (livello 3): https://www.spid.gov.it/SpidL3 e, equivalentemente, exact ovvero minimum;
• autenticazione di livello almeno "significativo" (livello 2 o superiore): https://www.spid.gov.it/SpidL2 e minimum;
• autenticazione di livello "basso"" o superiore (livello 1 o superiore): https://www.spid.gov.it/SpidL1 e minimum;

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

<samlp:AuthnRequest
  xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
  xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
  xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
  AttributeConsumingServiceIndex="0"
  AssertionConsumerServiceURL=" [...] "
  ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
  Destination="https://idserver.servizicie.interno.gov.it/idp/profile/SAML2/POST/SSO"
  ForceAuthn="true"
  ID="..."
  IssueInstant="2020-11-02T09:01:25Z" Version="2.0">
    <saml:Issuer NameQualifier="https://service_provide_entityID">
        https://service_provider_entityID
    </saml:Issuer>
    <ds:Signature>
        <ds:SignedInfo>
            <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
            <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256" />
            <ds:Reference URI="RIFERIMENTO ALL'ID DELL'ATTRIBUTO">
                <ds:Transforms>
                    <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" />
                    <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
                </ds:Transforms>
                <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256" />
                <ds:DigestValue> [...] </ds:DigestValue>
            </ds:Reference>
        </ds:SignedInfo>
        <ds:SignatureValue> [...] </ds:SignatureValue>
        <ds:KeyInfo>
            <ds:X509Data>
                <ds:X509Certificate> [...] </ds:X509Certificate>
            </ds:X509Data>
        </ds:KeyInfo>
    </ds:Signature>
    <samlp:NameIDPolicy Format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient" />
    <samlp:RequestedAuthnContext Comparison="minimum">
        <saml:AuthnContextClassRef>https://www.spid.gov.it/SpidL3</saml:AuthnContextClassRef>
    </samlp:RequestedAuthnContext>
</samlp:AuthnRequest>

Risposta di autenticazione SAML¶

Al termine della challenge mediante la CIE, effettuata dal server CieID dell'Identity Provider, quest'ultimo invia un messaggio di risposta ("response") al Service Provider. L'elemento <Response> costituisce la radice del messaggio e contiene i seguenti attributi:

• Destination: URL del Service Provider a cui è inviata la risposta; coincide con la URL riportata nel metadata cosí come specificato dall'attributo location presente nell'elemento <AssertionConsumerService>. Il Service Provider deve verificare il riferimento URI e, in caso di esito negativo, deve scartare la risposta;
• ID: identificatore univoco basato su un Universally Unique Identifier (UUID) o su una combinazione origine + timestamp (quest'ultimo generato con una precisione di almeno un millesimo di secondo per garantire l'univocità);
• InResponseTo: riferimento all'ID della richiesta a cui si risponde;
• IssueInstant: indica l'istante di emissione della richiesta, in formato UTC (AAAA-MM-GGThh:mm:ss.sssZ);
• Version: riferimento alla versione SAML (2.0) utilizzata dallo schema Entra con CIE.

Gli elementi contenuti nella <Response> (tutti dichiarati con il corretto uso dei namespace XML) sono:

• <Issuer>: in maniera analoga a quanto previsto per la request, tale campo indica l'EntityID del soggetto che effettua l'autenticazione (cioè l'Identity Provider stesso) e coincide perciò con l'attributo entityID del metadata dell'IdP.

• <Signature>: contiene il sigillo elettronico apposto sulla request dell'Identity Provider. Per ulteriori informazioni si faccia riferimento al capitolo sull'infrastruttura a chiave pubblica.

• <Status>: indica l'esito della richiesta di autenticazione e in particolare prevede l'elemento <StatusCode> che riporta la codifica di stato SAML attraverso l'attributo Value, valorizzato come:

  • urn:oasis:names:tc:SAML:2.0:status:Success, nel caso di autenticazione effettuata con successo;
  • in caso di errori, é possibile visualizzare gli attributi <StatusMessage> e <StatusDetail> per maggiori dettagli sull'errore ricevuto.

• <Assertion>: costituisce l'elemento piú importante che attesta l'avvenuta autenticazione e contiene gli attributi dell'utente che ha richiesto l'accesso al servizio. Contiene almeno un elemento <AuthnStatement> nel quale sono riportati i dati dell'utente richiesti dal Service Provider. Nel caso l'Identity Provider abbia riscontrato un errore nella gestione della richiesta di autenticazione l'elemento <Assertion> non é presente.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

<samlp:Response
  xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
  xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
  Destination="https://service_provide_assertion_consumer"
  InResponseTo="..."
  IssueInstant="2020-10-29T11:36:02.708Z"
  ID="..."
  Version="2.0">
    <saml:Issuer>
        https://idserver.servizicie.interno.gov.it/idp/profile/SAML2/POST/SSO
    </saml:Issuer>
    <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        [...]
    </ds:Signature>
    <samlp:Status>
        <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success" />
    </samlp:Status>
    <saml:Assertion>
        [...]
    </saml:Assertion>
</samlp:Response>

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106

<samlp:Response
  xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
  xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
  xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
  xmlns:xs="http://www.w3.org/2001/XMLSchema"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  Destination="https://service_provide_assertion_consumer"
  ID="..."
  InResponseTo="..."
  IssueInstant="2020-10-29T11:36:02.708Z" Version="2.0">
    <saml:Issuer>
        https://idserver.servizicie.interno.gov.it/idp/profile/SAML2/POST/SSO
    </saml:Issuer>
    <ds:Signature>
        <ds:SignedInfo>
            <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
            <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256" />
            <ds:Reference URI="...">
                <ds:Transforms>
                    <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" />
                    <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
                </ds:Transforms>
                <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256" />
                <ds:DigestValue> [...] </ds:DigestValue>
            </ds:Reference>
        </ds:SignedInfo>
        <ds:SignatureValue> [...] </ds:SignatureValue>
        <ds:KeyInfo>
            <ds:X509Data>
                <ds:X509Certificate> [...] </ds:X509Certificate>
            </ds:X509Data>
        </ds:KeyInfo>
    </ds:Signature>
    <samlp:Status>
        <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success" />
    </samlp:Status>

    <saml:Assertion
      ID="..."
      IssueInstant="2020-11-03T09:19:36.785Z"
      Version="2.0">
        <saml:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">
            https://idserver.servizicie.interno.gov.it/idp/profile/SAML2/POST/SSO
        </saml:Issuer>
        <ds:Signature>
            <ds:SignedInfo>
                <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
                <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256" />
                <ds:Reference URI="...">
                    <ds:Transforms>
                        <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" />
                        <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
                    </ds:Transforms>
                    <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256" />
                    <ds:DigestValue> [...] </ds:DigestValue>
                </ds:Reference>
            </ds:SignedInfo>
            <ds:SignatureValue> [...] </ds:SignatureValue>
            <ds:KeyInfo>
                <ds:X509Data>
                    <ds:X509Certificate> [...] </ds:X509Certificate>
                </ds:X509Data>
            </ds:KeyInfo>
        </ds:Signature>
        <saml:Subject>
            <saml:NameID
              Format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient"
              NameQualifier="https://idserver.servizicie.interno.gov.it/idp/profile/SAML2/POST/SSO">
                RIFERIMENTO ID ENTE
            </saml:NameID>
            <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
                <saml:SubjectConfirmationData
                  InResponseTo="..."
                  NotOnOrAfter="2020-11-03T09:24:36.807Z"
                  Recipient="https://service_provider_assertion_consumer" />
            </saml:SubjectConfirmation>
        </saml:Subject>
        <saml:Conditions
          NotBefore="2020-11-03T09:19:36.785Z"
          NotOnOrAfter="2020-11-03T09:24:36.785Z">
            <saml:AudienceRestriction>
                <saml:Audience>https://sevice_provider</saml:Audience>
            </saml:AudienceRestriction>
        </saml:Conditions>
        <saml:AuthnStatement
          AuthnInstant="2020-11-03T09:19:33.100Z"
          SessionIndex="....">
            <saml:AuthnContext>
                <saml:AuthnContextClassRef>https://www.spid.gov.it/SpidL3</saml:AuthnContextClassRef>
            </saml:AuthnContext>
        </saml:AuthnStatement>
        <saml:AttributeStatement>
            <saml:Attribute FriendlyName="Data di Nascita" Name="dateOfBirth" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
                <saml:AttributeValue xsi:type="xs:string">AAAA-MM-GG</saml:AttributeValue>
            </saml:Attribute>
            <saml:Attribute FriendlyName="Codice Fiscale" Name="fiscalNumber" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
                <saml:AttributeValue xsi:type="xs:string">TINIT-CODICE_FISCALE</saml:AttributeValue>
            </saml:Attribute>
            <saml:Attribute FriendlyName="Nome" Name="name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
                <saml:AttributeValue xsi:type="xs:string">NOME</saml:AttributeValue>
            </saml:Attribute>
            <saml:Attribute FriendlyName="Cognome" Name="familyName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
                <saml:AttributeValue xsi:type="xs:string">COGNOME</saml:AttributeValue>
            </saml:Attribute>
        </saml:AttributeStatement>
    </saml:Assertion>

Logout¶

Lo schema di autenticazione Entra con CIE, nella versione attuale, non implementa il Single logout SAML. Il meccanismo di logout previsto gestisce la sola sessione relativa all'Identity Provider non propagando il logout sulle relative sessioni dei Service Provider. A tal proposito é onere del Service Provider garantire il logout al proprio servizio autenticato tramite un apposito endpoint presente nei metadata dell'Identity Provider all'interno del tag <SingleLogoutService> che viene invocato mediante HTTP-GET e che reinderizza su una apposita pagina dell'IdP server CieID recante il messaggio "Logout effettuato con successo".

Schermata di conferma di avvenuto Logout.

Binding HTTP-POST¶

In questo tipo di binding, il messaggio HTTP contiene una form HTML all'interno della quale è codificato in formato Base64 il costrutto SAML firmato in accordo alla specifica XML Digital Signature. Il trasporto del messaggio di richiesta di autenticazione prevede due parametri fondamentali:

• SAMLRequest o SAMLResponse: contengono, rispettivamente, la codifica della <AuthnRequest> e della <Response>
• RelayState: indica la risorsa originariamente richiesta dall'utente e alla quale dovrà essere trasferito il controllo al termine della fase di autenticazione; puó essere un UUID, un url, un percorso di file o un mini-blob con codifica binaria Base64

La codifica Base64 é richiesta solo per i messaggi del protocollo SAML in formato XML SAMLRequest e SAMLResponse e non per il RelayState, che è un token specifico dell'applicazione usato per identificare lo stato, la cui codifica o decodifica é in carico all'applicazione stessa.

Binding HTTP-Redirect¶

Quando si usa un binding di tipo Redirect, la firma viene posta nella URL come query parameter. Tutti i parametri sono URL-encoded. Il messaggio HTTP trasporta i seguenti parametri

• SAMLRequest: Un costrutto SAML codificato in formato Base64 e compresso con algoritmo DEFLATE. Come da specifica, il messaggio SAML non contiene la firma in formato XML Digital Signature esteso (come avviene in generale nel caso di binding HTTP-POST). La specifica indica come modalità alternativa quella di specificare con parametri aggiuntivi l'algoritmo utilizzato per firmare (SigAlg) e la stringa con la codifica Base64 URL-encoded dei byte del messaggio SAML (Signature).
• RelayState: Identifica il servizio originariamente richiesta dall'utente e a cui trasferire il controllo alla fine del processo di autenticazione.
• SigAlg: Identifica l'algoritmo usato per la firma prodotta secondo il profilo specificato per SAML utilizzando chiavi RSA almeno a 1024 bit e algoritmo di digest SHA-256 o superiore;
• Signature: Contiene la firma digitale della query string, così come prodotta prima di aggiungere questo parametro, utilizzando l'algoritmo indicato al parametro precedente;

Esempio HTML di utilizzo¶

Di seguito un esempio di form HTML per trasferire in HTTP-POST la richiesta di autenticazione

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

<html>
    <head>
        [...]
    </head>
    <body onload="javascript:document.forms[0].submit()">
        <form method="post" action="https://idserver.servizicie.interno.gov.it/idp/profile/SAML2/POST/SSO">
            <input type="hidden" name="SAMLRequest"
                value="[...]">
            <input type="hidden" name="RelayState" value="...">
            <input type="submit" value="Invia"/>
        </form>
    </body>
</html>

Di seguito un esempio di form HTML per trasferire la risposta in HTTP-POST

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

<html>
    <head>
        [...]
    </head>
    <body onload="javascript:document.forms[0].submit()">
        <form method="post" action="https://service_provide_assertion_consumer">
            <input type="hidden" name="SAMLResponse"
                value="[...]">
            <input type="hidden" name="RelayState" value="...">
            <input type="submit" value="Invia"/>
        </form>
    </body>
</html>

La form HTML è corredata da una istruzione che ne provoca il "post" automatico (se Javascript è abilitato nel browser dell'utente) all'indirizzo indicato nell'attributo action. Quindi, il browser dell'utente elabora la risposta HTTP e invia una richiesta HTTP POST verso il servizio dell'entità destinataria.

Metadata¶

In riferimento ai metadata, diversamente da quanto previsto per SPID, lo schema Entra con CIE prevede un unico modello di metadata indipendentemente dal ruolo che il soggetto svolge nell'ambito dello schema SPID. In particolare i due elementi nei quali si hanno maggiori impatti sono:

• l'elemento <AttributeConsumingService> che contiene il set di attributi richiesti in fase di autenticazione prevede, attualmente, solo e soltanto gli attributi relativi al Minimum Dataset eIDAS o suoi sottoinsiemi;
• l'elemento <ServiceName> può contenere un UUID v.4 dell'attribute set richiedibile dal SP, comprensivo dell'attributo xmlns:lang, valorizzato con una stringa vuota;
• l'elemento <md:Organization> che contiene i dati del Service Provider in veste di persona giuridica;
• gli elementi <ContactPerson> che dovranno contenere le informazioni di censimento e contatto del Service Provider e dell'eventuale partner tecnologico (cfr. Federazione).

I dati identificativi del Service Provider e del partner tecnologico devono coincidere con quelli inseriti in fase di richiesta di adesione. Per maggiori dettagli consultare il capitolo Federazione.

Protocolli di comunicazione¶

I protocolli di comunicazione previsti da entrambi gli schemi (Entra con CIE e SPID) sono basati sullo standard SAML versione 2.0 e, dunque, ereditano da esso le principali specifiche tecniche. Tuttavia, nella modalità specifica secondo la quale gli schemi di identificazione sono declinati è possibile individuare alcune lievi differenze che possono avere un impatto sull'implementazione da parte del Service Provider.

Nella costruzione della richiesta di autenticazione <AuthnRequest> è necessario valorizzare l'attributo Destination coerentemente con l'attributo Location presente nel tag SingleSignOnService riportato nel metadata dell'IdP e relativo al particolare binding utilizzato in fase di richiesta (cfr. Protocolli di comunicazione e Modalitá di trasmissione dei messaggi per ulteriori dettagli).

Per quanto riguarda il parsing e la verifica dei messaggi di response, il Service Provider deve tenere conto che, diversamente da quanto previsto da SPID,

• l'attributo Format dell'elemento <samlp:Issuer> non è presente;
• gli attributi inviati in risposta alla richiesta di autenticazione comprendono sempre almeno il Minimum Dataset eIDAS e non è previsto l'invio dello spidCode.

Troubleshooting¶

Prima di procedere con la richiesta di supporto ai referenti tecnici dell'Identity Provider, si consiglia di verificare la correttezza sintattica e semantica dei metadata come specificato nella sezione Federazione nonché la corretta implementazione dei Protocolli di comunicazione e delle Modalitá di trasmissione dei messaggi. In particolare, al fine di agevolare le attivitá di integrazione e test dei Service Provider (SP), di seguito si riporta un elenco non esaustivo di potenziali problemi che possono impedire la corretta autenticazione con una indicazione delle relative azioni di troubleshooting che si consiglia di intraprendere:

Nel caso il Service Provider, a seguito di una corretta autenticazione, non venga reindirizzato correttamente all'URL richiesta, é necessario che verifichi che gli attributi

• AttributeConsumingServiceIndex,
• AssertionConsumerServiceURL,

siano correttamente referenziati in modo coerente con quanto riportato all'interno dei metadata (ad esempio, tramite le loro referenze numeriche, assegnate mediante gli attributi index).

Sigilli di federazione¶

Tutti gli enti federati, cioè i soggetti che entrano nella federazione CIE - ad esempio Service Provider (SP) e Identity Provider (Id) - utilizzano chiavi crittografiche private sotto il loro esclusivo controllo per:

• creare un sigillo elettronico sul metadata propro di ciascun ente federato;
• creare sigilli elettronici sulle richieste di autenticazione (request) inviate dagli SP all'IdP;
• creare sigilli elettronici sulle asserzioni (assertion) e sulle risposte di autenticazione (response) restituite dall'IdP agli SP;
• zcifrare i messaggi scambiati con altri enti federati.

I sigilli elettronici apposti in modalità enveloped sulle evidenze SAML (cioè all'interno dello stesso documento XML che rappresenta il metadata, la request o la response), denominati sigilli di federazione, sono contenuti nell'elemento <Signature> in testa all'evidenza. I certificati elettronici per:

• la creazione di sigilli elettronici sulle request, le assertion e le response;
• la cifratura dei messaggi scambiati tra enti federati;

sono contenuti, all'interno di elementi <KeyDescriptor> con attributo <use> valorizzato, rispettivamente, come <signing> o <encryption>. I certificati elettronici afferenti a chiavi crittografiche utilizzate dagli enti federati per altri scopi sono contenute in ulteriori estensioni SAML dei metadata. Tutti i sigilli di federazione devono essere acclusi per intero mediante elementi <KeyInfo> contenenti il payload del certificato in un elemento <X509Certificate>. Tali elementi rispettano lo standard XML Signature Syntax and Processing del W3C, nella versione riportata nelle specifiche SAML di riferimento per lo schema CieID.

Struttura dei certificati di federazione¶

I certificati di federazione sono conformi con quanto previsto dalla normativa RFC 5280 e rispettano anche la normativa comunitaria ETSI in materia di sigilli elettronici avanzati.

I Service Provider possono, per il momento, adottare anche certificati generati in modalità self-signed. Tali certificati, però, perdono la denominazione di sigilli di federezione.

In tutti i certificati di sigillo elettronico (non trattandosi di certificati di firma elettronica), è vietato l'uso delle seguenti estensioni X.509 / X.520:

• name (OID 2.5.4.41),
• surname (OID 2.5.4.42),
• initials (OID 2.5.4.43),
• generationQualifier (OID 2.5.4.44),
• familyInformation (OID 2.5.4.64),
• pseudonym (OID 2.5.4.65).

Ulteriori estensioni possono essere presenti nei certificati, purché non vadano in contrasto con le attuali specifiche tecniche e con le norme e standard qui richiamati.

Algoritmi crittografici¶

Per la creazione di sigilli elettronici è utilizzato l'algoritmo crittografico RSA con lunghezza delle chiavi di almeno 1024 bit e algoritmo di hash SHA-256 o superiore (cioè con lunghezza dell'impronta crittografica pari almeno a 256 bit).

Per gli scopi di cifratura dei messaggi è adottato l'algoritmo crittografico AES con lunghezza delle chiavi di almeno 256 bit.