Utgåvehistorik

1          Översikt

Detta dokument beskriver anvisningar för valfria tillägg till regelverket för RIV Tekniska Anvisningar Basic Profile 2.1. Anvisningarna är generellt sett valfria men kan för vissa typer av komponenter, t ex tjänsteplattformar, vara obligatoriska. Enskilda domäner kan också ta beslut om att göra vissa valfria tillägg obligatoriska inom sin domän, se respektive domäns Tjänstekontraktsbeskrivning.

Dokumentet beskriver följande anvisningar:

• RIV Tekniska Anvisningar – Basic Profile med http header för att ange ursprunglig avsändare 2.1
• RIV Tekniska Anvisningar – Basic Profile med status för anrop till aggregerande tjänster 2.1

1.1          Tillgänglighet

Detta dokument är publicerade under licensen Creative Commons CC-BY-SA (http://creativecommons.org/licenses/by-sa/2.5/se/). Det betyder att du fritt får kopiera, distribuera och skapa bearbetningar av anvisningarna, under förutsättning att upphovsmannen (Sveriges Kommuner och Landsting) anges (men inte på ett sätt som antyder att de godkänt eller rekommenderar din användning av verket).

Denna profil är verifierad genom exempelapplikationer. Källkoden [R11] för dessa distribueras under öppen-källkodslicensen Apache License, Version 2.0 (http://www.apache.org/licenses/LICENSE-2.0)

1.2         Referenser

2         RIV Tekniska Anvisningar – Basic Profile med http header för att ange ursprunglig avsändare 2.1

2.1         Inledning

Denna anvisning är en påbyggnad på Basic Profile 2.1 för att möjliggöra överföring av information om den ursprungliga avsändarens (tjänstekonsuments) identitet. Överföringen skall ske via en http header med namnet ”x-rivta-original-serviceconsumer-hsaid". Anvisningen är obligatorisk för tjänsteplattformar men frivillig för tjänsteproducenter. Anvisningen påverkar inte tjänstekonsumenter.

Anvisningen innehåller endast regeluppsättningen som definierar profilens avvikelser från ”Basic Profile”. För bakgrund, motiv, krav samt de principer som ligger till grund för utvecklingen av profilen hänvisas till Översikt RIV Tekniska Anvisningar 2.1 [R2].

2.1.1         Målgrupp

Denna anvisning riktar sig dels till leverantörer som implementerar tjänsteplattformar enligt T-boken [R1] och till implementationer av tjänsteproducenter som vill veta identiteten på den ursprungliga tjänstekonsumenten i de fall anropet passerat en eller flera tjänsteplattformar på vägen till tjänsteproducenten.

2.1.2        Syfte

Syftet med denna anvisning är att beskriva en utökning av basprofilen som ger möjlighet att föra över information om den ursprungliga avsändarens (tjänstekonsuments) identitet till en tjänsteproducent. En tjänsteproducent kan använda denna information till exempel för loggning eller behörighetsmekanismer.

I de fall tjänstekonsument och tjänsteproducent kommunicerar utan mellanliggande tjänsteplattform behövs inte denna http header då tjänsteproducenten i det fallet kan hämta avsändarens identitet direkt från tjänstekonsumentens klient certifikat, se regel #6 i RIV TA Basic Profile 2.1 [R3]. Detta illustreras av följande bild:

I de fall tjänstekonsument och tjänsteproducent kommunicerar via en eller flera mellanliggande tjänsteplattformar har samtliga tjänsteplattformar till ansvar att sätta denna http header om den inte redan är satt av en tjänsteplattform tidigare i anropskedjan. Är http header redan satt ansvarar respektive tjänsteplattform för att föra http headern vidare i anropet till tjänsteproducenten alternativt till nästa tjänsteplattform.

Följande bild visar hur ursprungsidentiteten förs via den nationella tjänsteplattformen från anropande tjänstekonsuments klient certifikat till tjänsteproducenten via http headern:

Nedan ett mer komplext exempel med tre tjänsteplattformar inblandade i anropet, dels en applikationslokal tjänsteplattform (också känd som Applikation Service Bus, ASB), dels en regional samt den nationella tjänsteplattformen. I detta exempel så är det den applikationslokala tjänsteplattformen som fångar upp identiteten från tjänstekonsumentens klient certifikat och sätter det i http headern. Den regionala och den nationella tjänsteplattormen för bara vidare inkommande http header till sitt utgående anrop:

Till sist ett exempel där vi vänder på anropskedjan för att visa hur det ser ut med en tjänsteproducent som sitter bakom en applikationslokal tjänsteplattform som i sin tur anropas av en regional tjänsteplattform. Tjänstekonsumenten i detta exempel anropar den nationella tjänsteplattformen som i sin tur anropar den regionala. Det blir nu den nationella tjänste-plattformen som fångar upp identiteten från tjänstekonsumentens klient certifikat och sätter det i http headern. Den regionala och den applikationslokala tjänsteplattormen för bara vidare inkommande http header till sitt utgående anrop:

2.2        Beskrivning av namnregler

Denna profils namn är ”RIV Tekniska Anvisningar – Basic Profile med http header för att ange ursprunglig avsändare 2.1” och refereras ${profil}

Denna profils kortnamn är ”rivtabpos21” och refereras ${profilKortnamn}

2.3        Följsamhet mot externa regelverk

Här definieras de externa regelverk (t.ex. profiler) som utgör regelbas för denna profil. Det är en målsättning att denna profil ska kunna läsas uppifrån och ner utan detaljerad kunskap om externa regelverk. För regler som inte lyfts fram i denna profil (av förbiseende eller för att de inte bedömts viktiga) hänvisas till de externa regelverk som redovisas här.

Regel #1, Följsamhet mot RIV TA BP 2.1

Utformning av WSDL skall följa RIV TA BP 2.1, med tillägg av de regler som definieras i denna profil.

Motiv: Interoperabilitet

2.4        Detaljerade regler

Regel #2: Propagering av ursprunglig sändares identitet i http header

En tjänsteplattform skall propagera ursprunglig avsändares identitet i http headern ”x-rivta-original-serviceconsumer-hsaid”. Det innebär att:

1. Om http headern inte är satt i ett inkommande anrop så skall avsändaren betraktas som ursprunglig avsändare och dess identitet (HSA-ID) skall hämtas från inkommande klient certifikat och sättas i http headern i utgående anrop till tjänsteproducenten alternativt till nästa tjänsteplattform.
2. Om http headern är satt i ett inkommande anrop så skall tjänsteplattformen föra vidare http headern i anropet till tjänsteproducenten alternativt till nästa tjänsteplattform.

Motiv: Detta ger möjlighet att föra vidare information om ursprunglig avsändares identitet även om anropet passerar en eller flera mellan liggande tjänsteplattformar.

Regel #3: Mottagande av ursprunglig sändares identitet i http header

En tjänsteproducent kan utnyttja http headern ”x-rivta-original-serviceconsumer-hsaid” för att få redan på identiteten av den ursprungliga avsändaren om anropet kommer från en eller flera mellanliggande tjänsteplattformar.

Motiv: Detta ger en valfri möjlighet för tjänsteproducenter att identifiera den ursprungliga avsändaren.

Regel #4: Säkerställ att anropande tjänsteplattform är känd

För att säkerställa en pålitlig propagering av ursprunglig avsändares identitet skall en tjänsteplattform säkerställa att den endast för vidare ursprunglig avsändares identitet från andra tjänsteplattformar som den litar på, t ex genom att upprätthålla en lista på IP adresser eller HSA-ID för de tjänsteplattformar den litar på och som den kontrollerar mot innan den accepterar en inkommande http header för ursprunglig avsändare. För anrop där denna kontroll misslyckas skall ett felmeddelanden skickas tillbaka till avsändaren och felet skall loggas som ett potentiellt försök till intrång.

Motiv: Om inte denna kontroll utförs så riskerar en tjänsteplattform att bli utsatt för angrepp från av avsändare som skickar med en annan tjänstekonsuments identitet (HSA-ID) i http headern och därmed otillåtet kan uppträda med dess identitet.

3         RIV Tekniska Anvisningar – Basic Profile med status för anrop till aggregerande tjänster 2.1

3.1         Inledning

Denna anvisning är en påbyggnad på Basic Profile 2.1 för att möjliggöra rapportering av teknisk information om bearbetningen i en aggregerande tjänst. Informationen skickas tillbaka till anropande tjänstekonsument i SOAP svaret som en SOAP header med namnet "ProcessingStatus".

3.1.1         Målgrupp

Denna anvisning riktar sig till dem som ska implementera aggregerande tjänster samt till tjänstekonsumenter som är intresserade av att ta del av teknisk information om bearbetningen i en aggregerande tjänst.

Notera att utformning av WSDL för en nationell tjänsteinteraktion i enlighet med RIV TA inte påverkas av denna anvisning, för detaljer se nedan.

3.1.2        Syfte

Syftet med denna anvisning är att beskriva en utökning av basprofilen som ger möjlighet att rapportera teknisk information om bearbetningen i en aggregerande tjänst. Informationen skickas tillbaka till anropande tjänstekonsument i SOAP svaret som en SOAP header med namnet "ProcessingStatus".

SOAP headern innehåller en lista med en rad per anropat källsystem och ger per källsystem information huruvida anropet gick bra, om svaret kom direkt från cache eller om det hämtades från källsystemet, hur gammal den cachade informationen är. För detaljer se schemafilen interoperability_headers_1.0 i psuedodomänen interoperability:headers i källkodsträdet på http://rivta.se. 

Följande dokumentation är hämtad från XML Schemat ovan:

SOAP headern beskrivs inte i de tjänsteinteraktioner (WSDL-filer) som en aggregerande tjänst följer, detta för att kunna använda samma tjänsteinteraktioner som de underliggande tjänsteproducenterna använder.

Nedan ett exempel där en tjänstekonsument anropar en aggregerande tjänst som via engagemangsindex får reda på att det finns information att hämta i två olika källsystem. Den aggregerande tjänsten anropar de två källsystemen (parallellt) och sätter samman ett aggregerat svar till tjänstekonsumenten där SOAP header ”ProcessingStatus” ingår. Detta illustreras av följande bild:

Givet att båda källsystemen svarar korrekt så kommer ProcessingStatus – SOAP headern se ut något i stil med följande:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Header>
      <ProcessingStatus xmlns="urn:riv:interoperability:headers:1">
         <ProcessingStatusList>
            <logicalAddress>HSA-ID-A</logicalAddress>
            <statusCode>DataFromSource</statusCode>
            <isResponseFromCache>false</isResponseFromCache>
            <isResponseInSynch>true</isResponseInSynch>
            <lastSuccessfulSynch>20130904124333</lastSuccessfulSynch>
         </ProcessingStatusList>
         <ProcessingStatusList>
            <logicalAddress>HSA-ID-B</logicalAddress>
            <statusCode>DataFromSource</statusCode>
            <isResponseFromCache>false</isResponseFromCache>
            <isResponseInSynch>true</isResponseInSynch>
            <lastSuccessfulSynch>20130904124333</lastSuccessfulSynch>
         </ProcessingStatusList>
      </ProcessingStatus>
   </soapenv:Header>

Om däremot något av de anropade källsystemen inte svarar inom en föreskriven tid eller returnerar ett fel så kommer ProcessingStatus-SOAP headern innehålla information om att svaret inte är komplett utan bara partiellt samt information om vilket fel som uppstod. I bilden nedan illustreras ett exempel där tre källsystem anropas men bara två ger svar, det tredje orsakar en timeout (dvs svarar inte inom föreskriven maxtid):

SOAP-headern ProcessingStatus kommer då se ut något i stil med följande:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Header>
    <ProcessingStatus xmlns="urn:riv:interoperability:headers:1">
      <ProcessingStatusList>
        <logicalAddress>HSA-ID-A</logicalAddress>
        <statusCode>DataFromSource</statusCode>
        <isResponseFromCache>false</isResponseFromCache>
        <isResponseInSynch>true</isResponseInSynch>
        <lastSuccessfulSynch>20130905111504</lastSuccessfulSynch>
      </ProcessingStatusList>
      <ProcessingStatusList>
        <logicalAddress>HSA-ID-B</logicalAddress>
        <statusCode>DataFromSource</statusCode>
        <isResponseFromCache>false</isResponseFromCache>
        <isResponseInSynch>true</isResponseInSynch>
        <lastSuccessfulSynch>20130905111504</lastSuccessfulSynch>
      </ProcessingStatusList>
      <ProcessingStatusList>
        <logicalAddress>HSA-ID-C</logicalAddress>
        <statusCode>NoDataSynchFailed</statusCode>
        <isResponseFromCache>false</isResponseFromCache>
        <isResponseInSynch>false</isResponseInSynch>
        <lastUnsuccessfulSynch>20130905111504</lastUnsuccessfulSynch>
        <lastUnsuccessfulSynchError>
          <causingAgent>virtualization_platform</causingAgent>
          <code>43000</code>
          <text>Read timed out. Failed to route event via endpoint:
            org.mule.module.cxf.CxfOutboundMessageProcessor. Message payload is
            of type: PostMethod, Read timed out</text>
        </lastUnsuccessfulSynchError>
      </ProcessingStatusList>
    </ProcessingStatus>
  </soapenv:Header>

3.2        Beskrivning av namnregler

Denna profils namn är ”RIV Tekniska Anvisningar – Basic Profile med status för anrop till aggregerande tjänster 2.1” och refereras ${profil}

Denna profils kortnamn är ”rivtabpagg21” och refereras ${profilKortnamn}

3.3        Följsamhet mot externa regelverk

Här definieras de externa regelverk (t.ex. profiler) som utgör regelbas för denna profil. Det är en målsättning att denna profil ska kunna läsas uppifrån och ner utan detaljerad kunskap om externa regelverk. För regler som inte lyfts fram i denna profil (av förbiseende eller för att de inte bedömts viktiga) hänvisas till de externa regelverk som redovisas här.

Regel #1, Följsamhet mot RIV TA BP 2.1

Utformning av WSDL skall följa RIV TA BP 2.1, med tillägg av de regler som definieras i denna profil.

Motiv: Interoperabilitet

3.4        Detaljerade regler

Regel #2: Aggregerande tjänster skall returnera status om bearbetning av ett anrop

Implementationer av aggregerande tjänster skall returnera en SOAP header med namnet "ProcessingStatus". Headern skall rapportera teknisk information om bearbetningen i tjänsten. Headern skall följa elementet ProcessingStatus i XML Schemat: interoperability_headers_1.0.xsd.

Motiv: Ge tjänstekonsumenter möjligheten att verifiera att de fått ett komplett svar från den aggregerande tjänsten och om så inte är fallet kunna rapportera tillbaka till användaren att svaret bara är partiellt.

Exempel: Se ovan i kapitlet Syfte.

Regel #3: Tjänstekonsumenter av en aggregerande tjänster kan ta del av status om bearbetning av ett anrop

Tjänstekonsumenter av en aggregerande tjänster kan ta del av status om bearbetning av ett anrop till en aggregerande tjänst genom att ta del av innehållet i SOAP headern med namnet "ProcessingStatus" i svaret från den aggregerande tjänsten. Headern rapporterar teknisk information om bearbetningen i tjänsten. Headern följer elementet ProcessingStatus i XML Schemat: interoperability_headers_1.0.xsd.

Motiv: Ge tjänstekonsumenter möjligheten att verifiera att de fått ett komplett svar från den aggregerande tjänsten och om så inte är fallet kunna rapportera tillbaka till användaren att svaret bara är partiellt.

Exempel: Se ovan i kapitlet Syfte.

Regel #4: Aggregerande tjänster skall återanvända befintlig tjänsteinteraktion (WSDL-fil)

Aggregerande tjänster skall återanvända befintlig tjänsteinteraktion (WSDL-fil), dvs. använda samma tjänsteinteraktioner som de underliggande tjänsteproducenterna använder. Det medför att SOAP headern "ProcessingStatus" inte beskrivs explicit i de enskilda WSDL-filerna utan definieras istället i denna anvisning.

Motiv: SOAP headern beskrivs inte i de tjänsteinteraktioner (WSDL-filer) som en aggregerande tjänst följer, detta för att enkelt kunna återanvända samma tjänsteinteraktioner som de underliggande tjänsteproducenterna använder. Minskar kostnader och risk för fel i samband med vidareutveckling och förvaltning av tjänsteinteraktioner.