Version | Dato | Ansvarlig | Beskrivelse |
| 1 | 6.7.2018 | KSR | Opdateret på baggrund af fuldmagtsprojektet |
| 2 | 17.9.2018 | KSR | Opdateret beskrivelser af installationer (2.5.7) |
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.
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.
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
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:
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.
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.
Der kræves adgang til følgende tjenester på internettet:
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.
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: konfiguration af Wildfly, 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:
teststs-1.keystore`, nsp-test-rid.jks, testtdc.keystore, test-new-nemLogin-idp.keystore skal i /pack/sts/
sts.war skal i /pack/wildfly/standalone/deployments.
sts-ds.xml skal i /pack/wildfly/standalone/deployments.
crasts-ds.xml skal i /packwildfly/standalone/deployments.
hele kataloget sts, hvori der findes en række xml filer, skal i /pack/wildfly/standalone/configuration.
log4j-sts.xml, log4j-nspslalog-sts.properties og nspslalog-sosists.properties skal i/pack/wildfly/standalone/configuration.
Øvrige filer skal bruges til database opsætning og som skabelon til konfigurering
Der benyttes et antal java keystores. Disse beskrives i driftsvejledningen.
Der bruges en database til caching af data og vedligehold af adgangsinformation. Adgangen til denne styres af to datasources.
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.
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 u datasourcen.
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
| Database | Skema | Tabel | Beskrivelse | Opdateringer | SQL |
|---|---|---|---|---|---|
| Backoffice (replikeret) | stamdata | autreg | Indeholder aktuelt aktive autorisationer. | Opdateres af autorisationsimporter | Konfigurabel i services.xml |
| Backoffice (replikeret) | stamdata | nationalRoles | Indeholder roller importerede fra SEB. | Opdateres af SEB importer | Konfigurabel i services.xml |
sts databasebrugeren skal således have læs adgang til disse tabeller.
STS indeholder endvidere 4 tabeller med konfigurationsdata. Disse befinder sig på Backoffice og replikeres ud på de enkelte NSP-noder. Data vedligeholdes gennem separate changes:
| Database | Skema | Tabel | Beskrivelse | Opdateringer | SQL |
|---|---|---|---|---|---|
| Backoffice (replikeret) | sts_audconf | audienceConfiguration | Indeholder konfiguration af borger-billetomveksling med angivelse af audiences, og adgang til disse. beskrevet nærmere i driftsvejledningen | Via changes | Konfigurabel i services.xml |
| Backoffice (replikeret) | sts_audconf | iboConfig | Indeholder konfiguration af (Medarbejder) billet omveksling fra id-kort til OIOSaml token (sikker browseropstart). Beskrevet nærmere i driftsvejledningen. | Via changes | Konfigurabel i services.xml |
| Backoffice (replikeret) | sts_audconf | roleDefinitions | Indeholder konfiguration af gyldige nationale roller (dvs. de SEB-roller der accepteres af STS, og hvorledes disse ser ud i id-kortet) | Via changes | Konfigurabel i services.xml |
| Backoffice (replikeret) | sts_audconf | trustedCvr | Beskriver hvilke cvr-numre der har adgang til at anvende nationale roller, uden at få disse verificeret. | Via changes | Konfigurabel i services.xml |
sts databasebrugeren skal således have læs adgang til disse tabeller.
STS indeholder indeholder endelig en cache at mapningen fra SubjectSerialNumber til cpr nummer for medarbejdere og borgere. Dvs. SubjectSerialNumber kan enten være et PID eller et cvr-rid. Tabellen 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 tabel
| Database | Skema | Tabel | Beskrivelse | Opdateringer | SQL |
|---|---|---|---|---|---|
| Lokal på NSP noder | sts | cprcache | En lokal cache af svar fra opslag på cvr-rid og pid-services. | Opdateres løbende af STS | Ligger i java-koden |
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.
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 elksistens af testdata ved eksekvering af filerne: 07-sts-testdata.sql, 08-autreg-testdata.sql
Opskrift på udførelse af tests:
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..
Det forventes at JBoss 8.x (Wildfly) anvendes og er installeret. Filplaceringer beskrevet nedenfor er rettet mod en NIAB/NSP installation.
Det har tidligere været nødvendigt at foretage admin beskyttelse i standalone.xml. Dette er ikke længere nødvendigt.
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.
STS kan integrere med en Lunaboks på to forskellige måder. Seal integrationen til bokse købt inden 2014 (generation 4) og NLL integrationen til bokse købt efter 2014 (generation 5).
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.
Modulet kan (såfremt det ikke allrede findes) oprettes med følgende jboss-cli kommando:
module add --name=dk.nsi.nsp.sts.luna --resources
I modulet skal passende jar-filer placeres, for miljøer som benytter Luna HSM.
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/wildfly8/standalone/configuration/log4j-sts.xml. 1 Der findes 3 overordnede log-emner:
TIMING; heri logges timing information, som nedbryder responstiden i de enkelt operationer. Denne funktion kan slåes fra.
AUDIT; heri logges request og respose. Denne log indeholder hele requestet, hvori også certifikatet kan findes.
ø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.
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/interface.xml
• sts/seal.xml
• sts/services.xml
• sts/timers.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:
Signerings certifikatet (STS’ens certifikat) skal ændres til produktions certifikatet - alternativt skal LUNA opsætning justeres.
CVR-RID konfigurationen skal tilpasses til produktionsmiljøer; der skal ikke længere refereres til PP test.
I seal.xml:sosiFederation skal SOSITestFederation ændres til SOSIFederation.
Adresser på eksterne endpoints skal tilrettes.
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.
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).
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.
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.