4. Gestione errori di verifica delle asserzioni | Fascicolo Sanitario Elettronico

Se la validazione dell’asserzione SAML fallisce, l’attore raggruppato con l’entità X-Service Provider DEVE restituire un codice di errore come descritto nelle specifiche tecniche OASIS WS-Security section 12 “Error Handling” usando il meccanismo SOAP Fault.

Le classi di fault che possono essere generati da un attore X-Service Provider sono descritti nella seguente tabella.

[ERROR_CODE]	Descrizione
wsse:FailedCheck	La firma dell’asserzione non è corretta
wsse:SecurityTokenUnavailable	La richiesta di servizio non veicola all’interno della porzione WS-Security un’asserzione di identità SAML 2.0
wsse:MessageExpired	Intervallo di validità dell’asserzione non corretto
wsse:InvalidSecurityToken	Parte del contenuto dell’asserzione non è conforme ai requisiti necessari per accedere al servizio richiesto
wsse:FailedAuthentication	Non è possibile autenticare l’utente o verificare la validità dell’asserzione

La struttura del messaggio di risposta veicolante una condizione di errore deve essere conforme allo standard SOAP 1.2 (per individuare la classe di errore) ed allo standard WS-BaseFault 1.2 (che permette di dettagliare la condizione di errore: “Web Services Base Faults 1.2”).

L’header del messaggio di risposta deve veicolare le informazioni che permettono di associare la risposta contenente il fault al messaggio di richiesta che non è stato possibile processare.

La classe del fault generato è descritta all’interno del body del messaggio SOAP attraverso l’utilizzo dei seguenti elementi:

<Code>: veicola un codice di fault (un elemento <value>).
- <Value>: valore che permette di descrivere la classe di errore (con soap=http://www.w3.org/2003/05/soap-envelope):
  - soap:Receiver, soap:Sender, soap:MustUnderstand, soap:VersionMismatch, soap: DataEncodingUnknow.
<Reason>: veicola le stringhe di testo che descrivono la condizione di errore (questo campo si utilizza come indicato nella definizione precedente in corrispondenza dello specifico codice di errore).
- <Text>: elemento specifico che permette di comunicare la stringa corrispondente ad un errore; i possibili valori sono specificati nella colonna “Messaggio di errore” al paragrafo 5.3;
  - @xml:lang: deve assumere valore fisso “en”;
<Detail>: contiene uno specifico elemento, del tipo BaseFault, caratterizzante la specifica tipologia di errore (es. <wsse:FailedCheck>, <wsse:InvalidSecurityToken,…). Questo elemento contiene una serie di sotto-elementi definiti dallo standard WS-BaseFault:

<wsrf-bf:Timestamp>: istante temporale in cui si è generato l’errore;
<wsrf-bf:ErrorCode>: elemento che contiene lo specifico codice di errore, tra quelli nella colonna Codice nelle tabelle al paragrafo 5.3;
<wsrf-bf:Description>: descrizione dell’errore.

Di seguito è presentato un esempio di condizione di fault da inserire nell’elemento body del messaggio SOAP. In particolare, l’esempio fa riferimento all’errore sollevato nel caso in cui è ricevuta una richiesta di ricerca documenti per un paziente che non ha fornito il consenso alla consultazione.

<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope" xmlns:env="http://www.w3.org/2003/05/soap-envelope">
    <S:Header>
        <To xmlns="http://www.w3.org/2005/08/addressing">http://www.w3.org/2005/08/addressing/anonymous</To>
        <Action xmlns="http://www.w3.org/2005/08/addressing">http://www.w3.org/2005/08/addressing/fault</Action>
        <MessageID xmlns="http://www.w3.org/2005/08/addressing">uuid:7910dda7-f3f4-449c-809b-233be3507add</MessageID>
        <RelatesTo xmlns="http://www.w3.org/2005/08/addressing">uuid:f4a3583d-3e3b-43c2-8f12-4c7e5c7cef48</RelatesTo>
    </S:Header>
    <S:Body>
        <S:Fault xmlns:ns4="http://schemas.xmlsoap.org/soap/envelope/">
            <S:Code>
                <S:Value>S:Sender</S:Value>
            </S:Code>
            <S:Reason>
                <S:Text xml:lang="en">Missing consultation consent</S:Text>
            </S:Reason>
            <S:Detail>
                <wsse:InvalidSecurityToken xmlns:schemaLocation="http://docs.oasisopen.org/wsrf/bf-2 bf-2.xsd" xmlns:wsrf-bf="http://docs.oasis-open.org/wsrf/bf-2" xmlns:wsse="http://docs.oasis-open.org/wsrf/r-2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                    <wsrf-bf:Timestamp>2017-05-30T16:22:27.605Z</wsrf-bf:Timestamp>
                    <wsrf-bf:ErrorCode dialect="http://www.fascicolosanitario.gov.it/interop-errorcodes">PFA11</wsrf-bf:ErrorCode>
                    <wsrf-bf:Description>Missing consultation consent</wsrf-bf:Description>
                </wsse:InvalidSecurityToken>
            </S:Detail>
        </S:Fault>
    </S:Body>
</S:Envelope>