1.Tjänstekontrakt och dokumentation

E-hälsomyndighetens tjänster tillhandahålls med WSDL med tillhörande XSD-scheman. Varje tjänst implementerar en operation per tjänstekontrakt i enlighet med RIV TA.

En tjänst med namnet Tjanst i version <version> som tillhör tjänstedomänen <domän> återfinns som:
 

Exempel:

 
Tjänstepaketen finns att hämta på E-hälsomyndighetens kundyta i Bibliotek Releaseinformation.

Dokumentationen om E-hälsomyndighetens tjänster är grupperad per tjänstedomän och återfinns i en funktionsspecifikation med namnet <domän>_Funktionsspecifikation-<versionspaket>.pdf.

Exempel: OR_Funktionsspecifikation-17.1.pdf

2. Anrop av tjänst

Användare av webbtjänster hos E-hälsomyndigheten är aktörers system och kan delas upp i tre olika kategorier:  

• Vård- och apotekspersonal
• Privatperson
• Maskinanvändare

För ytterligare information om roller och attribut se Kravspecifikation Behörighetsstyrning 17.1 (E002-Behörighetsstyrning).


Strukturen på ett SOAP-meddelande för anrop av en tjänst hos E-hälsomyndigheten:

​Vård- eller apotekspersonal	Privatperson​	Maskinanvändare​
​	​	​
Rollerna inom Vård- och apotekspersonal anropar E-hälsomyndighetens tjänster med ett Saml-intyg alternativt OAuth2-åtkomstintyg. För information om hur ett åtkomstintyg genereras, se OAuth2 tokenservice nedan. Saml-intyget ska vara utfärdat av en IdP ansluten via en av E-hälsomyndigheten godkänd operatör​. I anropet skickas ett SOAP:Header-element, med namnet ”Security”. Detta element ska innehålla ett SAML2:Assertion. SAML2:Assertion innehåller bland annat: SAML2:Issuer - namnet på användarorganisationens identitetsintygsutgivare (Identity Provider, IdP).  DS:Signature - innehåller bland annat utställarens krypterade certifikat SAML2:Conditions - giltighetstiden för intyget SAML2:Audience -  tjänsteleverantören (Service Provider, SP) som intyget är utställt till. Endast av E-hälsomyndigheten godkända tjänsteleverantörer ges tillgång till webbtjänster SAML2:AuthnContext - tillitsnivå (Level of Assurance, LOA) SAML2:Attribute - information om den person intyget avser För mer information om Sambi, se http://sambi.se/teknik. För information om innehållet i EHM:Systeminformation se nedan. Tjänstens anropsdata placeras i SOAP:Body. För ett komplett anropsexempel, se Anropsexempel Saml-intyg Anropsexempel med Sambi-intyg.xml​	​Rollen Privatperson anropar E-hälsomyndighetens tjänster med e-legitimation alternativt OAuth2-åtkomstintyg. För information om hur ett åtkomstintyg genereras, se OAuth2 tokenservice nedan. För anrop med e-legitimation skickas ett SOAP:Header-element, med namnet ”Security”. Detta element ska innehålla ett SAML2:Response. SAML2:Response innehåller ett SAML2:Assertion som bland annat innehåller: SAML2:Issuer - användarorganisationens BankId intygsutgivare (Identity Provider, IdP).​ DS:Signature - innehåller bland annat utställarens krypterade certifikat SAML2:Conditions - giltighetstiden för intyget SAML2:Audience -  tjänsteleverantören (Service Provider, SP) som intyget är utställt till. Endast av E-hälsomyndigheten godkända tjänsteleverantörer ges tillgång till webbtjänster SAML2:AuthnContext - autentiseringsmetod SAML2:Attribute - information om den person intyget avser För mer information kontakta den IdP (Identity Provider) som levererar e-legitimationslösningen. För information om innehållet i EHM:Systeminformation se nedan. Tjänstens anropsdata placeras i SOAP:Body. För ett komplett anropsexempel, se  Anropsexempel eLeg	För maskinanvändare anges inget säkerhetsintyg i anropet.  För information om innehållet i EHM:Systeminformation se nedan. Tjänstens anropsdata placeras i SOAP:Body.

