GCMWebservice. Versie SIVI

Transcriptie

1 GCMWebservice Versie SIVI

2 INHOUDSOPGAVE 1. INLEIDING DOELSTELLING DOELGROEP OPZET BELANGRIJKE CONCEPTEN GIM COMMUNICATIE MODULE (GCM) WAAROM GCM CLIENT SOFTWARE? STANDALONE CLIENTSERVER INSTALLATIE INLEIDING RECHTEN TECHNISCHE RANDVOORWAARDEN WINDOWS SERVER 2003 R MICROSOFT INTERNET INFORMATION SERVER (IIS) MICROSOFT.NET FRAMEWORK GCM PROGRAMMABESTANDEN CONFIGURATIE SPECIALE GEBRUIKER NET FRAMEWORK GEBRUIK BINNEN IIS WEB SERVICE EXTENSIONS VOOR ASP.NET APPLICATION POOL ONDER IIS GCMWEBSERVICE ONDER IIS RECHTEN OP DE DIRECTORY WINDOWS\TEMP CLIENT CERTIFICATEN INLEIDING MICROSOFT MANAGEMENT CONSOLE IMPORTEREN VAN EEN CLIENT CERTIFICATEN INCLUSIEF PRIVATE KEY RECHTEN GEVEN VOOR GEBRUIK VAN PRIVATE KEYS GIM REGISTER INLEIDING RECHTEN TOEVOEGEN EN WIJZIGEN VERWIJDEREN GIM TRANSACTIES LOGGEN INLEIDING AAN EN UITZETTEN VAN DE LOGFUNCTIONALITEIT BIJLAGE OPVRAGEN VERSIE INFORMATIE CHECKLIST INSTALLATIE EN INRICHTING GCMWEBSERVICE GCMWebservice Pagina 2 van 22

3 VERSIEBEHEER Versie Datum Auteur Status SIVI Vervallen SIVI Vervallen SIVI Definitief Wijzigingen ten opzichte van de vorige versie Hoofdstuk/Paragraaf Aanpassing Alle hoofdstukken Lay-out aangepast 2 Nieuw GCMWebservice Pagina 3 van 22

4 1. Inleiding 1.1 Doelstelling Deze handleiding beschrijft de configuratie waarin de GCM centraal wordt geïnstalleerd op een server en waarbij de GCM zelf als webservice wordt aangesproken door de verschillende software pakketten. 1.2 Doelgroep Doelgroep Upper Management Midden / Lijn Management Consultant, Ontwikkelaar e.d. Verzekeraars 1 Nee Nee Ja Intermediairs Nee Nee Ja Leveranciers Nee Nee Ja 1.3 Opzet Na deze inleiding volgt in hoofdstuk 2 de uitleg van een paar belangrijke concepten. In hoofdstuk 3 wordt op de installatie ingegaan en in hoofdstuk 4 op de configuratie. In hoofdstuk 5 wordt uitgelegd hoe client certificaten geïnstalleerd worden. In hoofdstuk 6 wordt uitgelegd hoe met het GIM Register omgegaan moet worden. Het loggen van GIM transacties wordt toegelicht in hoofdstuk 7. Het laatste hoofdstuk bevat bijlagen. 1 Verzekeraars en volmachten. Volmachten worden in het vervolg niet apart genoemd. GCMWebservice Pagina 4 van 22

5 2. Belangrijke concepten 2.1 GIM Communicatie Module (GCM) In 2007 heeft SIVI de GIM Communicatie Module (GCM) ontwikkeld als opvolger van de Koppelingsmodule. De GCM is geschikt voor gebruik in een Windows applicatie-server omgeving. De GCM is bedoeld om de GIM protocollen aan de kant van het intermediair snel en robuust te realiseren. Het is ook mogelijk de GIM protocollen zelf in te bouwen. 2.2 Waarom GCM Client software? Met de GCM kan een ontwikkelaar van een administratiepakket de GIM protocollen eenvoudig inbouwen. De GCM wordt aan de applicatie zijde aangestuurd op basis van.net API s (of een COM interface) en spreekt SOAP aan de kant van de verzekeraar. De COM interface is compatibel met de oude koppelingsmodule, het wordt aangeraden over te gaan naar de.net API aansturing. De GCM kan op 2 manieren worden geconfigureerd: Standalone: hierbij wordt de GCM uitsluitend op de PC van de gebruiker(s) geinstalleerd Client server: hierbij wordt een deel van de GCM op de PC van de gebruiker geinstallaeerd en daarnaast een deel (de GcmWebservice) op een server. 2.3 Standalone GCMWebservice Pagina 5 van 22

