IH SAML F2F token. Datum: 1 September 2015 Publicatie: AORTA 2015 (V )

Transcriptie

1 IH SAML F2F token Datum: 1 September 2015 Publicatie: AORTA 2015 (V )

2 Inhoudsopgave 1 Inleiding Doel en scope Doelgroep voor dit document Documenthistorie Het SAML F2F token Structuur Assertion Namespaces Inhoud Uniekheid Afzender Onderwerp Geldigheid Ontvanger Authenticatie Doel Algoritmes Opbouw De digitale handtekening Plaats van het F2F token in het SOAP bericht Certificaten Te gebruiken certificaat en attributen Token afhandeling Verificatie met het bericht...13 Bijlage A Referenties AORTA_Auth_IH_SAML_F2F_Token.docxAORTA_Auth_IH_SAML_F2F_Token_ docx 2

3 1 Inleiding 1.1 Doel en scope Dit document heeft tot doel een handleiding te geven voor de implementatie van het koppelvlak tussen het goed beheerd patiënten portaal (GBP) en het landelijk schakelpunt (LSP) voor wat betreft de toe te passen technieken voor de authenticatie van patiënten. Dit document specificeert een SAML (Security Assertion Markup Language) token voor patiënten die zich fysiek (face-to-face) bij een (zorg)-medewerker (die aan de pilot deelneemt) gemeld hebben en waarbij de (zorg)-medewerker het BSN van de patiënt gecontroleerd heeft op basis van een Wettelijk Identiteits Document (WID=paspoort, rijbewijs, ID-kaart). Het SAML F2F-token is alleen bedoeld voor de pilot-situatie Nijmegen. Impliciet betekent het token tevens dat de patiënt onderdeel uitmaakt van de selecte pilot-populatie en accoord gaat met de voorwaarden. 1.2 Doelgroep voor dit document Dit document is bedoeld voor softwareontwikkelaars van het goed beheerd patiënten portaal en het LSP, die op grond van de HL7v3 communicatiestandaard en op grond van dit document berichten willen uitrusten met het SAML token. 1.3 Documenthistorie Versie Datum Omschrijving mei 2015 Initieel document juli 2015 Verwerking review WTE, RSC aug 2015 Wijziging n.a.v. besluiten dd AORTA_Auth_IH_SAML_F2F_Token.docxAORTA_Auth_IH_SAML_F2F_Token_ docx 3

4 2 Het SAML F2F token In dit hoofdstuk wordt de inhoud van het, door het GBP gecreëerde, SAML F2F token besproken. In tegenstelling tot de authenticatietokens, beschreven in de IH Berichtauthenticatie Burger [IH_Auth_Burger], is het token, beschreven in dit document, meer een bewering (assertion) dan een authenticatietoken. In het F2F-token wordt de volgende bewering gedaan: Patiënt met BSN is gezien door zorgverlener/medewerker met UZI; Het BSN is face-to-face gecontroleerd aan de hand van een geldig WID van de patiënt volgens het afgesproken proces binnen de pilot-situatie Nijmegen; Patiënt is deelnemer aan de pilot-patiëntenpopulatie. Alle XML voorbeelden in het document dienen door de betrokken partijen tijdens het bouwen van de uitwisseling getest, en waar nodig, in samenspraak met VZVZ aangepast te worden voor een juiste optimale werking. Voor het verkrijgen van het SAML F2F token en het aanbieden van dit token aan de ZIM worden het volgende profiel gebruikt: Het gebruik van het SAML F2F token (security token) in het kader van het WSS SOAP berichten profiel voor het veilig stellen en uitwisseling van authentieke SOAP berichten. Dit profiel raakt het koppelvlak: o goed beheerd patiëntenportaal (GBP) het landelijk schakelpunt (LSP) Dit profiel wordt in de volgende paragrafen verder uitgewerkt. 2.1 Structuur Het SAML F2F token is een door een Vertrouwde Identiteits Verstrekker gecreëerde SAML assertion die gebruikt wordt bij berichtauthenticatie van patiënten voor het LSP. De zorgverlener/medewerker ondertekent de Assertion met het handtekeningauthenticatiecertificaat 1 van diens UZI-pas. De Assertion wordt vervolgens door het GBP als securitytoken in het bericht opgenomen Assertion De assertion heeft de volgende structuur (de waarden die in het token gebruikt worden zijn fictief): Element/@Attribute Unieke identificatie van de 1 Versie van het SAML Protocol. Vaste waarde moet zijn 1 Tijdstip van uitgifte van de Assertion. Issuer 1 Bevat zowel de UZI van de zorgverlener/medewerker die de assertion heeft opgesteld alsmede diens 0 Niet 0 Niet gebruiken 1 N.a.v besluit [Blijst ]. Dit is hetzelfde certificaat als waarmee ook het UZI-token ondertekend wordt (zie [IH_Auth_UZI]) AORTA_Auth_IH_SAML_F2F_Token.docxAORTA_Auth_IH_SAML_F2F_Token_ docx 4

