Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Navitabs
rootViderestillingsservice (DCC) - Leverancebeskrivelse
firsttabViderestillingsservice (DCC)
includeroottrue


Anchor
_Toc83370011
_Toc83370011

SOSI-DCC anvenderguide

Indledning
Målgruppe
Webservice snitfladen
Processering af indkommende kald
Fejlsituationer
Referencer

Anchor
_Toc343345287
_Toc343345287
Indledning

Nærværende dokument udgør anvenderguiden for SOSI-DCC komponenten, også kendt som SOSI Afkoblingskomponenten. SOSI-DCC fungerer som webservice gateway og dens hovedfunktioner er routing af requests og håndhævelse af timeout-grænser på webservice kald. Timeout-grænser er på operationsniveau konfigureret i komponenten, men kan overrides af klienter til afkoblingskomponenten som en del af web service kaldet. 

Som webservice gateway er komponenten placeret mellem en klient – som kaldes en webservice consumer (WSC) – og en service udbyder, kaldet en webservice provider (WSP). 
Som illustreret på nedenstående figur sender WSCen webservice requests til WSPen igennem SOSI-DCC og modtager responsen direkte ved synkron kommunikation. 

Image Added
SOSI-DCC understøtter [SOAP 1.1] kald (og dermed også Den Gode Webservice [DGWS]) samt [MTOM], men ikke [SOAP 1.2]. 
Afhængig af konfiguration af komponenten gør SOSI-DCC brug af [WS-addressing]. 


Anchor
_Toc343345288
_Toc343345288
Målgruppe

Denne anvenderguide henvender sig til arkitekter og udviklere, der skal kalde webservices i gennem SOSI-DCC.

Anchor
_Toc343345289
_Toc343345289
Snitfladebeskrivelse

SOSI-DCC har én proxy webservice snitflade, som router kald på baggrund af den operation der kaldes – angivet som 'SOAPAction' HTTP header, og evt. ServiceIdentifier angivet i url'en. En angivelse af 'SOAPAction' HTTP headeren er påkrævet for HTTP bundne SOAP kald. For hver operation, der skal kunne kaldes i gennem DCC, er komponenten konfigureret med et WSP endpoint, en timeout-grænse og en eventuel proxy endpoint som kaldet skal routes i gennem (fx en SOSI-Gateway).