6 De StandAlone configuratie communiceert enerzijds via een.net API of COM interface met de TPapplicatie en anderzijds met SOAP berichten met de GIM-diensten van de maatschappij. Het voordeel van deze configuratie is dat alles op één PC geïnstalleerd kan worden. 2.4 ClientServer Ook in een ClientServer configuratie communiceert de TP-applicatie op basis van.net API s of een COM interface met de GCM. Aan de achterkant communiceert de GCM nu op basis van SOAP berichten met een centraal deel van de GCM, de GcmWebService. De GcmWebService communiceert op zijn beurt op basis van SOAP berichten met de diensten van de maatschappij. Het grote voordeel van deze gecentraliseerde oplossing is vereenvoudiging van onderhoud op bijvoorbeeld het GimRegister en Client Certificaten (Digitale Paspoort). GCMWebservice Pagina 6 van 22

7 3. Installatie 3.1 Inleiding Deze handleiding beschrijft de installatie van de GCMWebService, het deel dat op de centrale server van de TP draait. Voordat de software geïnstalleerd wordt op de Windows server moet de server goed geconfigureerd zijn. De GCM stelt geen speciale eisen aan de configuratie van de server zelf. Natuurlijk moet rekening gehouden worden met de mate waarin gebruikers toegang moeten krijgen tot de server. Hiervoor kan het beveiligingsbeleid van de partij die de server inricht gehanteerd worden. Voor de inrichting van de server wordt verwezen naar de documentatie van de leverancier. 3.2 Rechten Rechten installatie Degene die de installatie van GCM gaat uitvoeren dient te beschikken over Administrator-rechten. Rechten gebruik De gebruikers van de GCMWebService hebben geen speciale rechten nodig. De GCMWebService draait onder de rechten gekoppeld aan een speciale user. Bijvoorbeeld GCMUSER. Rechten beheer Voor het beheer van de GCM zijn Administrator-rechten noodzakelijk. 3.3 Technische randvoorwaarden De GCMWebservice draait onder IIS en.net Framework 2.0. De software is getest op Windows Server 2003 R2 met IIS 6.0 en.net-framework en op Windows XP IIS 5.1 met.net-framework In verband met beveiligingsissues wordt installatie van de GCMWebservice op Windows XP afgeraden. Voor ontwikkel- en testdoeleinden is het echter een prima oplossing. 3.4 Windows Server 2003 R2 Bij deze installatie wordt uitgegaan van een correct geïnstalleerde Windows Server 2003 R2 inclusief de laatste security updates. SIVI adviseert om bij servers altijd te kiezen voor de Engelstalige versie van het besturingssysteem omdat voor die versie altijd als eerste patches verschijnen, er meer artikelen in het Engels verschijnen en supportafdelingen van Microsoft vaak technische ondersteuning bieden in het Engels. Verder geldt voor de installatie dat de gebruiker die is ingelogd Administrator rechten dient te hebben. 3.5 Microsoft Internet Information Server (IIS) 6.0 Het inrichten van de server is geen onderdeel van de GCM. Toch is de installatie van IIS in deze handleiding opgenomen omdat de GCM alleen op een Windows server met IIS gebruikt kan worden. Het is echter hier niet de bedoeling om een handleiding voor het inrichten van een server te schrijven. Daarvoor wordt verwezen naar andere beschikbare handleidingen. Kies voor Start/Control Panel/Add or Remove Programs. Selecteer vervolgens Add/Remove Windows Components. GCMWebservice Pagina 7 van 22

8 Kies hier voor Application Server en vervolgens voor Details. Selecteer dan Application Server Console, en onder Internet Information Services (IIS) dient gekozen te worden voor World Wide Web Service. 3.6 Microsoft.Net Framework 2.0 Voor de werking van GCMWebservice wordt gebruik gemaakt van het Microsoft.Net Framework 2.0. De meest recente versie hiervan is te downloaden via de website van Microsoft. Zoek op de website van Microsoft naar.net Framework 2.0. Op de SIVI website staat ook een kopie van deze software. Na het downloaden van dotnetfx.exe kan de installatie worden gestart. Wanneer het.net Framework wordt geïnstalleerd voordat de IIS geïnstalleerd is, zal het.net Framework handmatig geregistreerd dienen te worden voor het gebruik ervan binnen IIS. Hiervoor wordt verwezen naar de documentatie van Microsoft over dit onderwerp. GCMWebservice Pagina 8 van 22

