SOSI-DCC anvenderguide
Indledning
Målgruppe
Webservice snitfladen
Processering af indkommende kald
Fejlsituationer
Referencer
SOSI-DCC anvenderguide
Indledning
Målgruppe
Webservice snitfladen
Processering af indkommende kald
Fejlsituationer
Referencer
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.
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].
Denne anvenderguide henvender sig til arkitekter og udviklere, der skal kalde webservices i gennem SOSI-DCC.
SOSI-DCC har én proxy webservice snitflade, som router kald på baggrund af den operation der kaldes – angivet som 'SOAPAction' HTTP header 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):
<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
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:
<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">
<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.
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:
<?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>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</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:
<?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/http://test1.ekstern-test.nspop.dk:8080/nts/service
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.
Når en besked modtages fra en WSC til videreforsendelse til en WSP, gennemløbes følgende flow i komponenten:
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.
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. |
dcc_syntax_error | Syntaksfejl i det indkommende kald. |
dcc_access_denied | (Kun hvis DCC er konfigureret med IP whitelistening, hvilket pt. ikke er tilfældet på NSP) |
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:
<?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> |
[DGWS] | Den Gode Webservice, MedCom |
[MTOM] | SOAP 1.1 Binding for MTOM 1.0, W3C |
[SOAP 1.1] | Simple Object Access Protocol (SOAP) 1.1, W3C |
[SOAP 1.2] | SOAP Version 1.2, W3C |
[WS-addressing] | Web Services Addressing (WS-Addressing) |