5 Niet 0 Niet gebruiken Signature 1 Bevat de handtekening over de assertion zoals gezet met behulp van de UZI pas van de zorgverlener of de UZI medewerkerpas van de medewerker. De handtekening dient geplaatst te zijn met behulp van het handtekeningen authenticatie certificaat op de pas. Subject 1 De gecontroleerde patient. BaseID 0 Niet gebruiken De ondertekening houdt impliciet in dat de face-to-face controle door de medewerker is uitgevoerd. NameID 1 Hierin komt het BSN van de gecontroleerde patient te staan. EncryptedID 0 Niet gebruiken SubjectConfirmation 1 Moet aanwezig 1 'urn:oasis:names:tc:saml:2.0:cm:holder-of-key SubjectConfirmationData 1 Moet aanwezig 1 Niet 0 Niet 0 Niet 0 Niet 0 Niet gebruiken KeyInfo 1 Referentie naar het servercertificaat van de applicatie van waaruit de assertion als token ingezet wordt. In de pilot betreft dit het GBP Nijmegen. Conditions 1 Moet aanwezig 1 Moet aanwezig zijn. Is gelijk aan het moment van de 1 Moet aanwezig zijn. Mag maximaal een half jaar liggen. Condition 1 Niet gebruiken AudienceRestriction 1 Moet aanwezig zijn Audience 1 urn:iiroot: :iiext:1 (is de ZIM) ProxyRestriction 0 Niet gebruiken Advice 0 Niet gebruiken AuthnStatement 0 Niet 0 Niet 0 Niet gebruiken AuthnContext 0 Niet gebruiken AuthnContextClassRef 0 Niet gebruiken. AttributeStatement 1 Moet aanwezig zijn Attribute 1 Moet aanwezig 1 Vaste waarde: Purpose AORTA_Auth_IH_SAML_F2F_Token.docxAORTA_Auth_IH_SAML_F2F_Token_ docx 5

6 Omschrijving AttributeValue 1 Geeft het doel aan waarvoor het token gebruikt wordt Namespaces Het door een Vertrouwde Identity Provider afgegeven SAML F2F token dat gebruikt wordt bij berichtauthenticatie, maakt gebruik van de volgende namespaces. De prefixen zijn niet normatief maar worden in dit document als voorbeelden gebruikt. Tabel AORTA.STK.t Namespaces Prefix ds saml Namespace URI urn:oasis:names:tc:saml:2.0:assertion Bij het gebruik van de namespace-prefixes is het van belang deze na het ondertekenen niet meer te veranderen omdat anders de digitale handtekening ongeldig wordt. 2.3 Inhoud De volgende paragrafen beschrijven de verschillende kenmerken en beveiligingsgerelateerde gegevens die het SAML authenticatietoken onderscheiden, zoals in [IH tokens generiek][ih tokens generiek] beschreven is. <saml:assertion xmlns:saml="urn:oasis:names:tc:saml:2.0:assertion" xmlns:ds=" > Op de plaats van de drie punten ( ) worden Uniekheidattributen opgenomen ten aanzien van de Assertion. Deze attributen worden beschreven in paragraaf Uniekheid Uniekheid <saml:assertion Version="2.0" ID="_dc9f793e2811b86f8e5cdf43ab5fd47d1fe0e61c" IssueInstant=" T18:50:27Z"> De attributen van het SAML assertion element maken van de afgegeven SAML assertion een uniek gegeven. Het attribuut ID identificeert op een unieke wijze de assertion. De ID is uniek per Issuer. De Issuer is ervoor verantwoordelijk dat de uniekheid van de ID gedurende een periode van een jaar rond IssueInstant gegarandeerd is. Het attribuut IssueInstant is een tijdsmoment van uitgifte van de SAML assertion. De tijdswaarde is gecodeerd in UTC. Het attribuut Version is de gebruikte SAML versie van de SAML assertion. De aanduiding voor de versie van SAML gedefinieerd in deze specificatie is "2.0". AORTA_Auth_IH_SAML_F2F_Token.docxAORTA_Auth_IH_SAML_F2F_Token_ docx 6

