Dokumenthistorik

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