Page History
Navitabs | ||||||
---|---|---|---|---|---|---|
| ||||||
Anchor | ||||
---|---|---|---|---|
|
SOSI-DCC anvenderguide
Indledning
Målgruppe
Webservice snitfladen
Processering af indkommende kald
Fejlsituationer
Referencer
Anchor | ||||
---|---|---|---|---|
|
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].
Anchor | ||||
---|---|---|---|---|
|
Denne anvenderguide henvender sig til arkitekter og udviklere, der skal kalde webservices i gennem SOSI-DCC.
Anchor | ||||
---|---|---|---|---|
|
Code Block |
---|
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 \\ |
Wiki Markup |
---|
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 \\ |
Anchor | ||||
---|---|---|---|---|
|
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:
Divbox |
---|
<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:
Code Block | ||||
---|---|---|---|---|
| ||||
<?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:
Code Block | ||||
---|---|---|---|---|
| ||||
<?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.
Anchor | ||||
---|---|---|---|---|
|
Når en besked modtages fra en WSC til videreforsendelse til en WSP, gennemløbes følgende flow i komponenten:
- Whitelistning checkes Der bemærkes, at IP-whitelistning ikke er implementeret på NSP.: Hvis ikke WSCens IP adresse optræder i komponentens whitelist, afbrydes kaldet og et fejlsvar returneres til WSCen.
- Routing slås op i komponentens konfiguration: På baggrund af SOAPAction i HTTP headeren afgøres hvorhen beskeden skal routes. Hvis routingsinformation ikke findes i komponentens konfiguration afbrydes kaldet og der returneres et fejlsvar.
- Beskeden parses: Der foretages en SAX parsning af beskeden hvor relevante informationer opsamles og eventuel fjernes/modificeres (DCC og WS-addressing headere).
- 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.
- Beskeden sendes til WSPen.
- WSP svaret streames tilbage til WSC. Ved timeout i WSP kaldet returneres i stedt et fejlsvar.
Wiki Markup |
---|
\\ 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 | ||||
---|---|---|---|---|
|
Wiki Markup |
---|
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:
<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 | ||||
---|---|---|---|---|
|
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="9da33e42-875e-445e-9f7d-c57f9f21fa3f"><ac:plain-text-body><![CDATA[ | [DGWS] | Den Gode Webservice, MedCom |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="434558f0-736f-4461-ab7c-d83dfeb51c3f"><ac:plain-text-body><![CDATA[ | [MTOM] | SOAP 1.1 Binding for MTOM 1.0, W3C |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="7469023d-b8f5-4a1e-b559-b22221aa3f75"><ac:plain-text-body><![CDATA[ | [SOAP 1.1] | Simple Object Access Protocol (SOAP) 1.1, W3C |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="14bc1928-d157-46d1-8acc-1f30a7294692"><ac:plain-text-body><![CDATA[ | [SOAP 1.2] | SOAP Version 1.2, W3C |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="7516da9b-9f17-4c7c-8c9a-0cbb84d23300"><ac:plain-text-body><![CDATA[ | [WS-addressing] | Web Services Addressing (WS-Addressing) |