7 2.3.2 Afzender <saml:issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity"> : </saml:issuer> De Issuer verwijst naar de UZI van de zorgverlener/medewerker die de assertion heeft gegenereerd in combinatie met de rolcode van diezelfde zorgverlener/medewerker gescheiden door een dubbele punt (:). Verwacht wordt dat de zorgverlener/medewerker ook daadwerkelijk verbonden is aan de organisatie van waaruit de F2F-controle wordt uitgevoerd. Hiermee wordt bedoeld dat gastgebruik niet is toegestaan Onderwerp <saml:subject> <saml:nameid> </saml:nameid> <saml:subjectconfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:holder-of-key"> <saml:subjectconfirmationdata> <ds:keyinfo> <ds:x509data> <ds:x509issuerserial> <ds:x509issuername>cn=.., OU=.., O=.., C=NL</ds:X509IssuerName> <ds:x509serialnumber> </ds:x509serialnumber> </ds:x509issuerserial> </ds:x509data> </ds:keyinfo> </saml:subjectconfirmation> </saml:subject> Het onderwerp <Subject> bevat het BSN van de patiënt waarbij de F2F controle is uitgevoerd. Het BSN is opgenomen in het <NameID> element. De bevestiging van het onderwerp <SubjectConfirmation> wordt gebruikt om te bevestigen dat de assertion gegenereerd is voor een vertrouwde organisatie die vervolgens de assertion gebruikt als security token in berichten welke verzonden worden aan de ZIM. Voor deze bevestigingsmethode (het Method attribuut) moet de URN waarde "urn:oasis:names:tc:saml:2.0:cm:holder-of-key" worden gebruikt. Deze methode vereist dat er een referentie is naar het servercertificaat van de organisatie van waaruit het berichtenverkeer aan de ZIM wordt geïnitieerd. De referentie wordt opgenomen binnen een <KeyInfo> element binnen het element <SubjectConfirmationData>. Het <KeyInfo> element bevat zowel de <X509IssuerName> (de uitgever van het servercertificaat) als de <X509SerialNumber> (de feitelijke referentie naar het servercertificaat in decimal format ). In de <X509IssuerName> dienen de waarden CN, OU, O en C opgenomen te zijn zoals deze voorkomen op het servercertificaat. AORTA_Auth_IH_SAML_F2F_Token.docxAORTA_Auth_IH_SAML_F2F_Token_ docx 7

8 2.3.4 Geldigheid <saml:conditions NotBefore=" T18:48:27Z" NotOnOrAfter=" T18:52:27Z"> </saml:conditions> Op de plaats van de drie punten ( ) dient een AudienceRestriction te worden toegevoegd zoals beschreven in paragraaf Ontvanger). Het attribuut NotBefore is de tijd waarop de afgegeven SAML assertion geldig wordt. Wordt een bericht ontvangen voor NotBefore is aangevangen, dan moet dit bericht geweigerd worden. Het attribuut NotOnOrAfter is de tijd waarop de afgegeven SAML assertion vervalt. Wordt een bericht ontvangen op of nadat NotOnOrAfter is verstreken, dan moet dit bericht geweigerd worden. De subelementen Condition en ProxyRestriction worden niet gebruikt binnen het <Conditions> element bij F2F-tokens Ontvanger <saml:audiencerestriction> <!-- Root en extensie van de ZIM en het patiëntenportaal --> <saml:audience>urn:iiroot: :iiext:1</saml:audience> </saml:audiencerestriction> In de AudienceRestriction wordt beschreven aan welke ontvangende partijen (service providers) de SAML assertion is gericht. De waarden in de elementen zijn (voorlopig) vaste waarden. Voor de <Audience> parameter is gekozen voor een URN Authenticatie Aangezien er in dit type token geen sprake is van authenticatie, wordt het element AuthnStatement hier niet gebruikt Doel <saml:attributestatement> <saml:attribute Name="Purpose"> <saml:attributevalue> F2F WID Controle </saml:attributevalue> </saml:attribute> </saml:attributestatement> AORTA_Auth_IH_SAML_F2F_Token.docxAORTA_Auth_IH_SAML_F2F_Token_ docx 8

