REVISION HISTORY
STS Installationsvejledning
REVISION HISTORY
NUMBER |
DATE |
DESCRIPTION |
NAME |
2.2.6 |
2015-02 |
|
JQ |
Contents
1 Introduktion
2 Forudsætninger
2.1 Java
2.2 JBoss
2.3 MySQL
2.4 Adgang til eksterne miljøer
2.5 Adgang til spærrelister
3 Installation
3.1 Installationsmetode
3.2 Fillokationer
3.3 MySQL
3.4 Test af installation
4 Konfiguration
4.1 JBoss
4.1.1 Admin beskyttelse
4.1.2 DataSource
4.1.3 Luna modul
4.1.4 Logning
4.2 Database
4.2.1 Audience konfiguration (ITS)
4.2.2 Audience konfiguration (ITS)
4.2.3 Audience konfiguration (Sosi2OIOSaml)
4.2.4 Autorisationer
4.3 Generel opsætning
4.3.1 Verifikation af certifikat under opstart
4.3.2 Datasource opsætning
4.3.3 Opsætning af Seal/føderation
4.3.4 CVR-RID opsætning
4.3.4.1 Fallback opsætning
4.3.5 Monitorering
4.3.6 Spærrelister
4.3.7 Autorisation
4.3.8 OIOSaml2Sosi—billetomveksling
4.3.9 Sosi2OIOSaml—billetomveksling
4.3.10 Timing
4.3.11 Timer-relaterede tasks
5 Tilpasning til produktion
Dette Dokument beskriver installationen og initiel opsætning af en STS service/server. STS installationen vil blive refereret til som service eller installation.
Det forudsættes at STS'en installeres på et NSP-lignende miljø. Herunder beskrives afhængigheder hertil i detalje.
STS kræver minimum Java 8, som kan downloades her:
http://www.oracle.com/technetwork/java/javase/downloads/
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:
https://svn.nspop.dk/public/components/seal/release-2.3.2/modules/seal/src/site/SOSI%20programmers%20guide.pdf
STS er testet og udviklet mod JBoss 8 (Wildfly) samt testet på et NIAB lign. miljø.
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å.
Der kræves adgang til følgende tjenester på internettet:
Disse er del af DanId's infrastruktur, og udstilles pt. på internettet indenfor følgende IP range: 87.48.159.0 til 87.48.
159.127.
Der kræves læs-adgang til en database indeholdende opdaterede data fra NSP Certificate Revocation Authority (CRA)
STS installationen består overordnet af: konfiguration af JBoss, deriblandt placering af konfigurations filer og deployment arkiv, og opsætning af database.
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:
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:
Øvrige filer skal bruges til database opsætning og som skabelon til konfigurering.
Der bruges en database til caching af data og vedligehold af adgangsinformation, så følgende skridt er nødvendige før STS kan startes:
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.
Både til test- og produktionsopsætning er det muligt at checke følgende egenskaber via http-kald:
De sidste 2 punkter verificeres ved at kalde:
http://<nsp>:8080/sts/admin/checkendpoints?action=check
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.
Installationen som beskrevet her vil fungere til testføderationen, og testbrugere vil kunne bruge det medfølgende web interface.
Det forventes at JBoss 8.x (Wildfly) anvendes og er installeret. Filplaceringer beskrevet nedenfor er rettet mod en NIAB/NSP installation.
Admininistrations interfacet til STS er beskyttet af HTTP basic authentication, hvilket i JBoss angives ved at tilføje et securitydomain elememt under security-domains rod elementet i /pack/jboss/standalone/configuration/standalone.
xml
<!– STS admin login –> |
Herefter burde det være muligt at tilgå web interfacet med anvendte akkreditiver på:
http://<nsp>:8080/sts/admin
Password og bruger kan ændres i property filerne. Det er anbefalet at ændre disse ifht. hvad der følger med i leverancen.
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 nogle allerede i /pack/jboss/standalone/deployments/sts-ds. xml og /pack/jboss/standalone/deployments/crasts-ds.xml. Deri findes password, brugernavn og databasenavn 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.
STS kan integrerer med en Lunaboks på to forskellige måder. Seal integrationen til bokse købt inden 2014 og NLL integrationen til bokse købt efter 2014.
Det forventes at den JBoss som STS deployes på indeholder et jboss-modul med navnet dk.nsi.nsp.sts.luna. STS afhænger af eksistensen af et sådant modul. Modulet kan være tomt - men skal, såfremt man anvender nyere Lunabokse, ændres til at indeholde Luna biblioteker (driver). Herved kan disse deployes/opgraderes uafhængig af STS.
Et modul oprettes på følgende sti:
/pack/jboss/modules/dk/nsi/nsp/sts/luna/main
Herunder skal passende jar-filer placeres samt filen module.xml, som skal indeholde følgende:
<?xml version="1.0" encoding="UTF-8"?> |
Dette vil fungere med Luna biblioteket, der fulgte med 2014 Luna-indkøbet. For integration op mod tidligere Lunabokse skal Luna driverne fortsat manuelt indlejres i sts.war inden deployment.
Logging i STS er normalt konfigureret i filen, /pack/jboss/standalone/configuration/log4j-sts.xml. navngivning og placering af logkonfigurationen kan ændres Der findes 3 overordnede log-emner:
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.
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 til brug for sundhedsfagligt token (IdentitytokenService) har følgende attributer:
En attribut, f.eks. lifetime, for en given audience tilføjes ved:
insert into audienceConfiguration values ('audience-uri', 'lifetime', 86400000)
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.
Audience konfiguration til brug for borger token (Bst2IdwsService / Saml2IdwsService) har følgende attributer:
Såfremt targetCertificate er angivet, skal dette indeholde et certifikat i Base64 format. Er et sådant angivet (det er valgfrit), vil svaret blive krypteret med denne nøgle.
certificate.xxx kan benyttes til at angive en liste af certifikater,
En attribut, f.eks. lifetime, for en given audience tilføjes ved:
insert into audienceConfiguration values ('audience-uri', 'lifetime', 86400000)
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.
Audience konfigurationen har følgende felter:
Alle felter på nær idCardMaxAgeMins er påkrævet (her fortolkes null værdier som 1440min=24timer).
En række identificere konfiguration for den angivne audience. Denne indsættes f.eks. ved:
insert into iboConfig values ('//sundhed.dk', 'MD9FDKG...', 'http://login.sundhed.dk/login. ←aspx', false, 60000, 0, 3600000, null);
Her er deliveryNotOnOrAfterOffset sat til et minut, og gyldigheden af det omvekslede assertion er på en time.
STS kræver adgang til en database tabel indeholdende autorisationer. Denne tabel vil typisk være oprettet og vedligeholdt via stamdata importerne i NSP.
Som default anvendes en tabel ved navn Autorisation i skemaet ejet af databasebrugeren benyttet i sts-ds.xml. Dette kan overstyres i services.xml
<bean id="authorizationService" class="dk.sosi.sts.server.service. ←StsAuthorizationService"> |
←- |
De vedlagte databasescripts opretter som udgangspunkt en valid stamdata tabel under sts-skemaet, hvilket givetvis skal ændres.
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 2.0.0 anvendes Spring xml konfiguration.
Konfigurationen er bredt ud på følgende filer:
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.
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.
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 to datasources angivet i:
config:sts.db
config:cra.db
Disse id'er 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)
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:
Table 1: Føderations opsætning
Værdi |
Beskrivelse |
dk.sosi.seal.pki.SOSITestFederation |
Dette er testfederationen og skal bruges i sammenhæng med test. Den skal ikke bruges i produktion. |
dk.sosi.seal.pki.SOSIFederation |
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.
Med STS følger et testcertifikat, teststs-1.keystore, som kan benyttes til testformål.
Til produktion kan der benyttes en Luna Box baseret løsning. Dertil kan følgende element benyttes:
seal:lunaBasedCredentialVault
Der er udkommenteret to forskellige konfigurationer seal:lunaBasedCredentialVault. Den første er til tidligere Lunabokse og den anden er til nyere Lunabokse.
Hvis der for dk.sosi.seal.vault.LunaCredentialVault ø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>
For dk.nsi.nsp.nll.LunaCredentialVault sættes de fleste properties direkte på bean definitionen, dog skal følgende værdi tilføjes til seal:sealSetupProperties
<prop key="sosi:cryptoprovider.sha1withrsa">LunaProvider</prop>
Når der vælges en anden vault, så skal tidligere nævnte alias opdateres. For at anvende en af de udkommenterede, så skal følgende f.eks. bruges:
<alias alias="credentialVault" name="lunaBasedCredentialVault"/>
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
Til testsammenhænge er det muligt at ændre opførslen, når en CVR-RID service fejler. Der kan sættes en WsOcesCvrRidFal lbackService op, som vil gøre følgende:
Ved begge tilfælde vil hændelsen blive logget. Konfigurationen sættes op i:
cvr-rid:cvrRidService
Hvor alias'et skal ændres sådan at cachingCvrRidService erstattes med cvrRidFallbackService. Sidstnævnte bean definition skal være aktiv; den findes udkommenteret lige efter førnævnte indgang.
STS indeholder nsp-test-rid.jks, der kan benyttes til at identificere STS overfor cvrRid (test) servicen. Ligeledes indeholder STS en testtdc.keystore, som benyttes som truststore - og markerer at vi stoler på cvrRid testservicens certifikat.
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 og krydscertifikater findes der også, som omtalt i driftsvejledningen, et check. Dette check konfigreres i:
interface:cvrRidEndpointsToCheck 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.
Sidstnævnte element bruges til konfigurering af check af 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 hentes fra en CRA database der kan konfigureres i
services:certificateStatusChecker
Det er muligt at vælge om STS skal cache alle revokeringer fra CRA databasen eller om der skal laves et opslag for hvert request som STS modtager. For bedre performance anvendes CraOcesCrlServiceCacheImpl og for mindre hukommelsesforbrug anvendes CraOcesCrlServiceDbImpl.
Følgende parametre eksisterer:
Table 2: CRL setup
Parameter |
Beskrivelse |
strict |
Denne boolean afgører hvad der skal ske, hvis en CRL ikke findes i databasen. Hvis den sættes til true vil manglende spærreliste betyde at certifikatet er spærret. |
ttl |
Angiver hvor lang tid en spærreliste kan få lov til at leve ud over den tid, der er angivet i spærrelisten selv. |
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.
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:
Table 3: Billetomveksling setup
Parameter |
Beskrivelse |
fuzzyTime |
Gyldigheden bagud i tid af det omvekslede SOSI id-kort. |
idCardDuration |
Gyldigheden fremadrettet i tid for det omvekslede SOSI id-kort. |
trustedVault |
Det java keystore (vault), hvori trust til OIOSaml token etableres. Heri skal der til produktionsformål ligge certifikatet fra NemLogin IdP'en. |
allowedDriftInSeconds |
Den tilladte drift i tid i sekunder ifht. NemLogin IdP'en. Dette tal angives som et ikke-negativt antal sekunder. Værdien bruges under validering af OIOSaml tokens. |
cprTrustCertificates |
Angiver en liste af certifikater (SSN). Vil typisk kun indeholde et NemLog-in certifikat. Ved billetomveksling fra OIOSaml til id-kort stoler vi på cpr-numre fra disse kilder, og kan derfor undlader opslag i CVR-RID servicen for disse. Denne er indført af hensyn til enkeltmandsvirksomheder, der modtager et token med angivelse af CVR-RID, der ikke kan slås op i CVR-RID. |
I det leverede er der anvendt et keystore, som indeholder 2 certifikater: det er "det nye test NemLogin IdP" og så et yderligt, som blot er valgt arbitrært, nemlig Seal certifikatet navngivet VicValidVoces. Disse certifikater bruges til aftestning og er nødvendige for at integrationstesten er succesfuld.
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 hentning 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 Section 4.2.3.
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"/> |
←- |
Angivne queries er også default. |
|
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.
Endvidere er der mulighed for at sætte checkTargetCertificate til true eller false (default er true, hvis ikke angivet).
Denne værdi angiver om det konfigurerede certifikat (benyttet til kryptering) er et validt OCES2-certifikat.
Øvrige værdier i elementet bør ikke ændres.
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.
Der konfigureres 2 tidsrelaterede jobs—opsætning af disse er placeret som de 2 sidste elementer i filen timers.xml.
Table 4: Timer setup
Id |
Beskrivelse |
checkDbTask |
Er et job, der forespørger database/datasource med angivne query og i det angivne interval. |
checkCrlTask |
Dette er et job, der sørger for at opdatere spærrelister fra CRA databasen hvis CraOcesCrlServiceCacheImpl er valgt. |
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.
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: