Technische FAQ koppelvlak WUS 2.0 voor bedrijven

Transcriptie

1 Technische FAQ koppelvlak WUS 2.0 voor bedrijven Versie 1.0 Datum 25 juli 2012 Status Definitief

2 Colofon Projectnaam Versienummer Contactpersoon Organisatie Logius Postbus JE Den Haag Bijlage(n) Documentbeheer Datum Versie Auteur Opmerkingen 25 juli Bas Avis Pagina 2 van 14

3 Inhoud Colofon... 2 Inhoud... 3 Inleiding Waar moet ik rekening mee houden bij het gebruik van.net? Issues met security elementen uit de WSDL Niet automatische ondertekening Headersissues in reponsberichten Toelichting issue De oplossing Waar moet ik rekening mee houden bij het gebruik van PHP? SOAP Method wordt niet geïnitieerd Afleverrespons en SOAP server Omgaan met namespaces Wat kan mijn hash value problemen veroorzaken? Is het Wsa:To verplicht in het afleverresponsbericht? Waar vind ik de eisen die aan de berichtinhoud en de signering worden gesteld? Welke verschillen in headers zijn er? Zijn er voorbeeldberichten beschikbaar van de transportberichten? Wat betekent de foutmelding SOAP header Security was not understood? Moet ik zelf een waarde meegeven aan het element kenmerk (Aanlever-service)? Pagina 3 van 14

4 Inleiding Bedrijven die aansluiten op e-factureren of DigiInkoop implementeren het koppelvlak WUS 2.0 voor bedrijven. In dit document staan de meest veel voorkomende technische vragen met betrekking op de implementatie van het koppelvlak. Pagina 4 van 14

5 1 Waar moet ik rekening mee houden bij het gebruik van.net? 1.1 Issues met security elementen uit de WSDL Digipoort 1.1 Microsoft-ontwikkeltools voor.net hebben moeite met de SecurityPolicyelementen die in de WSDL zijn opgenomen. De WSDL s zijn weliswaar opgesteld volgens de bijbehorende WS-*-specificaties, maar in praktijk worden die specs niet altijd volledig door bestaande tools ondersteund. In de praktijk zie je vaak errormeldingen als An unsupported security policy assertion was detected. In dit geval betekent het dat een deel van de informatie uit de WSDL gehaald moet worden, opdat de WSDL wel in de tool kan worden geïmporteerd, en dat de SecurityPolicies vervolgens met de hand verder moeten worden geconfigureerd/geprogrammeerd. 1.2 Niet automatische ondertekening Digipoort 1.1:.NET 4.0, Visual Studio 2010 en WPF service references. Aanmaken van een service reference kan door de WSDL lokaal op een webserver te plaatsen en dan daarnaar te verwijzen vanuit VS2010 bij add Service Reference. Het is van belang om in de gegenereerde reference.cs de MessageContractAttributes aan te passen. Dit introduceert een afhankelijkheid op System.Net.Security, dus deze moet worden toegevoegd. Oorzaak is dat.net niet automatisch de ondertekeningseis uit de WSDL kan verwerken. Dezelfde aanpassing is overigens ook nodig voor aanleverservice en statusinformatieservice. Verder kan aanpassing van de afleverservice configuratie file nodig zijn. Het aanpassen van is nodig om de juiste security layout in de repsons te krijgen. Het uitzetten zorgt dat de repsons uberhaupt ondertekend wordt. De binding wordt opgezet met mtommessageencoding en httpstransport. Voor de aanleverservice en statusinformatieservice is dat niet nodig. Er is een zelfstandige webservice server gebouwd als windows service, dus los van IIS. Inrichting van de SSL certificaten gebeurt via windows, en alle certificaten/keys zitten in de windows certifcate store. 1.3 Headersissues in reponsberichten Digipoort 1.1:.Net, VB.net en Windows Communication Foundation (WCF) voor het ontvangen en versturen van berichten Toelichting issue Het gebruik van messageversion="soap11wsaddressing10" in de configuratie zorgt dat twee van de verplichte ws addressing headers worden opgenomen in de repsons. De twee andere verplichte ws adressing headers, te weten de MessageID header en de To-header, worden niet automatisch gevuld op basis van deze instelling. De Pagina 5 van 14