9 Via een extra attribuut genaamd Purpose wordt het doel van het token weergegeven. In het onderhavige document is dat de F2F WID controle maar in de toekomst zou hetzelfde token ook geschikt kunnen zijn voor de elab-toestemming. 2.4 Algoritmes Om de integriteit en onweerlegbaarheid van het SAML F2F-token te waarborgen wordt een XML Signature geplaatst, zoals beschreven in [IH tokens generiek][ih tokens generiek]. Na plaatsen van de XML Signature kan de ontvanger, met gebruikmaking van het publieke sleutel van het UZI handtekeningauthenticatie-certificaat van de verzender onomstotelijk vaststellen dat de getekende SAML assertion ondertekend is met de privé sleutel behorend bij het gebruikte UZI authenticatiehandtekening-certificaat van de UZIpas. De publieke sleutel van het UZI authenticatiehandtekening-certificaat bevindt zich in het UZI-LDAP register. De XML Signature van het SAML F2F-token die gebruikt wordt bij berichtauthenticatie voor Burgers maakt gebruik van de volgende algoritmes, zoals beschreven in [IH tokens generiek][ih tokens generiek]. Voor het berekenen van de hashwaarde wordt SHA-256 gebruikt. Voor de digitale handtekening in AORTA wordt gebruik gemaakt van een RSA handtekening over een SHA-256 digest. Omdat de XML Signature onderdeel is van het SAML F2F-token en in het SAML F2F-token geplaatst wordt, moet er een "enveloped-signature" transformatie uitgevoerd worden die de Signature tags uit het SAML F2F-token verwijderd. 2.5 Opbouw Na authenticatie en toegangsverlening van een patiënt op het GBP moet het GBP er zorg voor dragen dat, naast het SAML authenticatietoken, het SAML F2F-token eveneens wordt toegevoegd bij de berichten die van het GBP naar het landelijk schakelpunt worden verzonden. Het SAML F2F-token staat dus nooit alleen en dient altijd in combinatie met een SAML-authenticatie token (DigiD+SMS) voor te komen. Het SAML F2F token het <saml:assertion...> element is aangemaakt en gevuld met die elementen, zoals beschreven in de voorgaande paragrafen De digitale handtekening Het XML Signature blok is onderdeel van het SAML F2F token. Het XML Signature blok komt na het <saml:issuer> element van de <saml:assertion>. <ds:signature> <ds:signedinfo> <ds:canonicalizationmethod Algorithm=" <ds:signaturemethod Algorithm=" <ds:reference URI="#_b2728a3aa52c4779c4c77ab8dd8a7dda604c94c7"> <ds:transforms> <ds:transform Algorithm=" AORTA_Auth_IH_SAML_F2F_Token.docxAORTA_Auth_IH_SAML_F2F_Token_ docx 9

