Dokumenthistorik

...

...

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:

1. Krydscertifikater
2. CVR-RID/PID tjenester

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:

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.

...

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-1.keystore`, nsp-test-rid.jks, testtdc.keystore, test-new-nemLogin-idp.keystore skal i /pack/sts/
• sts.war skal i /pack/jboss/standalone/deployments.
• sts-ds.xml skal i /pack/jboss/standalone/deployments.
• crasts-ds.xml skal i /pack/jboss/standalone/deployments.
• hele kataloget sts, hvori der findes en række xml filer, skal i /pack/jboss/standalone/configuration.
• log4j-sts.xml, log4j-nspslalog-sts.properties og nspslalog-sosists.properties skal i /pack/jboss/standalone/configuration.
• jboss/stsadmin-users.properties og jboss/stsadmin-roles.properties skal i /pack/jboss/standalone/configuration.

Ø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:

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.

...

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 konfigurerede CVR-RID tjeneste med tilhørende SSL opsætning nåes.

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

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:

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:

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.

...

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:

• lifetime (default: 0)
• certificateAsReference (default: false)
• cprNumber (default: false)
• cvrNumberIdentifier (default: false)
• organizationName (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 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:

• targetCertificate (valgfri, default: ingen)
• certificate.xxx (vilkårligt antal properties pegende på certifikater)
• lifetime (default: 0)

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:

• 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.
• idCardMaxAgeMins maksimal alder på id-kortet

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

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:

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

...

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

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:

• Hvis kaldet til servicen fejler og cpr nummeret er kendt fra id-kortet, så vil dette blot blive anvendt som om det var resultatet.
• Hvis kaldet til servicen fejler og cpr nummeret ikke er kendt, så vil et konfigureret cpr nummer blive anvendt.

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

...

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

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

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"/>
<property name="updateAudiences" value="update iboConfig set audience = ? where audience = ?"/>

...

←-

Introduktion

Dette Dokument beskriver installation og initiel opsætning af en STS service/server. STS installationen vil blive refereret til som service eller installation.

Forudsætninger

Det forudsættes at STS’en installeres på et NSP-lignende miljø. Herunder beskrives afhængigheder hertil i detalje.

Java

STS kræver minimum Java 8. Ingen specifikke krav til versionen er identificeret.

STS forventes at være kompatibel med java 9 og java 10. Dette er dog ikke testet.

Kryptering

Seal biblioteket stiller visse krav til anvendelse af krypteringsalgoritmer med "unbounded strength" - hvilket i ældre java 8 versioner ikke er tilgængeligt som udgangspunkt.

Ved anvendelse af ældre java 8 versioner kræver dette separat download af US_export_policy.jar og local_policy.jar fra Oracle.

Ved nyere java 8 versioner er disse inkluderede som default. Og det vil her være tilstrækkeligt at sikre sikre at filen <JRE_HOME>/lib/security/java.policy indeholder propertyen:

crypto.policy=unlimited

Applikationsserver

STS er testet og udviklet til en wildfly-8.2.1 på et NSP/NIAB lignende miljø. Den forventes at være fremad kompatibel til nyere wildfly versioner (incl. wildfly 11).

STS forventes dog at kunne afvikles på en vilkårlig Java EE applikationsserver under hensyntagen til følgende:

• Det antages at system-propertyen jboss.server.config.dir er defineret og peger på en mappe som den kørende proces har læs-adgang til. Filbaseret konfiguration placeres i en underfolder (/sts) til denne.
• Der antages tilgængelighed af en MySql eller MariaDB databasedriver på applikationsserveren. Denne er allerede installeret på NSP-lignende miljøer. Eksempel database konfigurationsfiler antager anvendelse af MySql driver.
• På wildfly-lignende miljø kræves eksistens af et Jboss modul med navnet dk.nsi.nsp.sts.luna Dette kan evt være tomt, men SKAL eksistere.

Bemærk: Det har tidligere været nødvendigt med global sikkerhedsopsætning i standalone.xml vedrørende et "sts realm". Dette er ikke længere nødvendigt.

MariaDB

Der stilles ikke direkte krav til versionen, dog er version 10.3 brugt til udvikling. Det forventes at STS kan nå databasen på passende vis gennem en JBoss konfigureret datasource. Leverancen indeholder et eksempel herpå.

Applikationen er kompatibel med MySql 5 eller nyere.

Adgang til eksterne miljøer.

Der kræves adgang til følgende tjenester på internettet:

1. Krydscertifikater (http adgang)
2. CVR-RID og PID tjenester (2 vejs SSL)
3. Fuldmagtsservice (2 vejs SSL)

Det antages at adgangen sker gennem en proxy-server (f.eks. Stingray Traffic Manager) og at denne håndterer certifikater.

STS antager således at anvende HTTP.

Adgang til spærrelister

Der kræves læs-adgang til en database indeholdende opdaterede data fra NSP Certificate Revocation Authority (CRA)

Installation

STS installationen består overordnet af: tilrette konfigurations filer og opsætning af database.  STS anvender NSP's Continuous Integration og Continuous Deployment miljøer til byg og leverance af komponenten.

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 konfiguration kan bevares, såvidt det er muligt i forhold til skema ændringer.
3. Cachen i databasen, navnligt tabellerne cprhash, cprcache, uuidcprhash og uuidcprcache kan tømmes

Jenkins

STS bygges med NSP's Jenkins server via følgende jobs:

• STS_build - Bygger koden
• STS_push_snapshot - Pusher det nyeste snapshot image til NSP Docker Registry.

NSP Leverandøren er selv ansvarlige for at pushe release versioner af STS til NSP Docker Registry gennem Jenkins.

Docker

STS består af et Docker images som pushes til NSP Docker Registry med følgende navn:

Docker Compose

STS leveres samtidig som et sæt af Docker Compose filer i folderen https://svn.nspop.dk/svn/components/sts/trunk/compose.

For release x.y.z af STS findes Docker Compose filerne i folderen https://svn.nspop.dk/svn/components/sts/tags/release-x.y.z/compose

En leverance af STS består af en compose folder som beskrevet ovenfor samt tilhørende tags af de fem Docker images.

Compose folderen indeholder 5 underfoldere:

Java Keystores

Der benyttes et antal java keystores. Disse beskrives i driftsvejledningen.

Database

Der bruges en database til caching af data og vedligehold af adgangsinformation. Adgangen til denne styres af to datasources.

CRA datasource.

Benyttes til at tilgå cra-databasen, der rummer revokationslister indlæst på NSP via et baggrundsjob. Denne benytter database tabellen cra.crl og cra.revoked. Et eksempel på en datasource fil er vedlagt release pakken. Datasourcen skal anvende en bruger med læs adgang til de to nævnte tabeller.

STS datasource

Endvidere benyttes en STS datasource til at tilgå øvrige relationelle data. Et eksempel på en sådan fil findes i releasepakken under fil navnet sts-ds.xml.  Data kan inddeles i 3 "grupper", der alle kunne tilgås af den database-bruger der anvendes i datasourcen.

Stamdata

STS har behov for læs adgang til 2 tabeller under stamdata: stamdata.autreg og stamdata.nationalRoles. Skemaerne for disse vedligeholdes af respektive importere. De to tabeller indeholder hhv. en kopi af autorisationsregisteret, samt roller importerede fra SEB (Sundhedsdatastyrelsens Elektroniske Brugerstyring). Data vedligeholdes ved skedulerede import fra eksterne kilder

sts databasebrugeren skal således have læs adgang til disse tabeller.

STS konfiguration

STS indeholder endvidere 6 tabeller med konfigurationsdata. Disse befinder sig på Backoffice og replikeres ud på de enkelte NSP-noder. Data vedligeholdes gennem separate changes:

sts databasebrugeren skal således have læs adgang til disse tabeller.

STS cache

STS indeholder indeholder endelig følgende to caches:

1) en til mapningen fra SubjectSerialNumber til cpr nummer for medarbejdere og borgere. Dvs. SubjectSerialNumber kan enten være et PID eller et cvr-rid.

2) en til mapningen fra UUID til cpr nummer for medarbejdere og borgere. 

Tabellerne ligger lokalt på de enkelte NSP-noder uden replikering. Data opdateres automatisk af STS og data vil altid kunne slettes unden funktionel effekt (vil dog have negativ, midlertidig effekt på performance).

Der er tale om følgende tabeller:

sts databasebrugeren skal således have læs og skriv adgang til denne tabel

Endvidere har der tidligere været benyttet yderligere et antal database tabeller, der dog ikke længere er relevante.

Verifikation 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 konfigurerede CVR-RID tjeneste med tilhørende SSL opsætning nåes.

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.

Automatiseret test af installation

Testen udføres på lignende vis som i tidligere releases. Testen skal foretages fra en maskine der er IP whitelistet til at tilgå relevante services hos Nets (CRL, CVR-RID).

Testene antager eksistens af visse testdata. Disse bør på f.eks. test1 og test2 allerede eksistere i kraft af DTG.

På andre miljøer (f.eks. staging) kan det være nødvendigt at sikre eksistens af testdata ved eksekvering af filerne: 07-sts-testdata.sql, 08-autreg-testdata.sql

Opskrift på udførelse af tests:

• svn co https://svn.nspop.dk/svn/components/sts/tags/release-x.7.z/code sts-x.y.z
• cd sts-x.y.z
• mvn -Pintegration verify -Dunittests.skip=true -Dsts.url=http://<nsp-host>:8080

Testen skal køre igennem uden fejl. Ved testfejl, bør undersøges om man har glemt noget i ovennævnte opsætning af testdata. Testfejl der omhandler f.eks. NboIT skyldes formentlig uoverensstemmelser i forhold til forventingen i 07-sts-testdata.sql, mens de fleste andre fejl typisk vil skyldes afvigelser i forhold til autorisationsdata..

Konfiguration

Admin beskyttelse

Det har tidligere været nødvendigt at foretage admin beskyttelse i standalone.xml. Dette er ikke længere nødvendigt.

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 nogle allerede i /pack/wildfly8/standalone/deployments/sts-ds. xml og /pack/wildfly8/standalone/deployments/crasts-ds.xml. Deri findes connection properties til database-forbindelser. 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 forbindelses- checker op. Dette er medtaget i leverancens eksempel.

Luna modul

Alt efter hvilket miljø STS kører i skal det integrere med Luna HSM bokse. Uanset hvilket miljø STS afvikles i forventes det at der er et modul i Wildfly der hedder dk.nsi.nsp.sts.luna. I det docker image der leveres findes dette modul som et tomt modul. Dette er tilstrækkeligt når STS skal afvikles i et IKKE produktions miljø. I et produktions miljø skal dk.nsi.nsp.sts.luna modulet være opdateret med de korrekte jar filer til at integrere med Luna HSM boksene. 

Installation af Luna HSM jar filerne sker ved at volume mounte folderen med wildly modulet til /pack/wildfly8/modules/dk/nsi/nsp/sts/luna/main i den kørende container. Dette er beskrevet i release version af den docker-compose fil der leveres med projektet. 

Properties ved brug af Luna

I filen seal.xml skal følgende angives for at bruge Luna.

	<bean id="lunaBasedCredentialVault" class="dk.nsi.nsp.nll.LunaCredentialVault" init-method="init">
		<property name="keyAlias" value="key_alias" />
		<property name="certAlias" value="cert_alias" />
		<property name="password" value="password" />
		<property name="slot" value="1" />
		<property name="fixSubjectDN" value="true" />
	</bean>

Beskrivelse af properties:

keyAlias

certAlias

password

password

slot

1

fixSubjectDN

true

Logning

Logging i STS er normalt konfigureret i filen, /pack/wildfly8/standalone/configuration/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 er slået fra som default.

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

Afstemning af log-niveauet, rotation samt placering af logfiler overlades til NSP driften.

Applikations konfiguration (Spring)

STS konfigureres ved xml-baseret konfiguration af Spring-framework.

Konfigurationen er bredt ud på følgende filer (alle placeret i wildfly's konfigurationsfolder):

• sts/config.xml
• sts/cvr-rid.xml
• sts/federation.xml

• sts/interface.xml
• sts/seal.xml
• sts/services.xml
• sts/timers.xml
• sts/uuid2cpr.xml
• sts/uuid-rid.xml

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:

• OIOSaml2Sosi trust skal ændres (NemLogin certifikat), hvilket gøres i services.xml:nboConfiguration.

• Signerings certifikatet (STS’ens certifikat) skal ændres til produktions certifikatet - alternativt skal LUNA opsætning justeres.

• CVR-RID og UUID2CPR konfigurationen skal tilpasses til produktionsmiljøer; der skal ikke længere refereres til PP test.

• Endpoints-check skal tilpasses produktions endpoint

• I federation.xml:sosiFederation skal SOSITestFederation ændres til SOSIFederation.

• I uuid2cpr.xml skal uuid2cprProxyClient tilpasses til at pege på en deployet version af STS-UUID2CPR-PROXY.

Adresser på eksterne endpoints skal tilrettes.

Afvikling

STS startes og stoppes med Docker Compose kommandoer.

Standalone test

For en standalone test af STS hentes "compose" folderen for den ønskede version med Subversion og kommandoen "docker-compose up" køres i folderen "test".

NSP Miljø

På et NSP miljø hentes "compose" folderen for den ønskede version med Subversion og kommandoen "docker-compose up" køres i folderen "release".

Opgraderinger af eksisterende installationer.

Opgradering til STS-2.5.3 (JWT)

Opdater xml konfigurationsfilerne på baggrund af de leverede eksempler. Specielt er der ændringer til services.xml (ny service)

Vær endvidere opmærksom på det nye keystore (i test betegnet  /pack/sts/test-jwt-idp-trust.jks). Det leverede eksempel kan benyttes i test. I prod bør som udgangspunkt benyttes et tomt keystore. Efterfølgende changes kan så tilføje udvalgte certifikater til dette.

Opgradering til STS-2.5.6 (JWT)

Ny war-fil.

services.xml er opdateret med issuers - bemærk sagen https://jira.netic.dk/browse/NSP-14020 der tilføjer endnu en issuer. Denne skal IKKE fjernes.

Bemærk ligeledes at listen af issueres forventes at være forskellig i test og prod.

Releasen indeholder endvidere opdatering af nbo-truststore - der er tilføjet fornyede udgaver af nogle testcertifikater der udløber 3/9. Dette skal dog alene benyttes i test (dvs. både gamle og nye udgaver er pt. indeholdt).

Releasen indeholder endvidere opdatering af test-jwt-idp-trust.jks - ligeledes med fornyede udgaver af snarligt udløbne testcertifikater (dvs. både gamle og nye udgaver er pt. indeholdt).

Opgradering til STS-2.5.7 (nationale roller)

Ny war-fil.

Nye services i services.xml og timers.xml.

Ny databasetabel i sts_audconf (se scriptet 09-sts-roledefinitions.sql). sts-databasebrugeren skal have læs-adgang til denne.

Ny databasetabel i stamdata (se scriptet 10-create-sdm-roles.sql). sts-databasebrugeren skal have læs-adgang til denne.

Testdata til test1/test2:

Udfør de to scripts til 11-sdm-roletestdata.sql og 12-sts-roletestdata.sql.

Disse skal IKKE udføres i produktion.

Dokumentation:

Der er sket en mindre opdatering af anvenderguiden. Denne bør offentliggøres på et passende tidspunkt.

Opgradering til STS-2.6.1 (trust af nationale roller, tilføjelse af nationale rolle til NBO billetomveksling)

Ny war-fil.

Konfigurationsændringer i services.xml

Ny databasetabel i sts_audconf (se scriptet 13-sts-trustedcvr.sql). sts-databasebrugeren skal have læs-adgang til denne.

Testdata til test1/test2

Udfør scriptet 14-sts-testdata-trustedcvr.sql

Dette skal IKKE udføres i produktion

Dokumentation

En række guides er opdaterede og bør offentliggøres, herunder anvenderguide, design og arkitektur, installations- og driftsvejledning. Guides under arosiis space bør gennemgås med henblik på at få opdateringer offentliggjort.

Opgradering til STS-2.7.8

Konfigurationsændringer

Filen uuid2cpr.xml er tilføjet, hvor konfiguration til ny UUID service er defineret.

I config.xml er der tilføjet følgende import:

    <import resource="uuid2cpr.xml"/>

I log4j-sts.xml er timing log blevet disabled:

   <category name="STS.TIMING" additivity="false">
      <priority value="OFF"/>
      <appender-ref ref="TIMING"/>
   </category>

I services.xml er der tilføjet følgende beans:

	<bean id="userDataService" class="dk.sosi.sts.user.data.DbUserDataService">
		<property name="dataSource" ref="sts.db"/>
		<property name="sql" value="select * from sts_audconf.userData where cpr = ?" />
	</bean>

	<bean id="idpConfigService" class="dk.sosi.sts.idp.DBIdpConfigService">
		<constructor-arg ref="sts.db"/> <!-- the dataSource used -->
		<property name="selectByIssuer" value="SELECT attribute, attribute_value FROM sts_audconf.trustedIdpConfiguration WHERE issuer = ?" />
		<property name="selectAllEncryptionKeys" value="SELECT attribute_value FROM sts_audconf.trustedIdpConfiguration WHERE attribute like 'encryptionKey%'" />
	</bean>

	<bean id="idpCitizenConfigService" class="dk.sosi.sts.idp.DBIdpConfigService">
		<constructor-arg ref="sts.db"/> <!-- the dataSource used -->
		<property name="selectByIssuer" value="SELECT attribute, attribute_value FROM sts_audconf.trustedIdpCitizenConfiguration WHERE issuer = ?" />
		<property name="selectAllEncryptionKeys" value="SELECT attribute_value FROM sts_audconf.trustedIdpCitizenConfiguration WHERE attribute like 'encryptionKey%'" />
	</bean>

	<bean id="BST2SOSIRequestHandler" class="dk.sosi.sts.server.BST2SOSIRequestHandler" parent="abstractRequestHandler">
    	<property name="allowedDriftInSeconds" value="120"/> <!-- the number of seconds that the NemLogin IdP may drift from STS time -->
    	<property name="allowedAudience" value="https://sts.sosi.dk/"/>
    	<property name="fuzzyTime" value="300000"/> <!-- validity back in time for 5 minutes -->
		<property name="idCardDuration" value="86400000"/> <!-- validity forward in time for 24 hours -->
    	<property name="userValidationService" ref="userValidationService" />
    	<property name="userDataService" ref="userDataService" />
    	<property name="idpConfigService" ref="idpConfigService" />
		<property name="whitelistValidation" value="true" />
    </bean>

I services.xml har følgende beans fået nye properties:

	<bean id="nationalRolesService" class="dk.sosi.sts.roles.nationalroles.DbNationalRoleService">
		...
		<property name="uuidSql" value="select * from stamdata.nationalRoles where global_employee_uuid = ? and ValidFrom <= ? and (ValidTo is null or ValidTo > ?)" />
	</bean>

	<bean id="userValidationService" class="dk.sosi.sts.server.UserValidationService">
		...
		<constructor-arg ref="uuidService" />
	</bean>

	<bean name="nboConfiguration" class="dk.sosi.sts.server.NboConfig">
		...
		<property name="cprTrustCertificates">
			<list>
				...
                <value>UI:DK-O:G:23550132-5e1f-4e43-a5f9-048acf49e0b8</value><!-- lokal IT test - OCES3 -->
			</list>
		</property>
	</bean>

	<bean id="bs2IdwsRequestHandler" class="dk.sosi.sts.server.Bootstrap2IdwsRequestHandler" parent="abstractRequestHandler">
		...
		<property name="idpConfigService" ref="idpCitizenConfigService" />
	</bean>

	<bean id="iboRequestHandler" class="dk.sosi.sts.server.IboRequestHandler" parent="abstractRequestHandler">
		...
		<property name="emptyAttributeValue" value="NONE"/>
	</bean>

Databaseændringer

I databasen sts_audconf er der sket følgende (se 04-create-audconf-db.sql):

• Tilføjet 2 nye tabeller: trustedIdpConfiguration, trustedIdpCitizenConfiguration (sts-databasebrugeren skal have læs-adgang til disse)
• Tilføjet kolonnen 'comment' til tabellen  audienceConfiguration

OBS: Tabellen userData i sts_audconf simulerer det view der skal findes eller oprettes til opslag af fornavn og efternavn på CPR stamdata.

I databasen sts er der sket følgende (se 05-create-sts-localdb.sql):

• Tilføjet 2 nye tabeller: uuidcprhash, uuidcprcache (sts-databasebrugeren skal have læs- og skriv-adgang til disse)

Testdata

I databasen sts_audconf skal der ifm test tilføjes en ekstra tabel userData (se 04-create-audconf-db.sql) (sts-databasebrugeren skal have læs-adgang):

I databasen stamdata er der sket følgende (se 10-create-sdm-roles.sql):

• Tilføjet kolonnen 'global_employee_uuid' til tabellen nationalRoles

Følgende scripts til at indsætte testdata er blevet opdateret:

• 99-crl-testdata.sql
• 07-sts-testdata.sql
• 08-autreg-testdata.sql
• 11-sdm-roletestdata.sql
• 12-sts-roletestdata.sql
• 14-sts-testdata-trustedcvr.sql
• 17-sts-authorizationdata_nydata.sql

Følgende scripts til at indsætte testdata er blevet tilføjet:

• 19-sts-testdata.sql
• 20-sts-create-bst2sosi-testdata.sql
• 21-sts-create-bst2idws-testdata.sql

Andre ændringer

De to test keystores test-jwt-idp-trust.jks og test-new-nemLogin-idp.keystore er blevet opdateret.

Et nyt volume er blevet tilføjet til docker-compose.yml:

services:
  sts:
    ...
    volumes:
      - ../configuration/uuid2cpr.xml:/pack/wildfly8/standalone/configuration/sts/uuid2cpr.xml
...

Opgradering til STS-2.8.1

Konfigurationsændringer

I services.xml er property 'uuidSql' blevet fjernet igen.

Databaseændringer

De opdaterede og nye sql scripts fra STS-2.7.8 er blevet erstattet af:

• 19-sts-trustedidpconfiguration.sql
• 20-sts-update-audconf.sql
• 21-sts-uuidcpr.sql
• 22-sts-testdata.sql
• 23-sdm-testdata.sql (kun til lokal test)
• 24-sts-testdata.sql
• 25-sts-create-bst2sosi-testdata.sql
• 26-sts-create-bst2idws-testdata.sql

Opgradering til STS-2.8.2

Konfigurationsændringer

Der er foretaget en oprydning af beans i uuid2cpr.xml

Databaseændringer

OCES3 specifikke testdata er blevet flyttet fra 23-sdm-testdata.sql til 27-sdm-testdata-oces3.sql

Opgradering til STS-2.8.12

Konfigurationsændringer

Der er tilføjet en konfigurationsfil, federation.xml. Filen indeholder en bean, sosiFederation, som tidligere lå i seal.xml.

Databaseændringer

Ingen.

Opgradering til STS-2.8.20

Konfigurationsændringer

Der er tilføjet en konfigurationsfil, uuid-rid.xml, til opsætning af den nye uuid-rid service.

config.xml er opdateret, så den importerer uuid-rid.xml

Konfiguration af uuid2cprProxyClient er blevet samlet i uuid2cpr.xml. Det medfører også en ændring i cvr-rid.xml.

services.xml er opdateret, så nationalRolesService benytter den nye uuid-rid service.

Databaseændringer

Følgende script indsætter ny tabel til caching af uuid-rid relationer:

• 42-sts-uuidrid.sql

Følgende scripts indsætter nyt testdata:

• 43-sdm-testdata.sql (kun til lokal test)
• 44-sts-insert-userdata.sql

Andre ændringer

Et nyt volume er blevet tilføjet til docker-compose.yml:

services:
  sts:
    ...
    volumes:
      - ../configuration/uuid-rid.xml:/pack/wildfly8/standalone/configuration/sts/uuid-rid.xml
..

...

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

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:

...

.