9 3.7 GCM programmabestanden De GCM software kan in iedere willekeurige directory geplaatst worden. Geadviseerd wordt om alle programmatuur onder de directory GCM te plaatsen. Tevens is het aan te raden om voor het GIM Register een aparte subdirectory aan te maken. Daarmee wordt de totale directory structuur als volgt: C:\GCM\GimRegister C:\GCM\GcmWebservice C:\GCM\GcmWebservice\bin De directory GimRegister bevat het bestand: GimRegister.xml De directory GcmWebservice bevat de bestanden: GcmWebservice.asmx premcompiledapp.config RegsiterPage.aspx RegisterWebService.asmx VersionInfoPage.aspx Web.config De directory GcmWebservice\bin bevat de bestanden: App_Code.compiled App_Code.dll App_Web_registerpage.aspx.cdcab7d2.dll App_Web_versioninfopage.aspx.cdcab7d2.dll Gcm.dll GcmCommon.dll GimRegister.xml ICSharpCode.SharpZipLib.dll Microsoft.Practices.EnterpriseLibrary.Common.dll Microsoft.Practices.EnterpriseLibrary.Common.xml Microsoft.Practices.EnterpriseLibrary.Logging.dll Microsoft.Practices.EnterpriseLibrary.Logging.xml Microsoft.Practices.ObjectBuilder.dll Microsoft.Practices.ObjectBuilder.xml De directory GimRegister bevat het bestand GimRegister.xml GCMWebservice Pagina 9 van 22

10 4. Configuratie 4.1 Speciale gebruiker Om ervoor te zorgen dat alle rechten goed afgestemd worden, is het nodig een speciale gebruiker aan te maken. Deze gebruiker geven we de naam GCMUSER. Een andere naam mag gekozen worden. In de hierop volgende stappen zullen we de GcmWebService en IIS zodanig configureren dat deze onder de GCMUSER zal draaien. Aanmaken GCMUSER Ga naar Start/Administrative Tools/Computer Management. Ga naar System Tools/Local Users and Groups/Users en kies via rechtermuisklik in het popupmenu voor New User.... GCMWebservice Pagina 10 van 22

11 Zet hier User must change password at next logon uit en User cannot change password en Password never expires aan en kies vervolgens voor Create. Het password moet voldoen aan de policy die geldt voor passwords van de server en/of het netwerk waarin de server draait. Bewaar het password goed. GCMUSER rechten voor het draaien van.net applicaties Standaard heeft een gebruiker geen rechten om applicaties, geschreven in.net 2.0 te draaien. Ga naar de.net Framework directory (c:\windows\microsoft.net\framework\v ) en geef de zojuist aangemaakte GCMUSER rechten. >aspnet_regiis ga GCMUSER GCMUSER rechten op GimRegister.xml Net als de GIM maakt de GCMWebservice gebruik van een GIM Register. Het bestand C:\GCM\GimRegister\GimRegister.xml moet minimaal benaderbaar zijn voor de GCMUSER. Afhankelijk van de bewerkingen die de GCMUSER moet kunnen uitvoeren kunnen de rechten uitgebreid worden. GCMUSER rechten in EventLog Om het mogelijk te maken meldingen aan te maken in het Event Log voor applicaties dient de GCMUSER hiervoor rechten te krijgen. Dit kan met behulp van de registry editor. >regedit Selecteer de key: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Eventlog\Application GCMWebservice Pagina 11 van 22

12 Rechtermuisklik en selecteer uit het menu >Permissions. Voeg de GCMUSER toe en geeft deze alle benodigde rechten. 4.2.Net Framework gebruik binnen IIS Deze stap mag overgeslagen worden indien zowel IIS als het.net Framework al eerder geïnstalleerd zijn. Na de installatie van het.net Framework moet het framework geregistreerd worden binnen IIS. Start hiervoor een commandwindow (Start>Run>Cmd) en ga naar de directory waar het.net Framework is geïnstalleerd: >cd C:\WINDOWS\Microsoft.Net\Framework\v \ Start vervolgens de registratie voor IIS als volgt: >aspnet_regiis i GCMWebservice Pagina 12 van 22