10 signature"/> <ds:transform Algorithm=" <ec:inclusivenamespaces PrefixList="ds saml xs"/> </ds:transform> </ds:transforms> <ds:digestmethod Algorithm=" <ds:digestvalue>675ga8kqgfqjsggsjhzovu+kgrlwqylptxj28gwlpkq=</ds:digestvalue> </ds:reference> </ds:signedinfo> <ds:signaturevalue>ecxg...igg==</ds:signaturevalue> <ds:keyinfo> <ds:x509data> <ds:x509issuerserial> <ds:x509issuername>cn=test UZI-register Zorgverlener CA G21, O=agentschap Centraal Informatiepunt Beroepen Gezondheidszorg, C=NL</ds:X509IssuerName> <ds:x509serialnumber> </ds:x509serialnumber> </ds:x509issuerserial> </ds:x509data> </ds:keyinfo> </ds:signature> In dit token wordt dus gebruik gemaakt van een certificaatreferentie via het certificate serial number (zie ook bijlage C, [IH_Auth_UZI]) Plaats van het F2F token in het SOAP bericht. Het F2F token moet, als tweede token, naast het SAML authenticatietoken in de WS- Security SOAP Header worden gezet. De plaatsing van de security tokens in het SOAP bericht is visueel weergegeven in Figuur 1Figuur 1. SOAP enveloppe Header DigiD + SMS Security token F2F Security token Body Payload: HL7v3 Figuur 1 Plaatsing van security tokens in een SOAP-bericht. Op het <wss:security> element moet een soap:mustunderstand="1" vlag opgenomen worden, die aangeeft dat de ontvanger dit security element moet verwerken en een soap:actor=" die aangeeft dat de ZIM dit security element verwerkt. Field Code Changed AORTA_Auth_IH_SAML_F2F_Token.docxAORTA_Auth_IH_SAML_F2F_Token_ docx 10

11 <soap:header xmlns:soap=" <wss:security xmlns:wss= " 1.0.xsd" soap:actor=" soap:mustunderstand="1"> <saml:assertion...> <saml:issuer>samlissuer</saml:issuer> <ds:signature xmlns:ds=" <ds:signedinfo>... </ds:signedinfo> <ds:signaturevalue>wuwn...5e4=</ds:signaturevalue> <ds:keyinfo>... </ds:keyinfo> </ds:signature>... Zie paragraaf InhoudInhoud... </saml:assertion...> </wss:security> </soap:header> <soap:body>... </soap:body> Field Code Changed Formatted: Font color: Auto Field Code Changed Formatted: Font color: Auto, Dutch (Netherlands) AORTA_Auth_IH_SAML_F2F_Token.docxAORTA_Auth_IH_SAML_F2F_Token_ docx 11

12 3 Certificaten 3.1 Te gebruiken certificaat en attributen Voor het tekenen van het SAML F2F-token wordt het authenticatiehandtekeningcertificaat van de persoonlijke UZI-pas gebruikt. Dit certificaat bevat een RSA publieke sleutel. Met de privé sleutel wordt de digitale handtekening gegenereerd. Voor de technische context en het feitelijk genereren van de digitale handtekening met een UZI-pas wordt verwezen naar respectievelijk bijlage B en Bijlage C uit het document IH Berichtauthenticatie met UZI-Pas [IH_Auth_UZI] met dien verstande dat in het F2F-token dus het handtekeningcertificaat 2 wordt gebruikt in plaats van het in de bijlagen vermelde authenticatiecertificaat. Voor de attribuutwaarden wordt eveneens verwezen naar document [IH_Auth_UZI], hoofdstuk 3 Certificaten. Om de digitale handtekening bij de ZIM te verifiëren, moet de ontvanger over de bijbehorende publieke sleutel beschikken, zie [IH tokens generiek][ih tokens generiek]. Voor verificatie is gekozen door een verwijzing naar het authenticatiehandtekeningcertificaat in het SAML F2F-token als KeyInfo mee te zenden; de ontvanger moet deze dan met bijvoorbeeld het LDAP protocol ophalen, zie ook [IH tokens generiek][ih tokens generiek]. 2 Technisch dus het certificaat met keyusage non-repudiation. AORTA_Auth_IH_SAML_F2F_Token.docxAORTA_Auth_IH_SAML_F2F_Token_ docx 12