Klienter kan override den i DCC konfigurerede timeoutgrænse ved at tilføje følgende SOAP header i DCC namespacet (http://www.sosi.dk/2007/07/decoupling-component-1.0.xsd) til kaldet, hvor det ønskede timeout angives i millisekunder (her 500 ms):

Code Block
<dcc:DecouplingHeader xmlns:dcc="http://www.sosi.dk/2007/07/decoupling-component-1.0.xsd"> 
   <dcc:DecouplingModel>synchronous_timeout</dcc:DecouplingModel> 
   <dcc:Timeout>500</dcc:Timeout> 
</dcc:DecouplingHeader>


SOSI-DCC fjerner denne DecouplingHeader i kald der viderestilles. Komponenten konfigureres – igen på operationsniveau – til enten at ignorere eller videreføre _URL path_ _suffikset_ i kaldet, hvor der med _URL path_ _suffiks_ menes den del af endpoint URLen efter SOSI-DCCens endpoint URL (typisk noget i stil med http\[s\]://<host>:<port>/decoupling/).

Fx udgør someService/someID URL path suffikset i følgende URL (her fra det ene eksterne NSP testmiljø som eksempel):

http://test2.ekstern-test.nspop.dk:8080/decoupling/someService/someID

Anchor
_Toc343345293
_Toc343345293
Eksempel på kald af DCC

Det følgende eksempel viser hvordan man kalder servicen NTS gennem DCC'en.


Konfiguration

Kaldet af NTS skal først konfigureres i DCC'en. Det gør ved at tilføje følgende i dcc-config.xml:

Code Block
<Endpoint
        ActionPrefix="http://nspop.dk/nts/2013/05#"
        URL="http://test1.ekstern-test.nspop.dk:8080/nts/service"
        ProxyURL=""
        WSA_Headers_Processing="WSA_PASSTHROUGH">
    <Action Name="invoke" ServiceIdentifier="nts-1">
        <DecouplingModel>synchronous_timeout</DecouplingModel>
        <Timeout>30000</Timeout>
    </Action>
</Endpoint>

I dette eksempel vil man kalde NTS servicen på test1 med operationen "invoke". Timeout er sat til 30000 millisekunder.

Attributten ServiceIdentifier bruges, hvis man ønsker at udstille den samme SOAP-action flere gange gennem DCC'en. Attributten er ikke påkrævet.

Parameteren "WSA_Headers_Processing" bruges til at styre WS-addressing. Dette er beskrevet mere detaljeret i Installationsvejledningen. Bemærk at deafult-værdien er WSA_OVERWRITE, så der tilføjes to WS-addressing headere til requestet.


Security

For at kalde NTS skal man som anvendersystem skaffe sig et ID-kort udstedt af STS og indsætte dette i Security-delen af headeren. 


Data

Body-delen i kaldet til NTS behøver ikke indeholde andet end et <non-empty/> element, så det samlede request til NTS ser sådan ud:

Code Block
titleNTS Request
collapsetrue
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
      <wsu:Timestamp xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
        <wsu:Created>2021-01-28T20:17:50Z</wsu:Created>
      </wsu:Timestamp>
      <saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" IssueInstant="2021-01-28T20:12:26Z" Version="2.0" id="IDCard">
        <saml:Issuer>TEST2-NSP-STS</saml:Issuer>
        <saml:Subject>
          <saml:NameID Format="medcom:other">SubjectDN={SERIALNUMBER=CVR:46837428-UID:27910135 + CN=Statens Serum Institut - Test VOCES, O=Statens Serum Institut // CVR:46837428, C=DK},IssuerDN={CN=TRUST2408 Systemtest XXII CA, O=TRUST2408, C=DK},CertSerial={1495058165}</saml:NameID>
          <saml:SubjectConfirmation>
            <saml:ConfirmationMethod>urn:oasis:names:tc:SAML:2.0:cm:holder-of-key</saml:ConfirmationMethod>
            <saml:SubjectConfirmationData>
              <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
                <ds:KeyName>OCESSignature</ds:KeyName>
              </ds:KeyInfo>
            </saml:SubjectConfirmationData>
          </saml:SubjectConfirmation>
        </saml:Subject>
        <saml:Conditions NotBefore="2021-01-28T20:12:26Z" NotOnOrAfter="2021-01-29T20:12:26Z"/>
        <saml:AttributeStatement id="IDCardData">
          <saml:Attribute Name="sosi:IDCardID">
            <saml:AttributeValue>yv/D/gLWSK0BUxPbC++UbQ==</saml:AttributeValue>
          </saml:Attribute>
          <saml:Attribute Name="sosi:IDCardVersion">
            <saml:AttributeValue>1.0.1</saml:AttributeValue>
          </saml:Attribute>
          <saml:Attribute Name="sosi:IDCardType">
            <saml:AttributeValue>system</saml:AttributeValue>
          </saml:Attribute>
          <saml:Attribute Name="sosi:AuthenticationLevel">
            <saml:AttributeValue>3</saml:AttributeValue>
          </saml:Attribute>
          <saml:Attribute Name="sosi:OCESCertHash">
            <saml:AttributeValue>xe/OtYMBaE1RFJ7l9lN2zAuiXAU=</saml:AttributeValue>
          </saml:Attribute>
        </saml:AttributeStatement>
        <saml:AttributeStatement id="SystemLog">
          <saml:Attribute Name="medcom:ITSystemName">
            <saml:AttributeValue>Test</saml:AttributeValue>
          </saml:Attribute>
          <saml:Attribute Name="medcom:CareProviderID" NameFormat="medcom:cvrnumber">
            <saml:AttributeValue>46837428</saml:AttributeValue>
          </saml:Attribute>
          <saml:Attribute Name="medcom:CareProviderName">
            <saml:AttributeValue>Statens Serum Institut</saml:AttributeValue>
          </saml:Attribute>
        </saml:AttributeStatement>
        <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#" id="OCESSignature">
          <ds:SignedInfo>
            <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
            <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
            <ds:Reference URI="#IDCard">
              <ds:Transforms>
                <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
                <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
              </ds:Transforms>
              <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
              <ds:DigestValue>8V023TkgYn4/VSJ1NyOe2iIUvVs=</ds:DigestValue>
            </ds:Reference>
          </ds:SignedInfo>
          <ds:SignatureValue>JAokRnZ9MB1DFlggkQJpoeuhIFfGqCtDvdN1d+chtl1eloJVx+TFesEhVXE7aWzJciTc+g5TzEfWw3LyqV978Ij6z9+xjo5Cqlb2pAHJNq83dnFJPgNxAC6l0L0jXVIX6Lm2JiIn892OHEF+6LcLZ1XQxo2g9l3q1Qg9j0NMWr3DQtjSjX18N1SM4IuZADHLGnjAMuWFw8xA+A3Urb2yx1vL8G4jZRzv3c2Y7dttNST/uQcHy/e7Lm2dnsacIwFiFpSWcMZydFn2pMzQ1CrJCC0716HvAbUh5+xRzPr9XvqE0SwlLQcItAEwbPqvmejNL87kEBdPOmK+s4gQ7y75SA==</ds:SignatureValue>
          <ds:KeyInfo>
            <ds:X509Data>
              <ds:X509Certificate>MIIGKjCCBRKgAwIBAgIEW6uMBTANBgkqhkiG9w0BAQsFADBIMQswCQYDVQQGEwJESzESMBAGA1UECgwJVFJVU1QyNDA4MSUwIwYDVQQDDBxUUlVTVDI0MDggU3lzdGVtdGVzdCBYWElJIENBMB4XDTE5MDQzMDA5MDcxN1oXDTIyMDQzMDA5MDYzOFowgZQxCzAJBgNVBAYTAkRLMS4wLAYDVQQKDCVTdW5kaGVkc2RhdGFzdHlyZWxzZW4gLy8gQ1ZSOjMzMjU3ODcyMVUwIAYDVQQFExlDVlI6MzMyNTc4NzItRklEOjE4OTExODYxMDEGA1UEAwwqU09TSSBUZXN0IEZlZGVyYXRpb24gKGZ1bmt0aW9uc2NlcnRpZmlrYXQpMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAyo57h9E/hM5gimxaDgHB0MLcgVfXGJbQh/8OC1vTdDsCUIzIwRd5lJE+ado8urHF7UmKubFZzfCPduoRv9b3TkNVKaixiHUMtP4egbL8vcgyalk28cNQdUk8f34mg8atgvd45EnIKz2iB+yjs5guJPDBg2OFSbP0r53NU8fVTq3aLtDpDVnkxsyjNQ7HOFtzavyMnKx0vDgafEvrUR3WTSLCGju4aUIg3ThgrWXA7i3lPIAXdV8mQmlY3wn/kIBiyIotmF98UsEket/sxpJNkJ6R6AUpxnGApCDP1Fw2BgxAQWWrtD/c5IoIZwGWNfLgpJEzfhnuIZJ7Bfs9RmHFdQIDAQABo4ICzTCCAskwDgYDVR0PAQH/BAQDAgO4MIGXBggrBgEFBQcBAQSBijCBhzA8BggrBgEFBQcwAYYwaHR0cDovL29jc3Auc3lzdGVtdGVzdDIyLnRydXN0MjQwOC5jb20vcmVzcG9uZGVyMEcGCCsGAQUFBzAChjtodHRwOi8vZi5haWEuc3lzdGVtdGVzdDIyLnRydXN0MjQwOC5jb20vc3lzdGVtdGVzdDIyLWNhLmNlcjCCASAGA1UdIASCARcwggETMIIBDwYNKwYBBAGB9FECBAYEAjCB/TAvBggrBgEFBQcCARYjaHR0cDovL3d3dy50cnVzdDI0MDguY29tL3JlcG9zaXRvcnkwgckGCCsGAQUFBwICMIG8MAwWBURhbklEMAMCAQEagatEYW5JRCB0ZXN0IGNlcnRpZmlrYXRlciBmcmEgZGVubmUgQ0EgdWRzdGVkZXMgdW5kZXIgT0lEIDEuMy42LjEuNC4xLjMxMzEzLjIuNC42LjQuMi4gRGFuSUQgdGVzdCBjZXJ0aWZpY2F0ZXMgZnJvbSB0aGlzIENBIGFyZSBpc3N1ZWQgdW5kZXIgT0lEIDEuMy42LjEuNC4xLjMxMzEzLjIuNC42LjQuMi4wga0GA1UdHwSBpTCBojA9oDugOYY3aHR0cDovL2NybC5zeXN0ZW10ZXN0MjIudHJ1c3QyNDA4LmNvbS9zeXN0ZW10ZXN0MjIxLmNybDBhoF+gXaRbMFkxCzAJBgNVBAYTAkRLMRIwEAYDVQQKDAlUUlVTVDI0MDgxJTAjBgNVBAMMHFRSVVNUMjQwOCBTeXN0ZW10ZXN0IFhYSUkgQ0ExDzANBgNVBAMMBkNSTDE0MjAfBgNVHSMEGDAWgBSrqAFEGbCzQ5na+nzM0gAYA+c8vzAdBgNVHQ4EFgQUGYAVKKL17LHyVGSErL26MBNadTQwCQYDVR0TBAIwADANBgkqhkiG9w0BAQsFAAOCAQEAjHMO4sWEf8M25WHczBTJYtMitn1wLOqE6raeM6oYyw6R/4FImpOzF6bxBlfNnhhR0vJSXMWTqL/onCyy4gCs9eLglRHZ9BC8a9fmirrguNpOWlR8NAf5GRwOqCyTnkTAfUD1fp0RzVo8TvAd73WiGeUTzTiAVf7OgZFnRIYkcALXLjNs6AwELWSh+bC/gGuQcHUDd8YGSzgKS6w2qz3fIASrykxzlYjeusks58CereC6WfvN0I+GGlL9fIgjpzh7JEELME7r9QJLL9NSrmlRKfhM8gzuE6Vm4vGzmSsnNJxGMf1vTzEve4lXI8pnOtHMTtNl5zw4jCJFakRqcWm3FQ==</ds:X509Certificate>
            </ds:X509Data>
          </ds:KeyInfo>
        </ds:Signature>
      </saml:Assertion>
    </wsse:Security>
    <medcom:Header xmlns:medcom="http://www.medcom.dk/dgws/2006/04/dgws-1.0.xsd">
      <medcom:SecurityLevel>3</medcom:SecurityLevel>
      <medcom:Linking>
        <medcom:MessageID>AAABd0qlHSiyOXA2Yws0BFNPU0k=</medcom:MessageID>
      </medcom:Linking>
      <medcom:RequireNonRepudiationReceipt>no</medcom:RequireNonRepudiationReceipt>
    </medcom:Header>
  </soap:Header>
  <soap:Body>
    <non-empty/>
  </soap:Body>
</soap:Envelope>

Bemærk at alt mellem <soap:Header>...</soap:Header> skal udskiftes med et nyt ID-kort man har trukket fra servicen STS.

Dette gemmes i en fil med navnet: nts-request.xml


Request

Start med at kalde NTS direkte uden om DCC'en:

curl --data "@nts-request.xml" -H "Content-Type: application/soap+xml; charset=utf-8" -H "SOAPAction:http://nspop.dk/nts/2013/05#invoke" http://test1.ekstern-test.nspop.dk:8080/nts/service

Verificer at svaret er følgende:

Code Block
titleNTS Response
collapsetrue
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header>
    <Header xmlns="http://www.medcom.dk/dgws/2006/04/dgws-1.0.xsd">
      <Linking>
        <FlowID>EF93</FlowID>
        <MessageID>EF93:4492222951517333</MessageID>
        <InResponseToMessageID>AAABd0qlHSiyOXA2Yws0BFNPU0k=</InResponseToMessageID>
      </Linking>
      <FlowStatus>flow_finalized_succesfully</FlowStatus>
    </Header>
    <NTS xmlns="http://nspop.dk/nts/2013/05">
      <Environment>TEST</Environment>
      <NTS-Version>1.0.2</NTS-Version>
      <SEAL-Version>2.1.6</SEAL-Version>
    </NTS>
  </SOAP-ENV:Header>
  <SOAP-ENV:Body>
    <OK />
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>


Ændrer nu kaldet ved at tilføje URL'en til DCC foran URL'en til NTS. 

curl --data "@nts-request.xml" -H "Content-Type: application/soap+xml; charset=utf-8" -H "SOAPAction:http://nspop.dk/nts/2013/05#invoke" http://localhost:8080/decoupling/

I dette tilfælde er DCC'en startet op lokalt vha. docker-compose setup og DCC'ens URL er "http://localhost:8080/decoupling". Svaret skal være det samme som det direkte kald bortset fra at ID'erne (FlowID, MessageID og InResponseToMessageID) er forskellige for hvert kald til NTS'en.

Angivelse af ServiceIdentifier-parameter

Hvis man ønsker at kalde en operation som er udstillet under en bestemt ServiceIdentifier, angives denne i url'en. Hvis f.eks. ovenstående invoke-operation er udstillet under ServiceIdentifieren 'foo', udføres kaldet således:

curl --data "@nts-request.xml" -H "Content-Type: application/soap+xml; charset=utf-8" -H "SOAPAction:http://nspop.dk/nts/2013/05#invoke" http://localhost:8080/decoupling/service/foo/

Hvis operationen er konfigureret med ServiceIdentifier 'foo', vil DCC'en fjerne '/service/foo'-delen af url'en, og forwarde requestet til NTS.

Anchor
_Toc343345290
_Toc343345290
Processering af indkommende kald

Når en besked modtages fra en WSC til videreforsendelse til en WSP, gennemløbes følgende flow i komponenten:

  1. Whitelistning checkes Der bemærkes, at IP-whitelistning ikke er implementeret på NSP.
  2. Hvis ikke WSCens IP adresse optræder i komponentens whitelist, afbrydes kaldet og et fejlsvar returneres til WSCen.
  3. Routing slås op i komponentens konfiguration: På baggrund af SOAPAction i HTTP headeren, og evt. ServiceIdentifier i url'en, afgøres hvorhen beskeden skal routes. Hvis routingsinformation ikke findes i komponentens konfiguration afbrydes kaldet og der returneres et fejlsvar.
  4. Beskeden parses: Der foretages en SAX parsning af beskeden hvor relevante informationer opsamles og eventuel fjernes/modificeres (DCC og WS-addressing headere).
  5. Afkoblingsmodel identificeres: Hvis ikke WSCen har specificeret en timeoutgrænse i beskeden, benyttes default timeout for den pågældende operation som er angivet i komponentens konfiguration.
  6. Beskeden sendes til WSPen.
  7. WSP svaret streames tilbage til WSC. Ved timeout i WSP kaldet returneres i stedt et fejlsvar.

Der bemærkes, at komponenten ikke er bundet til \[DGWS\] og ikke foretager nogen form for validering af at \[DGWS\] overholdes og dermed heller ikke validerer et eventuel indlejret SOSI Idkort.

Afhængig af hvordan den enkelte operation (SOAPAction) er konfigureret, _erstatter, fjerner_ eller _bevarer_ SOSI-DCC \[WS-addressing\] headere i kaldet der viderestilles.

For oplysninger om den konkrete konfiguration (og dermed semantik) for de enkelte operationer på NSP instanserne henvises til NSP operatøren.

Anchor
_Toc343345291
_Toc343345291
Fejlsituationer

Fejlsvar fra WSPen som kaldet blev viderestillet til returneres af SOSI-DCC i uforandret form.

Ved fejlsituationer der opstår i SOSI-DCC returnerer komponenten et fejlsvar der følger \[DGWS\] formatet for SOAP faults.

Nedenstående tabel lister de mulige fejlkoder og beskriver hvornår typen af fejlen opstår.

Alle fejlkoder som DCC generer er præfikset med dcc_.

FaultCode

Beskrivelse

dcc_timeout

Timeout i kald til WSP.
Opstår når timeout-grænsen for den pågældende operation (som specificeret i konfigurationen eller angivet af klienten i DCC SOAP headeren) overskrides.

dcc_syntax_error

Syntaksfejl i det indkommende kald.
Opstår fx ved en manglende SOAPAction HTTP header, en ugyldig DCC SOAP header, ikke velformet SOAP XML, fejl i MIME boundaries i MTOM beskeder etc.

dcc_access_denied

(Kun hvis DCC er konfigureret med IP whitelistening, hvilket pt. ikke er tilfældet på NSP)
Opstår når klientens IP adresse ikke er whitelistet i DCC.

dcc_general_error

Andre typer fejl som opstår i DCC og som ikke er dækket af ovenstående, fx kald med en operation (SOAPAction) som ikke er konfigureret i komponenten, I/O fejl under videresendelse af kaldet (fx hvis WSPen ikke kan nås) etc.


Et eksempel DCC fejlsvar ser således ud:

Code Block
titleDCC Fejl
collapsetrue
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope id="Envelope">
  <soapenv:Header>
    <wsse:Security>
      <wsu:Timestamp>
        <wsu:Created>2016-12-14T09:22:26Z</wsu:Created>
      </wsu:Timestamp>
    </wsse:Security>
    <medcom:Header>
      <medcom:SecurityLevel>1</medcom:SecurityLevel>
      <medcom:Linking>
        <medcom:FlowID>unknown</medcom:FlowID>
        <medcom:MessageID>AAABWPyj23gwaMH/cmFafFNPU0k=</medcom:MessageID>
        <medcom:InResponseToMessageID>unknown</medcom:InResponseToMessageID>
      </medcom:Linking>
    </medcom:Header>
  </soapenv:Header>
  <soapenv:Body>
    <soapenv:Fault>
      <faultcode>Server</faultcode>
      <detail>
        <medcom:FaultCode>dcc_syntax_error</medcom:FaultCode>
      </detail>
      <faultstring>No SOAPAction specified in http header!</faultstring>
    </soapenv:Fault>
  </soapenv:Body>
</soapenv:Envelope>

Anchor
_Toc343345292
_Toc343345292
Referencer

[DGWS]

Den Gode Webservice, MedCom
]]></ac:plain-text-body></ac:structured-macro>
http://medcom.dk/standarder/webservice-standarder/den-gode-webservice

[MTOM]

SOAP 1.1 Binding for MTOM 1.0, W3C
]]></ac:plain-text-body></ac:structured-macro>
https://www.w3.org/Submission/soap11mtom10/

[SOAP 1.1]

Simple Object Access Protocol (SOAP) 1.1, W3C
]]></ac:plain-text-body></ac:structured-macro>
https://www.w3.org/TR/2000/NOTE-SOAP-20000508/

[SOAP 1.2]

SOAP Version 1.2, W3C
]]></ac:plain-text-body></ac:structured-macro>
https://www.w3.org/TR/soap12/

[WS-addressing]

Web Services Addressing (WS-Addressing)
]]></ac:plain-text-body></ac:structured-macro>
https://www.w3.org/Submission/2004/SUBM-ws-addressing-20040810/ og https://www.w3.org/TR/ws-addr-core/