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 | ||||
---|---|---|---|---|
|
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 | ||||
---|---|---|---|---|
|
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 | ||||
---|---|---|---|---|
| ||||
<?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/
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 | ||||
---|---|---|---|---|
|
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, 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.
- 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.
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 | ||||
---|---|---|---|---|
|
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:
Code Block | ||||
---|---|---|---|---|
| ||||
<?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 | ||||
---|---|---|---|---|
|
[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) |