Godkendelsesdato Version Rettet af Rettelse(r)

Transkript

1 REST/SOAP Services Referenceimplementation Godkendelsesdato Version Rettet af Rettelse(r) 17/ Stefan L. Jensen 1

2 Indhold 1. Indledning Visual Studio solution Konfiguration Installation af certifikat Rettigheder til privat nøgle Indstillinger i Web.config dkal.service.rest.basehost dkal.service.webservice.url dkal.service.test.web.certificate.storename dkal.service.test.web.certificate.storelocation dkal.service.test.web.certificate.findtype dkal.service.test.web.certificate.findvalue

3 1. Indledning Dette dokument giver en introduktion til referenceimplementationen til DKAL REST/SOAP services. Disse services eksponerer den funktionalitet, der er i DKAL, og referenceimplementationen er ment som en hjælp til at komme i gang med at bruge disse services. Dokumentet er rettet mod arkitekter og udviklere hos aftagere af servicen, der skal integrere løsninger op imod DKAL. 2. Visual Studio solution Referenceimplementationen består af en Visual Studio 2008 Solution (.NET 3.5) ved navn DKAL.ReferenceImplementation med et enkelt projekt DKAL.Test.Web. Første gang solutionen åbnes bliver man mødt med følgende besked, hvor man skal klikke Yes for at få webapplikationen oprettet i IIS: Derefter skal løsningen konfigureres, hvorefter den kan kompileres og køres. 3. Konfiguration 3.1. Installation af certifikat Da kommunikation med REST/SOAP foregår med både server- og klient-certifikat, er det vigtigt at klient-certifikater for de systemer, man ønsker at tilgå, er installeret på maskinen. Samtidig skal man være opmærksom på at den bruger, som applikationen kører under, har rettigheder til at tilgå certifikatet inkl. den private nøgle. Er rettighederne ikke sat korrekt op på den private nøgle, vil man sandsynligvis ikke se andet symptom end at klient-certifikatet ikke modtages af serveren. Følg nedenstående guide for installation af klientcertifikat: Klik på start-menuen og vælg Run. Indtast mmc i boksen. 3

4 Vælg File og dernæst Add/Remove Snap-in. Vælg Certificates og klik Add. 4

5 Vælg Computer account. Vælg Local computer: (the computer this console is running on). 5

6 Højreklik på Certificates under Personal og vælg All Tasks og dernæst Import Vælg certifikatet. Vær opmærksom på, at.cer-formatet ikke kan indeholde en privat nøgle. Certifikatet skal derfor importeres fra et andet format, fx.pfx/.p12, som vist ovenfor. 6

7 Indtast password for den private nøgle. Hvis du senere hen vil kunne eksportere nøglen igen, så marker afkrydsningsfeltet. Placer certifikatet under Personal. 7

8 Vælg Finish for at importere certifikatet. Certifikatet er nu importeret under Personal Certificates. 8

9 Dobbeltklik på certifikatet og ovenstående dialogboks vises. Hvis beskeden This certificate cannot be verified up to a trusted certification authority vises, så er rodcertifikatet placeret forkert. 9

10 Hvis rodcertifikatet er placeret under Personal, så kan det trækkes ned under Trusted Root Certification Authorities. 10

11 Når rodcertifikatet er placeret rigtigt, så skulle dialogboksen se ud, som vist ovenfor, når man klikker på certifikatet. Kontroller endvidere at certifikatet er gyldigt samt at den private nøgle er installeret (teksten you have a private key that corresponds to this certificate skal vises) Rettigheder til privat nøgle For at referenceimplementationen kan kalde DKAL REST/SOAP services skal brugerkontoen, som applikationen kører under, have adgang til certifikatets private nøgle. Brugerkontoen vil typisk være ASPNET (IIS 5 under Windows 2000, XP) eller NETWORK SERVICE (IIS 6 og 7 under Windows Server 2003, Server 2008, Vista, 7). Microsoft har udgivet et værktøj FindPrivateKey.exe, som kan benyttes til at finde den private nøgle. Værktøjet udgives sammen med Windows Communication Foundation (WCF), Windows Workflow Foundation (WF) and Windows Cardspace Samples for.net Framework 3.5 SP1, som kan downloades fra 721af1e2bfa8&displaylang=en. Efter endt installation kan FindPrivateKey.exe findes i C:\Samples\WCFWFCardSpace\WCF\Tools\FindPrivateKey\CS\bin. Dokumentation til værktøjet kan findes på: For nemheds skyld er værktøjet også vedlagt i.zip-filen med referenceimplementationen. 11

12 Følgende kommandoer viser certifikater under Personal i LocalMachine : FindPrivateKey.exe My LocalMachine Vælg certifikatet i dialogboksen og programmet outputter stien til den private nøgle: Private key directory: C:\Documents and Settings\All Users\Application Data\Microsoft\Crypto\RSA\MachineKeys Private key file name: 3c3ab1bd562eaf1d137b14c24e773813_563ac212-a298-4d55-970c-9cf6a3aaa342 Dernæst vælger man properties på filen og giver brugerkontoen læseadgang til certifikatets private nøgle: 12

13 Brugerkontoen skal have rettighederne Read samt Read & Execute til certifikatets private nøgle Indstillinger i Web.config Inden referenceimplementationen tages I brug er der en række indstillinger i Web.config, som skal konfigureres korrekt. Indstillingerne og deres betydning er beskrevet nedenfor. Nedenstående indstillinger angiver hvilke URL er der bliver kaldt ved brug af hhv. REST og SOAP. dkal.service.rest.basehost Angiver URL en der kaldes ifm. REST. Mulige værdier er: o URL til integrationstestmiljøet. o URL til produktionsmiljøet. dkal.service.webservice.url Angiver URL en der kaldes ifm. SOAP. Mulige værdier er: o URL til integrationsmiljøet. 13

14 o URL til produktionsmiljøet dkal.service.test.web.certificate.storename Angiver hvilket certificate store applikationen skal lede efter certifikatet i. Mulige værdier er: AddressBook (other people) AuthRoot (third-party root certification authorities) CertificateAuthority (intermediate certification authorities) Disallowed (revoked certificates) My (personal) Root (trusted root certification authorities) TrustedPeople TrustedPublisher Typisk installeres certifikatet under Personal, så værdien af denne indstilling skal som oftest være My. dkal.service.test.web.certificate.storelocation Angiver om applikationen skal lede efter certifikatet under brugerkontoen eller computeren. Mulige værdier er: CurrentUser LocalMachine Certifikatet bør installeres under LocalMachine. dkal.service.test.web.certificate.findtype Angiver typen af søgning applikationen foretager for at finde certifikatet. Mulige værdier er: FindByThumbprint FindBySubjectName FindBySubjectDistinguishedName FindByIssuerName FindByIssuerDistinguishedName FindBySerialNumber FindByTimeValid FindByTimeNotYetValid FindByTimeExpired FindByTemplateName FindByApplicationPolicy FindByCertificatePolicy FindByExtension FindByKeyUsage FindBySubjectKeyIdentifier Beskrivelse af de forskellige søgetyper kan findes på Typisk benyttes FindByThumbprint. 14

15 dkal.service.test.web.certificate.findvalue Værdien som der søges efter. Denne indstilling afhænger af typen af søgning ( dkal.service.test.web.certificate.findtype ). Hvis typen er sat til FindByThumbprint, så kan thumbprintet findes her: Dobbeltklik på certifikatet og vælg fanebladet Details for at finde certifikatets thumbprint. 15