​​​​​​​​​​​​

Anropsinformation - versionspaket 17.1


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:
 
​TjanstInteraction_<version>.wsdl ​Tjänstekontrakt
​TjanstResponder_<version>.xsd ​Tjänsteschema
​​se.apotekensservice_<domän>_<version>.xsd ​​Gemensamt schema som delas av flera tjänster
inom samma tjänstedomän

Exempel:

​HamtaAktuellaOrdinationerInteraction_5.1.wsdl ​Tjänstekontrakt för tjänsten HamtaAktuellaOrdinationer version 5.1
​HamtaAktuellaOrdinationerResponder_5.1.xsd ​Tjänsteschema för tjänsten HamtaAktuellaOrdinationer version 5.1
​se.apotekensservice_or_7.0.xsd ​Gemensamt schema som delas av flera tjänster inom domänen OR.


 
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​
​
SOAP-meddelande20assertion (002).png
 ​
SOAP-meddelande20response (002).png


 ​
SOAP-meddelande20maskin (002).png



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

 ​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 

 
 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.

<saml2:Assertion IssueInstant="2017-04-13T07:32:23.763Z">
<saml2:Conditions NotBefore="2017-04-13T07:32:23.763Z" NotOnOrAfter="2017-04-13T08:22:23.763Z">
.....
</saml2:Conditions>
</saml2:Assertion>

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.
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header>
<wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
.....
</wsse:Security>
<ehm:ehm xmlns:ehm="urn:riv:se.ehalsomyndigheten:core:systeminformation:4">
<ehm:systemnamn>Systemet ABC</ehm:systemnamn>
<ehm:systemversion>12.4</ehm:systemversion>
<ehm:modulversion>11111</ehm:modulversion>
<ehm:systeminformation>Aktörens systeminformation</ehm:systeminformation> 
</ehm:ehm>
</soapenv:Header>
<soapenv:Body>
</soapenv:Envelope>​
 
 
 
Attribut för systeminformation:
 
​Namn Beskrivning​​ Obligatorisk​​ Max antal tecken​
​systemnamn ​Aktörens systemnamn ​Obligatorisk ​20
​systemversion ​Aktörens systemversion ​Obligatorisk ​20
​modulversion ​Aktörens modulversion ​Valfri ​20
​systeminformation ​Aktörens systeminformation ​Valfri ​100

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:

POST [host]/oauth2/api/oauth/token HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: application/x-www-form-urlencoded
Authorization: Basic RUhNLVVTRVI6RUhNLVBTVw==
Content-Length: 6819
Host: [host]:[port]
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.5.2 (Java/1.8.0_152)
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2-bearer&assertion=[SAML2:Assertion]
 
 
​Inparametrar Beskrivning​​ Obligatorisk​​
grant_type ​“urn:ietf:params:oauth:grant-type:saml2-bearer“ Obligatorisk​​
​assertion ​Base64 encodat SAML2:Assertion. För privatpersonsanvändare med SAML2:Response måste detta konverteras till ett SAML2:Assertion. ​Obligatorisk​​
 

Exempel på ett response:

{
"access_token" : "[access_token]",
"expires_in" : 3600,
"token_type" : "bearer",
"refresh_token" : "[refresh_token]"
}
 

Utparametrar Beskrivning​​ Obligatorisk​​
access_token Krypterat access_token som endast kan läsas av eHälsomyndighetens API-SP (Resource Server). Kan användas vid anrop till E-hälsomyndighetens tjänster. Obligatorisk​​
​expires_in ​Giltighetstid på det returnerade access-token i sekunder från det att det genererades. Idag 3600 sekunder (60 minuter) Obligatorisk​​
​token_type ​"bearer" ​Obligatorisk​​
​refresh_token ​En refresh_token kommer att returneras vid intygsväxling med ​SAML-intyg. Denna refresh_token är giltig i 420 minuter (7 timmar) ​Valfri
 
 

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:
POST [host]/apisp/VerifieraLOA3Responder/V1 HTTP/1.1
Accept-Encoding: gzip,deflate 
Content-Type: text/xml;charset=UTF-8
SOAPAction: "urn:riv:se.apotekensservice:referens:VerifieraLOA3Responder:1:VerifieraLOA3"
Authorization: Bearer
[access_token]
Content-Length: 477
Host: 1.2.3.4:12380
Connection: Keep-Alive 
User-Agent: Apache-HttpClient/4.5.2 (Java/1.8.0_152)
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header>
<ehm:ehm xmlns:ehm="urn:riv:se.ehalsomyndigheten:core:systeminformation:4">
<ehm:systemnamn>Systemet ABC</ehm:systemnamn>
<ehm:systemversion>12.4</ehm:systemversion>
<ehm:modulversion>11111</ehm:modulversion>
<ehm:systeminformation>Aktörens systeminformation</ehm:systeminformation> 
</ehm:ehm>
</soapenv:Header>
<soapenv:Body>
<urn:VerifieraLOA3 xmlns:urn="urn:riv:se.apotekensservice:referens:VerifieraLOA3Responder:1"/>
</soapenv:Body>
</soapenv:Envelope>
 

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



