STS Installationsvejledning. STS Installationsvejledning

Transkript

1 STS Installationsvejledning i STS Installationsvejledning

2 STS Installationsvejledning ii REVISION HISTORY NUMBER DATE DESCRIPTION NAME HT

3 STS Installationsvejledning iii Indhold 1 Introduktion 1 2 Forudsætninger Java JBoss MySQL Adgang til eksterne miljøer Installation Installationsmetode Fillokationer MySQL Test af installation Konfiguration JBoss Admin beskyttelse DataSource Logning Database Audience konfiguration (ITS) Audience konfiguration (Sosi2OIOSaml) Generel opsætning Verifikation af certifikat under opstart Datasource opsætning Opsætning af Seal/føderation CVR-RID opsætning Monitorering Spærrelister Autorisation IdentityTokenService (ITS) OIOSaml2Sosi billetomveksling Sosi2OIOSaml billetomveksling Timing Timer-relaterede tasks Tilpasning til produktion 10

4 STS Installationsvejledning 1 / 11 1 Introduktion Dette Dokument beskriver installationen og initiel opsætning af en STS service/server. STS installationen vil blive refereret til som service eller installation. 2 Forudsætninger Det forudsættes at STS en installeres på et NSP-lignende miljø. Herunder beskrives afhængigheder hertil i detalje. 2.1 Java STS kræver minimum Java 6, som kan downloades her: Desuden stiller SOSI biblioteket visse krav til konfigurationen af Java, som er beskrevet i "The SOSI Library: Programmers Guide"(se afsnit 3 "Set-up"). Dokumentet kan downloades sammen med SOSI biblioteket her: JBoss STS er testet og udviklet mod JBoss 6 samt testet på et NIAB miljø. 2.3 MySQL Der stilles ikke direkte krav til MySQL versionen, dog er version 5.1 brugt til udvikling. Det forventes at STS kan nå databasen på passende vis gennem en JBoss konfigureret datasource. Leverancen indeholder et eksempel herpå. 2.4 Adgang til eksterne miljøer Der kræves adgang til følgende tjenester på internettet: 1. Krydscertifikater 2. Spærrelister 3. CVR-RID tjenester Disse er del af DanId s infrastruktur, og udstilles pt. på internettet indenfor følgende IP range: til Installation STS installationen består overordnet af: konfiguration af JBoss, deriblandt placering af konfigurations filer og deployment arkiv, og opsætning af database.

5 STS Installationsvejledning 2 / Installationsmetode Ved en ny installation forventes der ikke opsætning fra en tidligere installation. Nærværende vejledning beskriver dette scenarie. Hvis der derimod opgraderes fra en tidligere version af STS kan følgende bemærkes: 1. Konfigurationsfiler skal opdateres til nyeste version; stier, passwords og lignende skal med over i ny konfiguration. 2. Database indhold kan bevares, såvidt det er muligt i forhold til skema ændringer. 3. Cachen i databasen, navnligt cprhash og cprcache, kan tømmes. 3.2 Fillokationer Leverancen indeholder et sæt af filer og kataloger, som skal installeres på en NSP søjle. Her tages kun højde for opsætning til test formål, altså til testføderationen. Tilpasning til produktionmiljø beskrives senere. Her følger en liste af filers placering: teststs.keystore, testtdc.keystore, test-new-nemlogin-idp.keystore skal i /pack/sts/ sts.war skal i /pack/jboss/server/default/deploy. sts-ds.xml skal i /pack/jboss/server/default/deploy. hele kataloget sts, hvori der findes en række xml filer, skal i /pack/jboss/server/default/conf. log4j-sts.xml, log4j-nspslalog-sts.properties og nspslalog-sosists.properties skal i /pack/jboss/server/default/conf. jboss/stsadmin-users.properties og jboss/stsadmin-roles.properties skal i /pack/jboss/server/default/conf/props. Øvrige filer skal bruges til database opsætning og som skabelon til konfigurering. 3.3 MySQL Der bruges en database til caching af data og vedligehold af adgangsinformation, så følgende skridt er nødvendige før STS kan startes: 1. Opret database 2. Opret bruger med passende privilegier. 3. Opret tabeller Se eksempelvis filen createdb.sql. For at testen i SOSI bibliotekets testtool fungerer mod opstillede STS, så skal bestemte certifikater være henholdsvis black- og whitelisted. Det kan gøres via administrationsinterfacet, men det kan også gøres ved direkte indsættelse i databasen, f.eks. ved at indlæse filen teststsdata.sql, hvilket er anbefalet. 3.4 Test af installation Både til test- og produktionsopsætning er det muligt at checke følgende egenskaber via http-kald: 1. opsætning af STS certifikat og dets gyldighed. Dette gøres via /sts/checkstatus. 2. kan krydscertifikater nåes. 3. kan spærrelister downloades.