6 MessageId wordt toegevoegd in code via een IDispatchMessageInspector. Dat gaat goed en de MessageID wordt ook opgenomen in het repsonsbericht. Als de To-header wordt toegevoegd op dezelfde manier, wordt deze niet opgenomen in het responsbericht. Een DispatchMessageInspector is te vroeg in de WCF stack om dit TO veld te vullen. Het wordt later uitgefilterd door een code waar je niet bij kan De oplossing De manier om dit aan te pakken is het schrijven van een CustomMessageEncoder. Deze zit later in de pipeline. Een probleem in de code kan zijn dat zaken eromheen veel aanpassingen vergen door het toevoegen van een custom encoder aan je programma. Daarnaast geef je het toevoegen van een custom encoder ook aan in je programma in de Web.config van je c# of vb,net project door middel van extensies. De naam van deze extensie neem je ook op in de custom binding. In een.net project hoort een class te zitten dat de MessageEncoder class implementeert. In deze class komen een aantal functies voor waaronder de functies writemessage, maar ook de functies readmessage. Writemessage wordt gebruikt om de repsons dat de webservice genereert terug te sturen. Readmessage wordt gebruikt om de request dat verstuurd is naar de webservice te lezen. De implementatie van ReadMessage is vrij rechttoe rechtaan in de applicatie, maar je moet weten hoe je het moet implementeren in jouw versie van visual basic. Wanneer je dit hebt afgerond, heb je een custom message encoder die in staat is om ontvangen requests te lezen en repsons te versturen inclusief een To-header. Daarna moet je de door eerder opgenomen writemessage functies overnemen in class InterceptingMessageEncoder. De readmessagefuncties in de class InterceptingMessageEncoder kan je gebruiken en bekijken of het werkt. Werkt deze niet dan kun je readmessage-functies gebruiken als het visual basic betreft of hun equivalent in c#: In de writemessage functies voeg je een To-header toe, maar waarschijnlijk is dat ook de MessageID die ontbreekt. Deze kan op dezelfde plaats toegevoegd worden als de plaats waar de To-header wordt toegevoegd. Pagina 6 van 14

7 2 Waar moet ik rekening mee houden bij het gebruik van PHP? 2.1 SOAP Method wordt niet geïnitieerd Digipoort 1.1: PHP, Apache Indien geen gebruik wordt gemaakt van een WSDL kan het gebeuren dat voor binnenkomend berichtenverkeer geen SOAP method geïnitieerd wordt. Het gebruik van een normale SOAP server constructie heeft dan geen zin. Omdat SOAP over het HTTP protocol loopt, is een goed alternatief het lezen van de $HTTP_RAW_POST_DATA variabele. Hiermee is dan het volledige SOAP bericht beschikbaar. Knip eventueel de header en footer van het bericht om de XML verwerking te vereenvoudigen. 2.2 Afleverrespons en SOAP server Digipoort 1.1: PHP, Apache Als geen gebruik gemaakt wordt van een WSDL betekent dit dat je de afleverrespons op binnenkomende berichten niet via een SOAP server kunt beantwoorden. De SOAP server zal een foutbericht genereren en teruggeven aan Digipoort. Verstuur in dat geval een volledig opgebouwd afleverrespons XML-bericht via een 'echo', als ware het een browser die je beantwoordt. Ook hier geldt dat doordat SOAP over het HTTP protocol loopt het bericht keurig aankomt bij Digipoort. 2.3 Omgaan met namespaces PHP heeft in de laatste versies wel SOAP geïmplementeerd, maar zijn ook problemen mee. Het goede SOAP bericht dat Digipoort stuurt wordt door PHP vaak standaard niet goed behandeld. Het probleem zit m in de eigen namespaces van het bericht. Pagina 7 van 14