13 4 Token afhandeling 4.1 Verificatie met het bericht Het is belangrijk vast te stellen dat velden in het SAML F2F-token overeenstemmen met die in het HL7v3 bericht en eveneens overeenstemmen met het SAML authenticatietoken wat verkregen is van DigiD. De SAML F2F assertion wordt door het GBP in de WS-Security SOAP Header geplaatst voor verzending naar de ZIM, zoals beschreven in paragraaf De ontvanger controleert of de WS-Security SOAP Header voor hem bestemd is, zie soap attribuut actor. Het SAML F2F-token wordt door de ontvanger uit de WS-Security SOAP Header gehaald indien de WS-Security SOAP Header voor de ontvanger bestemd is en aangegeven is dat de ontvanger deze moet verwerken. Daarnaast dienen de volgende controles uitgevoerd te worden: De aanduiding voor de versie van SAML gedefinieerd is op "2.0", zie paragaaf UniekheidUniekheid; De verschillende attributen die bij de bevestiging van het onderwerp horen voldoen aan de daarvoor gestelde eisen, zie paragraaf OnderwerpOnderwerp; De juiste afzender is vastgelegd, die deze assertion heeft gecreëerd en de patiënt F2F heeft gecontroleerd. De afzender wordt weergegeven in de vorm van een UZI in combinatie met de rolcode, zie paragraaf AfzenderAfzender. UZI-nummer en rolcode van de verantwoordelijke zorgverlener/medewerker dient overeen te komen met het UZI-nummer en rolcode van het certificaat waarmee het F2F-token ondertekend is; UZI-nummer van de verantwoordelijke zorgverlener/medewerker (zie paragraaf Afzender) dient te vallen onder de URA van de afzender. Gastgebruik is niet toegestaan. De digitale handtekening over het SAML F2F-token was geldig was ten tijde van de creatie van het SAML F2F-token. Dat wil zeggen dat de datum moet liggen binnen de geldigheidsduur van het certificaat waarmee de ondertekening is gedaan en het certificaat niet is ingetrokken voor ondertekening zie [IH_EH]. Het gebruikte certificaat geldig is ten tijde van ontvangst van het token, zie paragraaf 3.1 De SubjectConfirmation Method is holder-of-key. De KeyInfo in de SubjectConfirmationData verwijst naar een geldig servercertificaat van het GBP, zie paragraaf 2.3.3, welke ook gebruikt is voor de beveiligde connectie (TLS) van het GBP naar de ZIM; Het bericht is ontvangen binnen de geldigheidsperiode van het token, zie paragraaf GeldigheidGeldigheid; De ZIM is benoemd als afnemer van de assertion (audience), zie paragraaf OntvangerOntvanger; Naast het F2F-token dient tevens een SAML Authenticatietoken aanwezig te zijn. Er is een extra attribuut Purpose aanwezig die het doel van het token weergeeft. In de pilot betreft dit de F2F WID Controle ; Alleen die attributen zijn gedefinieerd, die zijn beschreven in paragraaf 2.3; AORTA_Auth_IH_SAML_F2F_Token.docxAORTA_Auth_IH_SAML_F2F_Token_ docx 13

14 Als aan één van de bovenstaande condities niet is voldaan, moet het bericht door de ontvanger geweigerd worden en een SOAP foutmelding aan het verzendende systeem afgegeven worden, zie foutafhandeling in [IH tokens generiek][ih tokens generiek]. Als wel aan alle condities is voldaan, wordt het HL7v3 bericht verder verwerkt. AORTA_Auth_IH_SAML_F2F_Token.docxAORTA_Auth_IH_SAML_F2F_Token_ docx 14

15 Bijlage A Referenties Referentie Document Versie [IH tokens generiek] Implementatiehandleiding security tokens generiek [SAML Assertion Protocol] [SAML Authn Context] [SAML Profiles] [SAML Token] [WSS] [DigiD] [HR Pat Auth] [IH_Auth_B urger] [IH_Auth_U ZI] Assertion and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0 os.pdf Authentication Context for the OASIS Security Assertion Markup Language (SAML) V2.0 Profiles for the OASIS Security Assertion Markup Language (SAML) v os.pdf SAML Token Profile SAMLTokenProfile.pdf WS-Security SOAP Message Security SOAPMessageSecurity.pdf Koppelvlakspecificatie DigiD SAML Authenticatie kspecificaties/koppelvlakspecificatie_saml_digid4_v3.0_definitief. pdf Handreiking Patiëntauthenticatie pdf ABntauthenticatie.pdf maart mrt mrt feb feb dec-2013 Field Code Changed AORTA_Auth_IH_Berichtauthenticatie_Burger.docx AORTA_Auth_IH_Berichtauthenticatie_UZI.docx [IH_EH] AORTA_Auth_Sig_IH_Elektronische_handtekening_UZI.doc [Blijst ] Besluiten VIP overleg docx AORTA_Auth_IH_SAML_F2F_Token.docxAORTA_Auth_IH_SAML_F2F_Token_ docx 15