6 STS Installationsvejledning 3 / kan konfigurerede CVR-RID tjeneste med tilhørende SSL opsætning nåes. De sidste 3 punkter verificeres ved at kalde: Det kan tage lidt tid at udføre kaldet. Retur kode vil ikke kunne bruges. (Den vil altid være 200) Derudover skal denne URL ikke bruges til automatisk verifikation, da det vil påvirke normal drift. I testføderationen er det muligt at udføre tests, som vil checke installationen. Derudover kan Seal.java s testtools (også omtalt som SOSI bibliotekets testtool) ligeledes bruges. Disse 2 tests er beskrevet i "Guide for udviklere". Udover egentlige tests er det en god ide at forespørge checkstatus URL en efter endt installation og konfiguration. 4 Konfiguration Installationen som beskrevet her vil fungere til testføderationen, og testbrugere vil kunne bruge det medfølgende web interface. 4.1 JBoss Det forventes at JBoss 6.x anvendes og er installeret. Filplaceringer beskrevet nedenfor er rettet mod en NIAB/NSP installation Admin beskyttelse Admininistrations interfacet til STS er beskyttet af HTTP basic authentication, hvilket i JBoss angives ved at tilføje et applicationpolicy elememt under policy rod elementet i /pack/jboss/server/default/conf/login-config.xml <!-- STS admin login --> <application-policy name="stsadmin"> <authentication> <login-module code="org.jboss.security.auth.spi.usersrolesloginmodule" flag="required"> <module-option name="usersproperties"> props/stsadmin-users.properties </module-option> <module-option name="rolesproperties"> props/stsadmin-roles.properties </module-option> </login-module> </authentication> </application-policy> Herefter burde det være muligt at tilgå web interfacet med anvendte akkreditiver på: Password og bruger kan ændres i property filerne. Det er anbefalet at ændre disse ifht. hvad der følger med i leverancen DataSource Det forventes at en datasource kan slåes op i JNDI. Dette kan tilvejebringes vha. en JBoss datasource descriptor. Hvis installationsvejledningen allerede er fulgt findes sådan en allerede i /pack/jboss/server/default/deploy/sts-ds.xml. Deri findes password, brugernavn og database-navn til database-forbindelse. Disse kan frit ændres. Anden opsætning af datasource er overladt til NSP projektet, dog ville det give mening at have en pool og sætte en forbindelseschecker op. Dette er medtaget i leverancens eksempel.