13 4.3 Web Service Extensions voor ASP.NET Om ASP.Net applicaties te kunnen draaien onder IIS moet deze WebServer extensie toegestaan worden. 4.4 Application pool onder IIS Maak een application pool aan met de naam GcmWebservicePool. Het voordeel hiervan is dat de volledige instellingen van IIS voor het draaien van de GCMWebservice op deze manier kunnen worden ingesteld. Geef de Application pool een duidelijke ID, bijvoorbeeld GcmWebServicePool. GCMWebservice Pagina 13 van 22

14 Stel vervolgens de properties in voor de nieuw gecreëerde application pool. Onder het tabblad Identity wordt vervolgens de keuze gemaakt om de pool onder de identiteit van onze GCMUSER te laten draaien. 4.5 GCMWebservice onder IIS Maak een virtual directory binnen IIS en stel de juiste rechten in. Indien gekozen wordt voor een andere dan de Default Web Site, moet gezorgd worden voor een correct IP-adres en een juist poortnummer omdat de service anders niet draait. GCMWebservice Pagina 14 van 22

15 Stel vervolgens voor deze website de properties in. De service moet gaan draaien onder de zojuist aangemaakt application pool (GcmWebServicePool). Controleer via ASP.NET tabblad instellingen op de juiste versie van het.net Framework en doe vervolgens de instellingen via Configuration. GCMWebservice Pagina 15 van 22

16 Stel onder General/Acpplication settings de Key s op een juist manier in. GimRegisterPath: StoreName: StoreLocation : ValidCertsOnly: UseProxy: ProxyUsername: ProxyPassword: ProxyAddress : ProxyPort: <de juiste locatie invullen> My LocalMachine <false/true> <false/true> <in geval van authenticated Proxy> <in geval van authenticated Proxy> Proxy adres Proxy poort 4.6 Rechten op de directory Windows\Temp De GCMUSER moet ook rechten krijgen om in de Windows\Temp directory te kunnen schrijven. GCMWebservice Pagina 16 van 22

17 5. Client Certificaten 5.1 Inleiding Om communicatie vanuit de GCMWebservice richting maatschappijen met behulp van client certificaten te laten werken, dienen alle benodigde certificaten in de LocalMachine store van de machine waarop IIS draait, geïmporteerd te worden. Omdat de GCMWebservice communiceert met andere webservers, dienen alle certificaten die nodig zijn om de betreffende server te vertrouwen (Root, Intermediate), ook onder de LocalMachine geïnstalleerd te zijn. Daarnaast dienen alle certificaten die nodig zijn om de te installeren client certificaten te vertrouwen, op de machine aanwezig te zijn. 5.2 Microsoft Management Console Om de Certifcate Store voor LocalMachine te bekijken dient er een Microsoft Management Console (MMC) gestart te worden en daarin de Certificates snap-in geladen te worden. 5.3 Importeren van een client certificaten inclusief private key Client certificaten inclusief private key worden op het Microsoft platform opgeslagen in *.pfx bestanden. Per gebruiker die via de GCMWebservice zal communiceren dient het betreffende *.pfx te worden geïmporteerd onder de Personal store op de LocalMachine. GCMWebservice Pagina 17 van 22

18 Let op dat het certificaat vertrouwd wordt. Dit kan gecontroleerd worden door het zojuist geïmporteerde certificaat te openen. Hieronder een voorbeeld van een niet vertrouwd certificaat. De juiste certificaten van de uitgevende instantie moeten nog geïmporteerd worden. GCMWebservice Pagina 18 van 22

19 5.4 Rechten geven voor gebruik van private keys Na dit alles heeft de Application pool identity, die in ons geval GCMUSER is, nog geen rechten om de private key te gebruiken. Hiervoor dient een speciale tool te worden gebruikt. Deze is te vinden in de Windows 2003 Resource Kit die te downloaden is op de website van Microsoft. Zoek naar de volgende term Windows Server 2003 Resource Kit Tools. De toolkit is ook te downloaden van de website van SIVI. >winhttpcertcfg -g -c LOCAL_MACHINE\MY -s -a GCMUSER Dit moet voor alle certificaten herhaal worden. Aangezien er onder Windows XP geen standaard mogelijkheid bestaat voor iets dergelijks als application pool configuratie, draaien daar de processen altijd onder een speciale user ASPNET. Bij een XP omgeving moeten aan deze user de juiste rechten worden toegekend. GCMWebservice Pagina 19 van 22