E-hälsomyndighetens OAuth2-lösning stödjer följande ​E-hälsomyndighetens OAuth2-lösning stödjer tillsvidare INTE följande
  • Alla roller (vård, apotek samt privatperson) kan växla ett giltigt SAML-intyg till ett åtkomstintyg (access token) för vidare åtkomst
  • Alla tjänster från E-hälsomyndigheten kan anropas med en oAuth2 access token
  • Åtkomstintyget har en giltighetstid på 60 minuter
  • Via förnyelseintyget (refresh token) växla till sig ett nytt åtkomstintyg. Förnyelseintyget är giltigt i 420 minuter
  • Skapa client-secret
  • Byte av client-secret
  • Stöd för flödet Assertion Flow/Implicit flow
  • Åtkomstintyget (access token) som är av typen JSON Web Token (JWT), skyddas mot insyn med hjälp av JSON Web Encryption (JWE). Åtkomstintyget är därmed inte läsbart för annan part än E-hälsomyndigheten
  • HTTP Basic som autentiseringsmetod för klienter. [RFC 6749, 2.3.1]

  • Inget stöd för att invalidera eller avsluta ett giltigt åtkomstintyg innan dess giltighetstid är slut
  • Inget stöd för "prompt", det vill säga påkalla slutanvändarens uppmärksamhet
  • Inget stöd för introspection
 

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
 
 
​Utgåva ​Datum ​Kommentar
1.0​ ​2018- Ny publicering
​2.0 ​2018-10-12 Redaktionella ändringar
​3.0 ​2018-10-19 ​Förtydligande vad OAuth2lösningen stödjer
​3.1 ​2018-12-04 ​Förtydligande kring giltighetstid på biljett
​3.2 ​2018-12-05 ​Förtydligande hur access token bör användas
​3.3 ​2019-01-07 Uppdaterat att oAuth2-lösningen är tillgängligt för alla roller och alla eHm:s tjänster.
​3.4 ​2019-01-07 ​Uppdaterat varför eHälsomyndigheten har en maxgräns på 60 minuter på biljetten.
2.1.1 Lagt till stycke kring hantering av SAML-intyg.
6.0​ ​2019-02-08 ​Kapitel 2 Uppdaterat tabeller för vård- och apotekspersonal samt Privatperson
Ny information och länk till instruktionsmaterial för SAML-biljett
3.1 Uppdaterat beskrivning av refresh_token i tabell under intygsväxling samt förtydligat beskrivning av assertion
3.2 Förtydligat krav kring efterföljande anrop med access token samt ny information och länk till Anropsflöde för OAuth2 
3.3 Uppdaterat informationom vilka roller eHm stödjer och kan växla SAML-intyg till access token samt information kring giltighetstid
3.4 Ny information om giltighetstid för dosaktör
​7.0 ​2019-03-08 ​Uppdaterat sidan med att även Inera är en godkänd federation
Kap.2 Lagt till länk Anropsexempel Saml-intyg i tabell för vård- och apotekspersonal
​8.0 ​ ​3.4 Uppdaterat tjänster med utökad giltighetstid 
​9.0 ​2019-03-19 ​3 Uppdaterat namn för Inera-alternativet
​10.0 ​2019-07-09 ​3.4 Uppdaterat tjänster med utökad giltighetstid
11.0​ ​2019-12-03 ​​Kapitel 2 Reviderat information i matris för Vård- och apotekspersonal i SOAP-meddelandet om operatörer till att gälla fler än Sambi och Inera. 
Redaktionella ändringar, ny stavning E-hälsomyndigheten
12.0 ​​ ​
​13.0 ​2020-07-01 Kap 2. Omformulerat kring anslutning av godkända operatörer, tagit bort text och länk om federation​
2.1.1 Tagit bort releaseinformation och datumx
​14.0 ​2020-10-16 ​Lagt till stycket "Observera att"
​15.0 ​ ​3.4 Uppdaterat med tre tjänster med utökad giltighetstid
16.0​ ​2021-01-25 ​Uppdaterat md avseede på införandet av Sweden Connect