7 STS Installationsvejledning 4 / Logning Logging i STS er normalt konfigureret i filen, /pack/jboss/default/conf/log4j-sts.xml. 1 Der findes 3 overordnede log-emner: 1. TIMING; heri logges timing information, som nedbryder responstiden i de enkelt operationer. Denne funktion kan slåes fra. 2. AUDIT; heri logges request og respose. Denne log indeholder hele requestet, hvori også certifikatet kan findes. 3. øvrigt logges til filen sts.log Derudover anvendes NSP-util til at sla logge. Dokumentation herom findes i tilhørende dokumentation samt i STS ens Driftsvejledning. Konfiguration heraf findes i filerne log4j-nspslalog-sts.properties og nspslalog-sosists.prope rties. Afstemning af log-niveauet, rotation samt placering af logfiler overlades til NSP driften. 4.2 Database Dette afsnit beskriver konfiguration, der skal ligges i databasen. Konfiguration i databasen er af dynamisk natur, som forventes opdateres løbende på foranledning af anvendere Audience konfiguration (ITS) Audience konfigurationen har følgende attributer: lifetime (default: 0) certificateasreference (default: false) cprnumber (default: false) cvrnumber (default: false) orgname (default: false) itsystemname (default: false) authorizationcode (default: false) usereducationcode (default: false) idcardmaxage (defaulter til ikke at bruges) En attribut, f.eks. lifetime, for en given audience tilføjes ved: insert into audienceconfiguraiton values ( audience-uri, lifetime, ) Der eksisterer et unique-constraint på audience og attribut, så det er ikke muligt at indsætte flere værdier for samme audienceattribut par. Kun ovennævnte attributter er understøttet. 1 navngivning og placering af logkonfigurationen kan ændres

