1

Godkendelsesdato Version Rettet af Rettelse(r)

17/6-2010 1.0 Stefan L. Jensen

REST/SOAP Services Referenceimplementation

2

Indhold 1. Indledning ........................................................................................................... 3

2. Visual Studio solution ........................................................................................... 3

3. Konfiguration ....................................................................................................... 3

3.1. Installation af certifikat ...................................................................................... 3

3.2. Rettigheder til privat nøgle ............................................................................... 11

3.3. Indstillinger i Web.config .................................................................................. 13

dkal.service.rest.basehost ....................................................................................... 13

dkal.service.webservice.url ..................................................................................... 13

dkal.service.test.web.certificate.storename ............................................................... 14

dkal.service.test.web.certificate.storelocation ............................................................ 14

dkal.service.test.web.certificate.findtype................................................................... 14

dkal.service.test.web.certificate.findvalue ................................................................. 15

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”.

4

Vælg ”File” og dernæst ”Add/Remove Snap-in…”.

Vælg ”Certificates” og klik ”Add”.

5

Vælg ”Computer account”.

Vælg ”Local computer: (the computer this console is running on)”.

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.

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”.

8

Vælg ”Finish” for at importere certifikatet.

Certifikatet er nu importeret under ”Personal” ”Certificates”.

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.

10

Hvis rodcertifikatet er placeret under ”Personal”, så kan det trækkes ned under ”Trusted Root

Certification Authorities”.

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).

3.2. 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

http://www.microsoft.com/downloads/details.aspx?FamilyID=ed9c315c-31ac-4ccb-b62b-

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å: http://msdn.microsoft.com/en-

us/library/aa717039.aspx

For nemheds skyld er værktøjet også vedlagt i .zip-filen med referenceimplementationen.

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:

13

Brugerkontoen skal have rettighederne ”Read” samt ”Read & Execute” til certifikatets private

nøgle.

3.3. 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:

https://demo-rest.e-boks.dk/V1.svc/

o URL til integrationstestmiljøet.

https://rest.e-boks.dk/V1.svc/

o URL til produktionsmiljøet.

dkal.service.webservice.url Angiver URL’en der kaldes ifm. SOAP. Mulige værdier er:

https://demo-service.e-boks.dk/service/public/2/restricted/soap/{0}.asmx

o URL til integrationsmiljøet.

14

https://service.e-boks.dk/service/public/2/restricted/soap/{0}.asmx

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å http://msdn.microsoft.com/en-

us/library/system.security.cryptography.x509certificates.x509findtype.aspx. Typisk benyttes

”FindByThumbprint”.

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.