Sweden Connect
Som ett alternativ till Sambi finns Sweden Connect som ett möjligt alternativ för att ansluta till E-hälsomyndighetens tjänster. För vidare information om Sweden Connect se: https://samarbetsyta.ehalsomyndigheten.se/handboken/latest/utveckla-mot-e-haelsomyndighetens-tjaenster/arkitektur-och-saekerhet/saekerhetsloesning

Instruktionsmaterial för SAML-biljett
Sammanställt instruktionsmaterial för att komma igång med SAML-intyg finns på denna sida Instruktionsmaterial för SimpleSAML

2.1 Biljettens giltighetstid

En biljett får inte gälla i mer än 60 minuter. Att E-hälsomyndigheten har valt denna maxgräns är dels för att bibehålla en hög säkerhet kring dess tjänster, dels för att underlätta för aktörer att använda versionspaket 17.1 då föregående version också hade en maxgräns på 60 minuter. En högre tidsgräns hade resulterat i lägre säkerhet för E-hälsomyndighetens tjänster. 

E-hälsomyndigheten använder värdena i IssueInstant, NotBefore och NotOnOrAfter för att ta reda på en biljetts giltighetstid. IssueInstant är obligatoriskt. NotOnOrAfter är ej obligatoriskt enligt SAML-standarden men här frångår E-hälsomyndigheten standarden och säger att den är obligatorisk. Detta för att hålla en hög säkerhet i vår åtkomstlösning. NotBefore är ej obligatorisk och finns den ej med så använder E-hälsomyndigheten IssueInstant för att avgöra starttiden. IssueInstant är ett attribut i <saml2:Assertion>-elementet medan NotBefore och NotOnOrAfter finns som attribut i <saml2:Conditions>-elementet.

Observera! Alla anrop för en användare till E-hälsomyndighetens tjänster ska alltså inte göra en ny inloggning per anrop, utan istället använda sig av sin biljett så länge den är giltig.

2.1.1 Särskild hantering för PIRR/NEF avseende giltighetstid på SAML-intyg

Grundprincipen är att tjänsteanropen ska ske inom SAML-intygets giltighetstid, det vill säga 60 minuter.
I nuläget sker ett flertal tjänsteanrop av olika anledningar dagligen som då skulle ske utanför SAML-intygets giltighetstid.
För att inte få en stor påverkan har myndigheten beslutat att acceptera och ta emot tjänsteranrop med SAML-intyg där giltigheten har förfallit.
Myndigheten kommer acceptera SAML-intyg upp till och med 24 timmar utifrån starttidpunkten för intygets giltighetstid.

Denna funktionalitet finns även för OAuth2-åtkomstintyg.

Implementationsinstruktioner för systeminformation

För att bedriva ett kvalitets- och säkerhetsarbete både för anropande och svarande part är det nödvändigt med information om vilket godkänt system som skapat, förändrat eller expedierat ett recept eller annan datamängd i de register som ägs, förvaltas eller förmedlas av E-hälsomyndigheten. Därför är det ett krav att vid samtliga anrop av E-hälsomyndighetens tjänster alltid ange "systemnamn" och "systemversion". I det fall "modulversion" finns bör även detta anges. Detta är motsvarande systeminformation som tidigare skickades med biljetten.

Ett SOAP:Header-element vid namn ”ehm”, skickas med i anropet.

 
 
 
Attribut för systeminformation:
 

Informationen i fälten får endast innehålla tecken i enlighet med följande kravdokument:
Tillåtna tecken i element och attributdata
 
 
Observera att

• Namespace-prefixet wsse är obligatoriskt på Security-elementet. Se exempel ovan.

3. OAuth2 tokenservice

E-hälsomyndigheten har utvecklat en ny tjänst, OAuth2 tokenservice, som kan användas för att byta ett SAML-intyg mot ett OAuth2-åtkomstintyg (access-token). OAuth2-åtkomstintyget kan sedan användas för åtkomst till myndighetens tjänster. Idag har det genererade åtkomstintyget en giltighetstid på 60 minuter. Observera - skulle ett anrop till E-hälsomyndighetens tjänster innehålla både ett OAuth2-åtkomstintyg och ett Saml-åtkomstintyg så valideras endast OAuth2-åtkomstintyget och inte Saml-åtkomstintyget.

client-secret
För att anropa OAuth2 tokenservice krävs autentiseringsuppgifter som erhålls från E-hälsomyndighetens Servicedesk. E-hälsomyndigheten skapar client och secret som tilldelas en specifik aktör. Detta lösenord används av aktörssystemen som identifiering vid all intygsväxling.

3.1 Intygsväxling av SAML-intyg mot access-token

Anropet görs med ett http-anrop till <host>/oauth2/api/oauth/token och skickas med content-type "application/x-www-form-urlencoded".

Exempel på ett request:

Exempel på ett response:

3.2 Vidare åtkomst till E-hälsomyndighetens API-SP (Resource Server)

För kommunikation med E-hälsomyndighetens tjänster med det genererade åtkomstintyget anropas API-SP med ett soap-anrop <host>/apisp/<tjänstens namn>Responder/V1.
Observera! Alla efterföljande anrop för denna användare till E-hälsomyndighetens tjänster ska alltså inte göra intygsväxlingen igen, utan istället använda sig av access token så länge den är giltig.
Anropet kräver access_token som en http-header. Se exempel:

Beskrivning av anropsflödet för OAuth2 finns på Beskrivning Anropsflöde OAuth 2.0
 

3.3 ​OAuth2

OAuth2 är en teknisk säkerhetslösning som bygger på öppna standarder framtagna för OAuth2. Huvudsakligen

• RFC7522 (Security Assertion Markup Language (SAML) 2.0 Profile for OAuth 2.0 Client Authentication and Authorization Grants, https://tools.ietf.org/html/rfc7522)  
• RFC6749 (The OAuth 2.0 Authorization Framework https://tools.ietf.org/html/rfc6749).
  

3.4 Utökad giltighetstid för åtkomstintyg av vissa tjänster för dosaktör

Dosaktörers verksamhet skiljer sig från övriga öppenvårdsapotek. E-hälsomyndigheten stödjer därför längre giltighetstid på 720 minuter för åtkomstintyg till följande tjänster:

• GodkannDosunderlag
• GodkannProduktionsuttag
• GodkannUttag
• HamtaAktuellaOrdinationer
• HamtaExpeditionsid 
• HamtaGallandeUnderlagsversion
• HamtaHkdbInformation
• HamtaHkdbkonto
• HamtaIckeaktuellaOrdinationer
• HamtaKundinfo
• HamtaProduktionsunderlag
• KontrolleraUttag
• Prisfraga
• RapporteraExpeditionLF
• RegistreraHkdbTransaktion
• SkrivUtDosrecept
• UppdateraForsaljningOppenvardFörskrivning
• UppdateraVardtagarinformation
• UppdateraBestallningsstatus
• UppdateraProduktionsinformation

Förutsättning för att få utökad giltighetstid är:

• ​att anropande apotek är ett dosapotek
  
• endast anrop till tjänsterna beskrivna ovan
• endast användning av åtkomstlösning OAuth2 och åtkomstintyg och förnyelseintyg

Åtkomstlösning i alla tjänster är via OAuth2 2.0 och åtkomstintyg. Den maximala giltighetstiden för ett dosapotek att anropa ovan tjänster utan att göra en ny inloggning är 720 minuter. Det förnyelseintyg klienten får är alltså giltigt i 660 minuter (åtkomstintyget är giltigt 60 minuter). 

Beskrivning Anropsflöde OAuth 2.0 beskriver hur en klient förväntas använda sig av åtkomstintyg och förnyelseintyg i anropen mot E-hälsomyndighetens tjänster.
För behörighet att anropa ovanstående tjänster, se Behörighetsstyrning från och med release17.1