20 6. GIM Register 6.1 Inleiding In het GIM Register worden de beschikbare services van de maatschappijen gepubliceerd. Om een webservice actief te maken binnen de GCMWebservice dient een GIM Registratiebericht opgenomen worden in het GIM Register. Een GIM Registratiebericht geeft onder andere aan welke webservice ter beschikking staat en waar deze webservice te vinden is. Het GIM Register kan gezien worden als de Gouden Gids waarin de maatschappijen publiceren welke producten zij via GIM ontsluiten. Bij de GCM wordt de tool GimRegisterPage.aspx geleverd. Hiermee kan het GIM Register op de server onderhouden worden. Het programma is erg basic en dient als voorbeeld gezien te worden. 6.2 Rechten Door het verlenen van de de juiste rechten aan deze applicatie kan de toegang gereguleerd worden. 6.3 Toevoegen en wijzigen Met de applicatie zelf kunnen GIM Registratieberichten van maatschappijen worden toegevoegd in het GIM Register op de server. Indien een maatschappij al aanwezig is in het GIM Register, zal de bestaande registratie worden overschreven door het nieuw in te lezen bericht. Er wordt geen bevestiging gevraagd. 6.4 Verwijderen Door ingave van het betreffende GimObjectId is het mogelijk om een GIM registratie van de betreffende maatschappij te verwijderen uit het GIM Register. Er wordt geen bevestiging gevraagd. GCMWebservice Pagina 20 van 22

21 7. GIM Transacties loggen 7.1 Inleiding Alle transacties kunnen gelogd worden op de server. Zowel de inkomende als de uitgaande SOAPcommunicatie wordt naar de Windows Eventlog geschreven. Er is gekozen voor logging naar de Windows Eventlog omdat de systeembeheerder zijn eigen tools kan blijven gebruiken of gebruik kan maken van de tools van het operating system. Bij de logfunctionaliteit wordt gebruik gemaakt van de mogelijkheden die het.net Framework biedt. Logging kan naar wens ingesteld worden. Hierop wordt echter geen ondersteuning verleend. Entries in de Application Eventlog zijn te onderkennen door de source GcmWebService. Logging heeft een snelheidsverlies van ongeveer 10% tot gevolg. 7.2 Aan en uitzetten van de logfunctionaliteit In het bestand Web.Config in de directory \GCM\GCMWebService is de volgende sectie opgenomen. Hierin kan de LogFilter Aan of uitgezet worden. De weergave van de sectie is verkort opgenomen om de leesbaarheid te vergroten. Aan <loggingconfiguration tracingenabled="true" defaultcategory="general"> <logfilters> <add name="category" > <categoryfilters> <add name="ui Events"/> </categoryfilters> </add> <add name="priority"..> <add name="logenabled Filter" enabled="true"/> </logfilters> Uit <loggingconfiguration tracingenabled="true" defaultcategory="general"> <logfilters> <add name="category" > <categoryfilters> <add name="ui Events"/> </categoryfilters> </add> <add name="priority"..> <add name="logenabled Filter" enabled="false"/> </logfilters> GCMWebservice Pagina 21 van 22

22 8. Bijlage 8.1 Opvragen versie informatie Met de applicatie versioninfopage.aspx is het mogelijk het versienummer van de GCM Webservice die gebruikt wordt via een browser op te vragen. 8.2 Checklist installatie en inrichting GCMWebservice Installatie 1) Installeer Windows 2003 Server R2 2) Installeer Microsoft Internet Information Server (IIS) 6.0 3) Installeer Microsoft.Net Framework 2.0 4) Installeer GCM Webservice Programmatuur Inrichting 1) Aanmaken speciale gebruiker Rechten voor gebruik van.net Rechten voor het GIM Register Rechten voor de Eventlog Rechten voor gebruik van Windows-Temp directory 2) Toestaan van Webserver Extensions voor ASP.Net v2.0 3) Aanmaken Application pool Application Pool laten draaien onder speciale user 4) GCM Webservice onder IIS Juiste properties ingesteld 5) Juiste certificaten aanwezig Beheren certificaten Speciale user heeft rechten voor gebruik van certificaten GCMWebservice Pagina 22 van 22