8 3 Wat kan mijn hash value problemen veroorzaken? Controleer in het koppelvlakspecificaties welk algoritme gebruikt moet worden en of die daadwerkelijk gebruikt wordt. Controleer verder of de juiste versie van WS security gebruikt wordt. Deze versie is ook te vinden in de koppelvlakspecificaties. Pagina 8 van 14

9 4 Is het Wsa:To verplicht in het afleverresponsbericht? Ja, het WS-Addressing element wsa:to is verplicht gesteld in de respons, waarbij een vaste standaardwaarde ( /anonymous ) aan dit element moet worden toegekend. Niet alle software die wordt gebruikt voor de implementatie van WUS-services is in staat om dit element automatisch in het responsbericht op te nemen, waardoor handmatige aanpassing benodigd kan zijn om dit gerealiseerd te krijgen. De WS-Addressing-standaard zelf zegt dat het element niet expliciet in het res-ponsbericht hoeft te worden opgenomen (net zo min als het element wsa:replyto in het requestbericht). Dit betekent dat het element niet expliciet als element in de XML hoeft te worden opgenomen. De ontvangende software moet het niet-expliciet aanwezig zijn van het element interpreteren als impliciet aanwezig met waarde Pagina 9 van 14

10 5 Waar vind ik de eisen die aan de berichtinhoud en de signering worden gesteld? In zowel de koppelvlakbeschrijving als in WSDL (zie ZIP-file van de koppelvlakbeschrijving) staat aangegeven welke elementen gesigneerd dienen te worden en met welke informatie de velden moeten worden gevuld. Zie voor de additionele eisen die voor bepaalde berichtstromen boven op de het generieke koppelvlak worden gesteld de berichtstroomspecificaties. Pagina 10 van 14

11 6 Welke verschillen in headers zijn er? Er zijn geen verschillen in de header van responsberichten van de afleverservice en die van de aanlever- en statusinformatieservice. Deze berichten betreffen allen berichten richting Digipoort en de header is daarom gelijk in opbouw. Aan beide berichten wordt de eis gesteld dat de berichten WSA en WSS te bevatten. Pagina 11 van 14

12 7 Zijn er voorbeeldberichten beschikbaar van de transportberichten? Ja, naast de specificaties zijn ook voorbeeldberichten beschikbaar. Deze zijn te vinden in de koppelvlakspecificaties. Pagina 12 van 14

13 8 Wat betekent de foutmelding SOAP header Security was not understood? Dit geeft aan dat deze header niet genegeerd mag worden als de software hem niet begrijpt. Dit wordt aangegeven door de waarde 1 in het attribuut mustunderstand (soap:mustunderstand="1"). Pagina 13 van 14

14 9 Moet ik zelf een waarde meegeven aan het element kenmerk (Aanlever-service)? Nee, het kenmerk -element hoeft niet te worden ingevuld (het element kan in zijn geheel worden weggelaten). Indien een Aanleverrequest door Digipoort wordt geaccepteerd, wordt een verwerkingsproces opgestart waaraan Digipoort een uniek identificatiekenmerk (GUID) toekent. Deze waarde wordt opgenomen in het element kenmerk in het responsbericht. Dit kenmerk kan worden gebruikt om de status van de (verwerking van het) aanleververzoek op te vragen (via de Statusinformatieservice). In theorie kan het kenmerk ook worden gebruikt bij een aanleverbericht dat aan een eerder bericht refereert, maar deze toepassing wordt momenteel niet gebruikt. Indien een kenmerk wordt meegegeven in de request, gaat Digipoort ervan uit dat deze waarde al bekend is (eerder toegekend aan een verwerkingsproces). Je zou dit (theoretisch) kunnen gebruiken om middels een request te refereren aan een eerder opgestart proces. Dat is voor e-factureren niet relevant; voor de Aanleverservice kan het element dan ook worden genegeerd. Pagina 14 van 14