Ämne Version Datum Introduktion MVK SSO 2.0 1.7 2014-02-14 Ansvarig Dokument ID Sign Martin Carlman/Peter Bäck MVK-0031 Version Datum Av Avsnitt Ändring 1.7 140214 AL MVK SSO 2.0 Mina vårdkontakter MVK SSO 2.0 introduktion 1 (19)
Innehållsförteckning 1 Inledning... 3 1.1 Revisionsinformation... 3 1.2 Referensdokument... 3 2 MVK SSO-tjänst ValidateToken... 4 2.1 Om tjänsten... 4 2.2 Exponering av tjänster mot användare... 5 2.2.1 Listning/Vårdval... 5 2.2.2 Betjäningsområde... 5 2.2.3 Vårdrelation med filöverföring... 5 2.2.4 Individuellt anpassad åtkomst... 5 2.2.5 Åtkomst för vårdpersonal... 5 2.3 Möjliga anpassningar i användargränssnittet... 6 2.3.1 Invånare... 6 2.3.2 Vårdpersonal... 8 2.4 Informationsutbyte... 9 2.4.1 Interface ValidateToken... 9 2.4.2 Affärsobjektet - ValidateIDType... 9 2.4.3 Affärsobjektet ValidateIdResponseType... 10 2.4.4 Affärsobjektet SSOObjectType... 11 2.4.5 Affärsobjektet Healthcare_facility... 12 2.4.6 Felmeddelanden... 12 2.5 Teknisk anslutningsinformation... 14 2.5.1 WSDL... 14 2.5.2 Säkerhetslösning... 14 2.6 Testdata... 15 3 MVK SSO-tjänst PushId... 16 3.1 Om tjänsten... 16 3.2 Informationsutbyte... 16 3.2.1 Affärsobjektet - PushIdType... 16 3.2.2 Affärsobjektet SSOObjectType... 16 3.2.3 Affärsobjektet Healthcare_facility... 17 3.2.4 Affärsobjektet PushIdResponseType... 17 3.2.5 Felmeddelanden... 17 3.3 Teknisk anslutningsinformation... 18 3.3.1 WSDL... 18 3.3.2 Säkerhetslösning... 18 4 Checklista vid anslutning till MVK SSO... 19 MVK SSO 2.0 introduktion 2 (19)
1 Inledning Dokumentet beskriver Mina vårdkontakters SSO-tjänst och är tänkt att vara en introduktion som beskriver tjänsten, vad som krävs för att ansluta sig och vilka konfigurationer och anpassningar som är möjliga. 1.1 Revisionsinformation Utgåva Datum Ansvarig Kommentar 1.00 2010-12-22 MC Fastställd version 1.1 2011-09-16 MC Uppdateringar gällande tjänster för vårdpersonal. Förtydliganden i beskrivningar av tjänsten. 1.3 2011-10-20 EE Lagt till information om PushID. 1.4 2011-11-17 EE Lagt till information om testpersoner och testenheter. 1.5 2012-01-04 EE Förtydligat information i checklistan kring certifikat och Subject CN. 1.6 2012-04-25 EE Ändrat i beskrivningen för objektet healthcarefacility i validatetokenresponse så att det står att healthcare_facility_name inte skickas med. 1.7 2014-02-14 AL Uppdaterat efter förändringar från och med MVK ver 6.x 1.2 Referensdokument Referens Namn Beskrivning REF01 WSDL, SSO2.0 Tjänstebeskrivning MVK SSO 2.0 introduktion 3 (19)
2 MVK SSO-tjänst ValidateToken 2.1 Om tjänsten Mina vårdkontakter (MVK) har en single-signontjänst för att ge åtkomst till andra system. Därigenom får dessa system möjligheten att använda basfunktioner som autentisering och styra åtkomst. Tjänsten används för att styra autentiserade användare vidare till externa system och det innebär att användaren inte skall behöva logga på det externa systemet separat. När tjänsten (SSO) anropas öppnas ett nytt webbläsarfönster och man lämnar MVK. I SSO-tjänsten finns inget stöd för att återföra information eller status till MVK, vill man göra detta finns andra tjänster tillgängliga. Användare 1. Login 5. MVK URL + GUID MVK 2. Webb URL 3. Skapa ID 6. Validera ID Externt system 7. Extern webb 4. GUID Create Token Validate Token GUID storage asb.minavardkontakter.se Figur 1 - Översikt MVK SSO 1. Användare loggar in på tjänsten MVK (invånare eller vårdpersonal). 2. Invånare: Användargränssnittet i MVK anpassas efter invånarens folkbokföring, listningsuppgifter, inloggningssätt och övrig profilinformation. (t ex relation till specialistmottagning, relation till andra tjänster). Vårdpersonal: Användaren kommer till en startsida med översikt över mottagningar och tjänster som man har tillgång till. På respektive mottagning kan det exponeras tjänster via MVK SSO. Alla MVK SSO 2.0 introduktion 4 (19)
som har behörighet på mottagningen kommer åt tjänsten. 3. Användaren klickar på SSO URL till externt system. Autentiseringstjänsten initieras och unikt id genereras (GUID). ID samt övrig nödvändig information skickas till autentiseringstjänsten (CreateToken) 4. Unikt ID (GUID) returneras till MVK 5. Användaren öppnar SSO URL till externt system. URL innehåller ID(GUID). Ett nytt webbläsarfönster öppnas med den externa tjänsten och användaren upplyses om att man nu lämnar MVK. Det finns även möjligheter att definiera andra parametrar som skall skickas till det externa systemet i anropet. 6. Det externa systemet hämtar ID(GUID) samt validerar detta mot autentiseringstjänsten (ValidateToken) 7. Invånaren är nu validerad och inloggad i det externa systemets webb Tabell 1 Översiktlig flödesbeskrivning SSO tjänst 2.2 Exponering av tjänster mot användare De flesta tjänster i MVK exponeras endera genom att de tillhandahålls av en mottagning (HSAID) eller att de kategoriseras som en tjänstekategori (HSAID) under menyvalet Övriga tjänster. Tjänsterna konfigureras så att mottagningen styr vilka användare som kan använda tjänsten. En användare kan ges åtkomst till en mottagning eller tjänstekategori på de sätt som beskrivs nedan. 2.2.1 Listning/Vårdval Genom information från listningssystem får en användare tillgång till en mottagning där de är listade. 2.2.2 Betjäningsområde En mottagning kan sätta upp kriterier som ålder, kön och geografisk tillhörighet för att välja vilka användargrupper man vill exponera sig för. En lokal administratör på mottagningen kan bestämma och ändra vilket betjäningsområde som gäller och på så vis styra vilka som ska kunna använda tjänsterna. 2.2.3 Vårdrelation med filöverföring Det finns möjligheter att sätta upp en filöverföring med användaruppgifter för att tilldela och frånta behörighet till specifika mottagningar. En fil kan skickas regelbundet med olika kommandon (se tjänsten MVK Systemrelation). 2.2.4 Individuellt anpassad åtkomst Behörighet kan ges till en mottagning baserat på en användares personnummer (Godkänn för kommunikation). Det finns även möjlighet att ge vissa användare tillgång till specifika tjänster på mottagningen helt individuellt (Dela ut ärendetyp). Vårdpersonal vid mottagningen kan dela ut behörigheter både till mottagningen och specifika tjänster. En lokal administratör på mottagningen bestämmer vilka tjänster som behöver delas ut till specificerade användare. 2.2.5 Åtkomst för vårdpersonal En tjänst som skall exponeras för vårdpersonal delas ut av MVKs administratörer till en eller flera mottagningar. Tjänsten blir då tillgänglig för samtlig vårdpersonal med tillgång till mottagningen. MVK SSO 2.0 introduktion 5 (19)
2.3 Möjliga anpassningar i användargränssnittet Det finns en mängd information som går att anpassa kring tjänster som exponeras i MVK. En del av informationen kan anpassas av administratörer på mottagningen där tjänsten exponeras, annan basinformation måste anpassas av systemets administratörer vid uppstart av tjänsten. Systemadministratörer underhåller texter och adresser rörande anslutande tjänst, och ställer in önskad minsta säkerhetsnivå. Följande värden behöver tillhandahållas av integrerande system. 2.3.1 Invånare Följande inställningar är möjliga för invånare: Värde Beskrivning Exempel Titel Namn på tjänsten som visas för användare Boka tid direkt Titel, knapp Namn på knappen som startar tjänsten Starta tjänsten Säkerhetsnivå Anger om tjänsten kräver inloggning med e- legitimation Som ovan nämnts kan tjänster exponeras för en invånare endera genom mottagningens kontaktkort eller grupperas inom en tjänstekategori under menyvalet Övriga tjänster. På mottagningens kontaktkort visas en SSO-tjänst tillsammans med andra sk ärendetjänster knutna till en mottagning. Namn på tjänst Figur 2 SSO-tjänst, exponering på kontaktkort MVK SSO 2.0 introduktion 6 (19)
Under menyvalet Övriga tjänster visas de tjänster som inte är knutna direkt till en mottagning. Dessa grupperas inom olika tjänstekategorier. En tjänstekategori hanteras som en mottagning i MVK, vilket innebär att denna måste finnas i Hsa-katalogen. Beskrivningen av en tjänstekategori hanteras i MVK på samma sätt som övrig information för en mottagning. Om säkerhetsnivån för tjänsten ifråga inte är uppfylld kommer tjänsten inte att vara tillgänglig (klickbar). Figur 3 SSO-tjänst, exponering under Övriga tjänster När man sedan väljer en tjänst kommer man till en sida där villkorstexterna visas. Finns det inga villkorstexter kommer man förstås vidare direkt till tjänsten. Invånaren måste sedan bocka i rutan att man tagit del av villkorstexterna innan man kan klicka sig vidare till tjänsten. Namnet på knappen är konfigurerbart och kan variera mellan tjänsterna. Villkorstexterna kan redigeras lokalt (lokaladmin på mottagningen) eller centralt av MVK support. Figur 4 Villkorstexter för en SSO-tjänst MVK SSO 2.0 introduktion 7 (19)
2.3.2 Vårdpersonal Följande inställningar är möjliga för vårdpersonal: Värde Beskrivning Exempel Titel Namn på tjänsten som visas för användare Boka tid direkt Titel, knapp Namn på knappen som startar tjänsten Starta tjänsten Beskrivning Beskrivning av tjänsten som visas för användaren Säkerhetsnivå Anger om tjänsten kräver inloggning med e- legitimation Text säkerhetsnivå Beskrivande text som visas för användaren om man inte uppfyller säkerhetsnivån Denna tjänst kräver att du loggat in med e-legitimation Titel Beskrivning Text säkerhetsnivå Titel, knapp Figur 5 - SSO-tjänst, exponering GUI vårdpersonal MVK SSO 2.0 introduktion 8 (19)
2.4 Informationsutbyte Tjänsten ValidateToken validerar att inkommet token (GUID) är giltigt och aktivt. 2.4.1 Interface ValidateToken 2.4.1.1 Översikt 2.4.1.2 Namespace 2.4.1.3 Operation Validate 2.4.2 Affärsobjektet - ValidateIDType 2.4.2.1 Översikt Objektet beskriver global universal ID som används som token(biljett) mellan MVK och anropande system. MVK SSO 2.0 introduktion 9 (19)
2.4.2.2 Elementförteckning Element Typ Mandatory Kardinalitet Default Max längd Beskrivning (M)/ Optional (O) GUID String M 1..1 Den längd som angavs i CreateTokentjänsten 2.4.3 Affärsobjektet ValidateIdResponseType 2.4.3.1 Översikt 2.4.3.2 Elementförteckning Element Typ Mandatory (M)/ Optional (O) Kardinalitet Default Max längd Beskrivning statuscode String M 1..1 Giltiga värden: - OK - WARNING - ERROR statustext String O 0..1 Felmeddelande från SSO-tjänsten om statuscode = ERROR Ssoobject SSOObjectType O 0..1 MVK SSO 2.0 introduktion 10 (19)
2.4.4 Affärsobjektet SSOObjectType 2.4.4.1 Översikt 2.4.4.2 Elementförteckning Element Typ Mandatory (M)/ Kardinalitet Default Maxlängd Beskrivning Optional (O) GUID String M 1..1 Det GUID som skickades in till tjänsten SysId String M 1..1 Systemidentifierare (alltid MVK i nuläget) UserId String M 1..1 Användarens identifierare (personnr enl format XXXXXXXX-XXXX eller HSAID 1 ) AuthMethod String M 1..1 Säkerhetsnivå som användaren använt för att autentisera sig mot MVK. Giltiga värden: 1 - användarnamn 2 3 certifikat/ e-legitimation TokenTimeOut Int M 1..1 SSO-biljettens giltighetstid (i millisekunder) Cert String O 0..1 Används inte UserType String O 0..1 Typ av inloggad användare. Kan vara: INV - Invånare VA - Vårdpersonal 1 MVK konfigurerar per tjänst om personnummer eller HSAID skall returneras. 2 Invånare autentiserar sig med användarnamn, lösenord och engångskod vilket innebär tvåfaktor- inloggning. Vårdpersonal använder sig enbart av användarnamn och lösenord. MVK SSO 2.0 introduktion 11 (19)
healthcare_- facility healthcare_- facility O 0..1 SYSTEM - System 2.4.5 Affärsobjektet Healthcare_facility 2.4.5.1 Översikt 2.4.5.2 Elementförteckning Element Typ Mandatory (M)/ Optional (O) Kardinalitet Default Max längd Beskrivning resourcename String O 0..1 Används inte resourceid String O 0..1 Används inte healthcare_facility_id String O 0..1 HSAID för den enhet som exponerar tjänsten. healthcare_facility_name String O 0..1 Används inte 2.4.6 Felmeddelanden SSO-tjänsten delar in fel i två typer: - Logiska fel, - Exceptions 2.4.6.1 Logiska fel Logiska fel är förväntade fel som upptäcks och hanteras av tjänsten. Dessa fel returneras till anropande system genom att i response-objektet sätta följande element: - statuscode, sätts till ERROR - statustext, innehåller feltext till anropande system. Följande logiska fel kan inträffa i SSO-tjänsten och returneras i elementet statustext: statuscode statustext Orsak ERROR Token is NOT valid Token är inte längre giltig, validering av token inträffade utanför giltigt tidsintervall ERROR Error, unable to Ett oväntat fel inträffade under validering av token. Token kunde inte MVK SSO 2.0 introduktion 12 (19)
validate token. valideras. 2.4.6.2 Exceptions Exceptions är oförväntade fel som inträffar under exekvering i SSO-tjänsten. Exceptions hanteras inte av SSO-tjänsten utan returneras som SOAP Exception. MVK SSO 2.0 introduktion 13 (19)
2.5 Teknisk anslutningsinformation SSO-tjänsten består av två tjänster: CreateToken - en intern tjänst som endast konsumeras av MVK. ValidateToken - den publika tjänsten som anslutande parter skall konsumera. Den publika tjänsten - ValidateToken består av 1 operation: ValidateID. 2.5.1 WSDL Tjänstens WSDL finns att hämta via nedanstående URL (Se även bilaga WSDL, SSO2.0). Endpointaddresser Test: https://asbcacc.minavardkontakter.se/mvkasb_validateidweb/sca/validatetoken Prod: https://asbc.minavardkontakter.se/mvkasb_validateidweb/sca/validatetoken 2.5.2 Säkerhetslösning 2.5.2.1 Brandvägg Tjänsten är skyddad av brandvägg. Alla nya system som ska använda tjänsten måste registreras med de IP nummer som används för att beredas access. 2.5.2.2 Autentisering Autentisering och kryptering mellan anslutande system och MVK baseras på SITHS HCC funktion certifikat. HTTPS mutual authentication tillämpas (certifikatsbaserad autentisering). Anslutande system autentiseras med klientcertifikat. 2.5.2.3 Kryptering Kommunikation mellan anslutande system och MVK krypteras med HTTPS (TLS/SSL). Anslutande system måste lita på MVK servercertifikat, utfärdat av SITHS CA. 2.5.2.4 Servercertifikat MVK SSO-tjänsten använder servercertifikat utfärdat av SITHS. I produktion används SITHS CA v3. I testmiljö används SITHS CA Test v3. 2.5.2.5 Klientcertifikat MVK SSO-tjänsten kräver att anropande system använder sig av klientcertifikat utfärdat av SITHS HCC. Certifikatet ska vara av PKCS12 format. (*.p12-fil). Detta gäller för både test-miljö och produktionsmiljö. MVK SSO 2.0 introduktion 14 (19)
2.6 Testdata 2.6.1.1 Personer Mina vårdkontakter använder följande testpersoner (invånare) i sina testmiljöer Testperson Pnr Tolvan Tolvansson 19121212-1212 Testperson 1 19301229-9263 Testperson 2 19400107-9120 Testperson 3 19531224-2083 Testperson 4 19710301-1032 Testperson 5 19970516-2387 Skyddad Id 19420119-9124 2.6.1.2 Enheter Enheter som ska testas måste har korrekta HSAID och måste finnas i HSA katalogen för att kunna registreras i MVK testmiljö. Rekommenderat är att använda någon enhet som är tänkt att ingå i pilot eller acceptans drift för att vara säker på att ingen konflikt med andra system uppstår. MVK har ett antal testenheter men användandet av dessa måste stämmas av innan testerna planeras eftersom dessa kan användas av fler projekt samtidigt och användandet blir tidsbegränsat. MVK SSO 2.0 introduktion 15 (19)
3 MVK SSO-tjänst PushId 3.1 Om tjänsten OBS Används endast för test! Tjänsten PushId kan användas vid test för att generera upp ett token (GUID). 3.2 Informationsutbyte 3.2.1 Affärsobjektet - PushIdType 3.2.1.1 Elementförteckning Element Typ Mandatory Kardinalitet Default Max längd Beskrivning (M)/ Optional (O) TokenSize String O 0..1 Den längd som angavs i CreateTokentjänsten SSOObject SSOObjectType O 0..1 3.2.2 Affärsobjektet SSOObjectType 3.2.2.1 Elementförteckning Element Typ Mandatory (M)/ Optional (O) Kardinalitet Default Max längd Beskrivning SysId String O 0..1 Systemidentifierare (alltid MVK i nuläget) AuthMethod String O 0..1 Säkerhetsnivå som användaren använt för att autentisera sig mot MVK. Giltiga värden: 1 - användarnamn 3 3 certifikat/ e-legitimation TokenTimeOut Int O 0..1 SSO-biljettens giltighetstid (i millisekunder) Cert String O 0..1 Kan lämnas tomt healthcare_facility healthcare_facility O 0..1 3 Invånare autentiserar sig med användarnamn, lösenord och engångskod vilket innebär tvåfaktor- inloggning. Vårdpersonal använder sig enbart av användarnamn och lösenord. MVK SSO 2.0 introduktion 16 (19)
3.2.3 Affärsobjektet Healthcare_facility 3.2.3.1 Elementförteckning Element Typ Mandatory (M)/ Optional (O) Kardinalitet Default Max längd Beskrivning resourcename String O 0..1 Används inte resourceid String O 0..1 Används inte healthcare_facility_id String O 0..1 HSAID för den enhet som exponerar tjänsten. healthcare_facility_name String O 0..1 Namn i klartext på den enhet som exponerar tjänsten (namn i MVK) 3.2.4 Affärsobjektet PushIdResponseType 3.2.4.1 Elementförteckning Element Typ Mandatory Kardinalitet Default Max längd Beskrivning (M)/ Optional (O) GUID String O 0..1 Den längd som angavs i CreateTokentjänsten GUID 3.2.5 Felmeddelanden SSO-tjänsten delar in fel i två typer: - Logiska fel, - Exceptions 3.2.5.1 Logiska fel Logiska fel är förväntade fel som upptäcks och hanteras av tjänsten. Dessa fel returneras till anropande system genom att i response-objektet sätta följande element: - statuscode, sätts till ERROR - statustext, innehåller feltext till anropande system. 3.2.5.2 Exceptions Exceptions är oförväntade fel som inträffar under exekvering i SSO-tjänsten. Exceptions hanteras inte av SSO-tjänsten utan returneras som SOAP Exception. MVK SSO 2.0 introduktion 17 (19)
3.3 Teknisk anslutningsinformation Den publika tjänsten - PushId består av 1 operation: PushId. 3.3.1 WSDL Tjänstens WSDL finns att hämta via nedanstående URL Endpointaddress Test: https://asbcacc.minavardkontakter.se/mvk_ssoservice_certauthweb/sca/exports/pushid_cert_facade 3.3.2 Säkerhetslösning 3.3.2.1 Brandvägg Tjänsten är skyddad av brandvägg. Alla nya system som ska använda tjänsten måste registreras med de IP nummer som används för att beredas access. 3.3.2.2 Autentisering Autentisering och kryptering mellan anslutande system och MVK baseras på SITHS HCC funktion certifikat. HTTPS mutual authentication tillämpas (certifikatsbaserad autentisering). Anslutande system autentiseras med klientcertifikat. 3.3.2.3 Kryptering Kommunikation mellan anslutande system och MVK krypteras med HTTPS (TLS/SSL). Anslutande system måste lita på MVK servercertifikat, utfärdat av SITHS CA. 3.3.2.4 Servercertifikat MVK SSO-tjänsten använder servercertifikat utfärdat av SITHS. I testmiljö används SITHS CA Test v3. 3.3.2.5 Klientcertifikat MVK SSO-tjänsten kräver att anropande system använder sig av klientcertifikat utfärdat av SITHS HCC. Certifikatet ska vara av PKCS12 format. (*.p12-fil). Detta gäller för både test-miljö och produktionsmiljö. MVK SSO 2.0 introduktion 18 (19)
4 Checklista vid anslutning till MVK SSO Följande aktiviteter behöver genomföras i samband med en anslutning till MVK SSO. Aktivitet Miljö Aktör URL IP/hostnamn Klientcertifikat Servercertifikat Översiktlig dokumentation Drift och förvaltningsorganisation Urval Informationstexter Information om testsystem Testanvändare för MVK Verifiering vid anslutning Tidsplan för anslutning Kommentar QA eller produktion Invånare eller vårdpersonal URL till anslutande system (externt system) IP/hostnamn till anslutande system (externt system). Information nödvändig för brandväggsöppning. Detta ska skickas till kontaktperson på Softronic. Klientcertifikat ska vara av PKCS12-format. För autentisering av anropande använder SSO-tjänsten certifikatets Serialnumber som finns i Subject i certifikatet. Detta ska skickas till kontaktperson på Softronic. Anslutande system måste lita på SITHS CA v3 (produktion) samt SITHS CA Test v3 (test) Översiktlig dokumentation av anslutande system (externt system). Dokumentation bör belysa: - Flödesbeskrivning - Tillgänglighet och förväntade volymer - Säkerhet - Testmiljö och testdata Kontaktuppgifter/kontaktvägar till förvaltningsorganisation för tjänsten. Information om vilka användare tjänsten skall exponeras för (se även avsnitt 2.2 Exponering av tjänster mot användare). Information visas för invånaren. Namn på tjänst, rubriker och informationstexter (se avsnitt 2.3 Möjliga anpassningar i användargränssnittet ): - Namn på tjänsten - Namn på knapp som startar tjänsten - Beskrivning av tjänsten - Tjänstekategori - Säkerhetsnivå (e-leg/alla) - Text vid högre säkerhetsnivå Vid anslutning är det även önskvärt att det finns ett motsvarande testsystem att ansluta mot. Motsvarande information som för produktionssystemet behöver tillhandahållas. För att kunna verifiera att lösningen fungerar och för felsökning i förvaltningen behöver det finnas testpersoner upplagda i externt system. En plan för hur lösningen verifieras vid anslutning/driftsättning behöver fastställas i samband med projektstart. En tidplan för när tjänsten förväntas driftsättas och när tester skall genomföras. Observera att det är anslutande parts ansvar att se till att certifikat från SITHS är giltiga och att förnya dessa då giltighetstiden går ut. MVK SSO 2.0 introduktion 19 (19)