8 STS Installationsvejledning 5 / Audience konfiguration (Sosi2OIOSaml) Audience konfigurationen har følgende felter: audience normaliseret jvf. Anvenderdokument. publickey text felt. recipienturl streng. includebst angivelse om idkortet skal inkluderes i svar. deliverynotonorafteroffset tidsforskydelse i millisekunder. notbeforeoffset tidsforskydelse i millisekunder. notonorafteroffset tidsforskydelse i millisekunder. Alle felter er påkrævet. En række identificere konfiguration for den angivne audience. Denne indsættes f.eks. ved: insert into iboconfig values ( //sundhed.dk, MD9FDKG..., aspx, false, 60000, 0, ); Her er deliverynotonorafteroffset sat til et minut, og gyldigheden af det omvekslede assertion er på en time. 4.3 Generel opsætning I forhold til tidligere STS konfiguration, markerer version 2.0.0, en radikal forandring. Tidligere blev der anvendt en normal java property fil. Fra og med version anvendes Spring xml konfiguration. Konfigurationen er bredt ud på følgende filer: sts/config.xml sts/cvr-rid.xml sts/interface.xml sts/seal.xml sts/services.xml sts/timers.xml Der er mange aspekter af funktionaliteten der kan ændres i disse xml, og ikke alle er driftsorienteret. I det følgende bruges følgende syntax for at referere til en delmængde af indeholdet af en given konfigurationsfil: config:log4jinitialization Hermed refereres til det første bean-element i filen config.xml, altså bean-definitionen log4jinitialization. Dette er tilfældigvis, hvor log4j konfigurationsfilens placering kan bestemmes. I den element kan placering af log konfigurationen ændres. I det følgende vil konfigurationen gennemgåes i detalje Verifikation af certifikat under opstart STS verificerer dens certifikat under opstart. Dette kan slåes fra ved at udkommentere følgende element: config:startupverification Dette er dog ikke anbefalet. Certifikatet verificeres også på hvert request samt ved check-status kald.

9 STS Installationsvejledning 6 / Datasource opsætning Enkelte services benytter sig af databasen. Disse services kan konfigureres uafhængigt af hinanden. Som default er alle services dog sat op til at bruge samme datasource angivet i: config:sts.db Dette id går igen i de omtalte services. Men tilsvarende opsætninger af nye datasources, som er anderledes konfigureret, kan sættes op og benyttes til de enkelte services. Se f.eks. : services:authorizationservice Her angives datasourcen som første argument. (Konstruktor argument) Opsætning af Seal/føderation Det er vigtigt at føderationen sættes rigtigt op. Dels skal den rigtige føderation vælges, hhv. test eller produktion, og dels skal issuer sættes op til en fornuftig værdi i seal:sealsetupproperties. Føderationen vælges i: seal:sosifederation Her kan value sættes ifht: Tabel 1: Føderations opsætning Værdi dk.sosi.seal.pki.sositestfederation dk.sosi.seal.pki.sosifederation Beskrivelse Dette er testfederationen og skal bruges i sammenhæng med test. Den skal ikke bruges i produktion. Dette er produktions federationen. Derudover skal STS certifikatet sættes op. Der er dertil lavet et konfigurations-alias, credentialvault. Dette er i leverancens konfiguration sat til at være fil-baseret. Dette kan ses i følgende 2 elementer: seal:credentialvault seal:filebasedcredentialvault I det sidste referede element kan stien samt password til det java keystore, hvori certifikatet ligger, konfigureres. Til produktion kan der benyttes en Luna Box baseret løsning. Dertil kan følgende element benyttes: seal:lunabasedcredentialvault Det er udkommenteret i leverancen. Hvis der ønskes yderligere properties sat til konfiguration af Luna Boxen, skal disse indsættes i seal:sealsetupproperties. Bla. kan følgende parameter tilføjes <prop key="dk.sosi.seal.vault.lunacredentialvault.slot">42</prop> <prop key="dk.sosi.seal.vault.lunacredentialvault.pwd">test1234</prop> <prop key="dk.sosi.seal.vault.credentialvault.alias">soso:alias_system</prop> Når der vælges en anden vault, så skal tidligere nævnte alias opdateres. For at anvende det udkommenterede, så skal følgende f.eks. bruges: <alias alias="credentialvault" name="lunabasedcredentialvault"/>

10 STS Installationsvejledning 7 / CVR-RID opsætning STS skal kunne mappe certifikater til CPR, hvor dette er muligt. Derfor skal den kunne tilgå CVR-RID services. Disse kan findes segmenteret eller samlet for forskellige miljøer. Konfigurationen tillader at sætte en CVR-RID service op for et givet rod-certifikat. Et rod-certifikat definerer dermed et givet miljø. I produktion findes pt. OCES1 og OCES2. Mapningen fra rod-certifikat til service kan findes i: cvr-rid:cvridendpoints I det leverede er alle test miljøer sat op: IG, PP og OCES1 test. Til produktion skal kun de allerede nævnte miljøer, OCES1 og OCES2 blot sættes op. Fra ovenstående element refereres der til en række andre elementer i samme fil. I disse konfigureres de enkelte endpoints med trust- og keystore samt dertilhørende akkreditiver. Desuden kan man angive en connect-timeout til angivne URL. Udover endpoints kan caching strategien desuden konfigureres. En fundet mapning vil ikke ændres, hvorfor der aldrig vil være en forretningsmæssig grund til at tømme cachen. Mapninger gemmes i databasen, hvortil datasource, som tidligere omtalt kan tilpasses. Mod databasen kan der vælges om CPR nummeret skal gemmes eller om et hash skal gemmes. I begge tilfælde vil der blive gemt nok til, at afgøre om et givet CPR nummer tilhører et givet certifikat. Dog vil sidstnævnte ikke alene kunne bruges, hvis CPR nummeret ikke leveres med i requestet. Derfor er den ikke-hashede udgave at anbefalde, men der kræves dertil også større sikkerhed (godkendelse). Konfigurationen hertil findes som følgende: cvr-rid:cvrridnonhashcache cvr-rid:cvrridhashcache Den ene er leveret udkommenteret. Når en af disse vælges skal tilhørende alias opdateres: cvr-rid:cvrridcache Monitorering Det er muligt at finpudse diverse ikke direkte funktions orienterede aspekter, såsom monitorering og aftestning. Til monitorering kan database select-statement ændres, dette gøres i: interface:monitordbcheck Til aftestning af endpoints til CVR-RID, krydscertifikater og spærrelister findes der også, som omtalt i driftsvejledningen, et check. Dette check konfigreres i: interface:cvrridendpointstocheck interface:crlstocheck interface:xcertocheck Førstnævnte burde blot være et alias til cvrridendpoints, da der dermed checkes den konfiguration, der er sat op til STSs normal funktion. Dog kan man vælge enkelte endpoints specifikt, hvis man ønsker dette. Dette er hvad den leverede konfiguration beskriver. Øvrige 2 elementer bruges til konfigurering af check af hhv. spærrelister og krydscertifikat, altså om givne URL er kan hentes af STS en. Det hentede vil ikke på nogen måde bidrage til STS ens funktion det er kun til test formål. Som det leverede viser, så kan connection-timeout samt read-timeout konfigureres pr. URL Spærrelister Hentning og håndtering af spærrelister kan konfigureres. Dette gøres i services:certificatestatuschecker Følgende parametre eksisterer:

11 STS Installationsvejledning 8 / 11 Tabel 2: CRL setup Parameter interval strict crl_ttl readtimeout connectiontimeout Beskrivelse Hvor lang tid en spærreliste må leve i STSen før den er tvunget opdateret. Denne boolean afgører hvad der skal ske, hvis en CRL ikke kan downloades. Hvis den sættes til true vil manglende spærreliste betyde at certifikatet er spærret. Angiver hvor lang tid en spærreliste kan få lov til at leve ud over den tid, der er angivet i spærrelisten selv. Angivelse af timeout på hentning af spærreliste. Denne værdi er ikke påkrævet. Angivelse af connect-timeout på hentning af spærreliste. Denne værdi er ikke påkrævet. Desuden kan spærrelister prepopuleres. Dette kan gøres ved at sætte spærrelister op til at blive hentet ved opstart i: timers:prepopulatecrl Der er 3 parametre til implementationen, hvoraf de første 2 ikke må ændres. Den sidste parameter angiver en mapning fra et vilkårligt unikt id til en URL, hvorpå en spærreliste ønskes hentes. Jobbet til hentning sættes op i samme fil under timertask:prepopulatecrl Autorisation Autorisation servicen kan konfigureres til at tilgå autorisations registeret i en given database med et given SQL query. Dette gøres i: services:authorizationservice Som default er følgende konfigureret: SELECT aut_id, edu_id FROM autreg WHERE cpr=? Det essentielle er her at der returneres et par med aut_id og edu_id ud fra indsatte CPR nummer. Der kan og skal returneres multiple rækker/par, hvis det findes IdentityTokenService (ITS) Til IdentityToken servicen kan der konfigureres 3 parametre: den datasource, der benyttes til at hente en specifik audience konfiguration, fuzzytime, som er tiden et Identity Token har som levetid bagud i tiden, 2, og endeligt den SQL query, der bruges for at forespørge databasen. Alle parametre konfigureres her: services:itsconfigservice Per default er SQL query sat til: SELECT attribute, attribute_value FROM audienceconfiguration WHERE audience =? Det query returnerer alle attributter og deres værdier for en given audience, f.eks. kan være en audience. Attributterne er beskevet i Afsnit Dette er for at komponensere for usikkerheden i tiden hos anvendere.

12 STS Installationsvejledning 9 / OIOSaml2Sosi billetomveksling Til billetomveksling, her omveksling fra OIOSaml tokens til SOSI id-kort, kan der konfigures en række parametre. Disse findes her: services:nboconfiguration Overordnet er det: Tabel 3: Billetomveksling setup Parameter fuzzytime idcardduration trustedvault Beskrivelse Gyldigheden bagud i tid af det omvekslede SOSI id-kort. Gyldigheden fremadrettet i tid for det omvekslede SOSI id-kort. Det java keystore (vault), hvori trust til OIOSaml token etableres. Heri skal der til produktionsformål ligge certifikatet fra NemLogin IdP en. I det leverede er der anvendt en keystore, som indeholder 2 certifikater: det var "det nye test NemLogin IdP"og så et yderligere, som blot er valgt arbitrært, nemlig Seal certifikatet navngivet VicValidVoces. Disse certifikater bruges til aftestning og er nødvendige for at testen er succesfuld Sosi2OIOSaml billetomveksling Til billetomvekslingen fra SOSI ID-kort til OIOSaml tokens findes der 2 konfigurations muligheder udover selve servicen: en service til hentning af enkelte audience konfigurationer og så en konfigurations checker. Konfiguration af henting findes her: services:iboconfigservice Her kan datasourcen samt SQL query konfigureres. Default query er SELECT publickey, recipienturl, includebst, deliverynotonorafteroffset, notbeforeoffset, notonorafteroffset FROM iboconfig WHERE audience =? Nævnte kolonner er beskrevet i Afsnit Konfigurations checkeren er egentlig blot en funktionalitet, der aktiveres ved opstart som normaliserer alle fundne audiences i databasen. Konfiguration heraf findes i: services:iboconfigchecker Heri findes yderligere SQL queries, der kan ændres. Følgende kan tilføjes (en eller begge) til elementet: <property name="selectaudiences" value="select audience from iboconfig"/> <property name="updateaudiences" value="update iboconfig set audience =? where audience =?"/> Angivne queries er også default. Selve servicen konfigureres her: services:iborequesthandler Her er der mulighed for at sætte validateenvelopesignature til true eller false. Denne værdi angiver om signaturen på forespørgelser valideres eller ikke. I sammenhænge med SOSI-GW skal denne sættes til false. Øvrige værdier i elementet burde ikke ændres.

13 STS Installationsvejledning 10 / Timing STS funktionalitet afhænger i nogen grad af leverede libraries samt eksterne services, derfor er det vigtigt at kunne fortælle hvor lang tid enkelte dele af STS ens funktion tager. Dertil er der introduceret en "timing-funktionalitet som rapporterer hvor lang tid enkelte dele tager. Denne konfigureres i: timers:timing Hvis funktionaliteten ikke ønskes slået til, kan elementet blot fjernes. Dette er dog ikke anbefalet, da det kan være meget behjælpeligt i debug-sammenhæng. SLA-logning overlapper for visse dele denne funktion, men udfylder ikke helt funktionalitet. Lognings kategorien samt ignorerede værdier kan konfigureres som de første 2 parametre til arguments listen. (Sidste værdi er dybden af kald-stakken, der kan imødekommes) Ignorerede værdier angives som prefix til følgende format class#method Name Timer-relaterede tasks Der konfigureres 3 tidsrelaterede jobs opsætning af disse er placeret som de 3 sidste elementer i filen timers.xml. Tabel 4: Timer setup Id checkdbtask prepopulatecrl checkcrltask Beskrivelse Er et job, der forespørger database/datasource med angivne query og i det angivne interval. Et job, der per default kun udføres en gang. Dette job prepopulerer spærrelister. Denne funktionalitet er beskrevet i et tidligere afsnit. Dette er et job, der søger for at opdatere spærrelister uafhængigt af requests. Hver enkelt timer job sættes med følgende parametre: delay tiden i millisekunder efter opstart, der ventes før jobbet udføres første gang. onetime boolean, der angiver om jobbet kun skal udføres en gang. period intervallet i millisekunder jobbet udføres i medmindre onetime er sat til true. Den leverede konfiguration hertil er anbefaldet. 5 Tilpasning til produktion Den leverede konfiguration samt beskrivelsen i indeværende dokument passer til opsætning ifbm. test. Når en produktion opsætning ønskes, så er der en del konfiguration, der skal ændres. Her følger en lister af punkter: 1. OIOSaml2Sosi trust skal ændres, hvilket gøres i services:nboconfiguration. 2. Sosi2OIOSaml; der skal tages stilling til om validering af forespørgelser skal slåes til eller ikke. Se Afsnit nborequesthandler skal pege på dk.sosi.sts.server.nborequesthandler og ikke dk.sosi.sts.server.nbotestrequesthandler.

14 STS Installationsvejledning 11 / Signerings certifikatet (STS ens certifikat) skal ændres til produktions certifikatet, se Afsnit I seal:sosifederation skal SOSITestFederation ændres til SOSIFederation. 6. CVR-RID konfigurationen skal tilpasses til produktionsmiljøer; der skal ikke længere refereres til IG, PP og OCES1 test. Se Afsnit Endpoints-check skal tilpasses produktions endpoints, se Afsnit Prepopulering af spærrelister skal tilpasses til produktions spærrelisteendpoints, se Afsnit