Introduktion

Formålet med design- og arkitekturbeskrivelse er at beskrive SOSI STS implementationen. Detaljeringsgraden henvender sig til læseren der har behov for en overordnet introduktion til implementationen.

Det forudsættes at læseren har forudgående kendskab til STS'ens rolle - specifikt i relation til ”Den Gode Web Service” (DGWS) og de standarder den baserer sig på.

Security Token Service (STS) er en fælles komponent, som kan udstede adgangsgivende billetter på baggrund af OCES-certifikater. En sådan komponent betegnes generelt som en "Identitetsservice" eller IdP (IdentityProvider).

På NSP anvendes id-kort som single sign-on mekanisme til at autentificere anvendere op mod platformens services. STS'en tilbyder billetomveksling for at lette integration mellem disse, så anvendere nemt kan kalde services på tværs af NSP og andre systemer. 

Arkitekturoverblik

STS består af en række del-komponenter (eller services), som konfigureres via Spring-frameworket. Komponenterne indkapsler følgende funktionalitet:

• Crl: Spærreliste kontrol af OCES certifikater
• Acl: Check for adgang til udstedelse ID-kort (benyttes ikke pt)
• Cpr: CPR opslag ud fra OCES-medarbejdercertifikat eller borgercertifikat
• Authorization: Verifikation af autorisation id ud fra CPR Fuldmagt og den fællesoffentlige fuldmagtsløsning.

En væsentlig komponent for STS er SOSI Seal biblioteket, der indtager en central rolle i forbindelse med udstedelse af ID-kortet. Seal anvendes som et tredjeparts bibliotek af STS.

Figur 1: Komponenter anvendt af STS (ikke udtømmende liste)

Adgang til NSP-komponenters services er begrænset med autentificering. Denne autentifikation er baseret på OCES-certifikater, hvormed anvendere er i stand til at identificere sig. Det betyder dog ikke at alle services skal validere alle anvenderes certifikater og tilhørende information. Dette vil være et stort ansvar at fordele på så mange komponenter. Derfor er STS en fælles komponent, som kan udstede adgangsgivende billetter, som kun kræver simpel verifikation i NSP-komponenterne. 

Dette betyder at en anvender udelukkende skal identificere sig overfor STS med sit OCES-certifikat og får herefter et id-kort, der er underskrevet med (STS) føderationens certifikat. Dette id-kort agerer som nøglen, der identificerer anvenderen, og kan give adgang til de andre komponenter på NSP. Komponenternes ansvar er derfor kun at kende til STS'ens ene certifikat og verificere dette i id-kortet. STS verificerer og beriger desuden id-kortet med en række af attributter. F.eks. verificeres slutbrugerens personnummer og dennes autorisation.

Oversigt over snitflader og adgang

STS afhænger af en række eksterne komponenter i forbindelse med udstedelse af og omveksling af billetter. Afhængigheder i parantes anvendes kun i visse scenarier: 

* Hver kasse i ovenstående diagram har en kort forklaring, som kommer frem i et nyt browservindue, når der klikkes på kassen.

Anvenderes tilgang til STS vil ofte være med hjælp fra Seal.Java eller Seal.NET, som er biblioteker der bl.a. hjælper til med at understøtte brugen af DGWS og håndtere sikkerhedsaspekterne.

STS kræver ingen whitelisting og ingen specifikke WSDL'er eksisterer for STS'ens services.

Komponentinteraktion id-kort udstedelse

Komponenterne anvendes f.eks.  af STS ved udstedelsen af ID-kort. Sekvensdiagrammet i Figur 3 viser et typisk forløb med anvendelse af komponenterne, som STS gennemløber i forbindelse med udstedelse af MOCES signeret ID-kort, hvor resultatet er en succesfuld udstedelse af et STS signeret ID-kort.

Figur 3: STS-udstedelse af MOCES signeret ID-kort

Andre scenarier gennemløber en delmængde af de komponentinteraktioner der er illustreret i figuren. Således består udstedelsen
af skridtene:

1. Deserialisering web service request og verifikation af signatur
2. Check af ID-kort, f.eks. version og autentifikationsniveau
3. Spærrelistecheck af signerende og STS-certifikat
4. Check af certifikat til CPR-tilknytning
5. Check af autorisation knyttet til CPR
6. Signering af ID-kort med STS-certifikat
7. Serialisering af web service response

Skridt 5 og 6 foretages kun, såfremt ID-kortet er signeret med et MOCES-certifikat. Alle verifikationsskridtene kan afbryde forløbet, hvilket resulterer i, at et fejlsvar med passende information returneres til kalderen.

Diagrammerne nedenfor viser nærmere detaljer angpende henholdsvis validering af signatur, samt medarbejder validering

Figur 4: Validering af XML signatur

Figur 5: Validering af medarbejder information

Komponent interaktion omveksling fra OIOSaml assertion til id-kort

Snitflader

Figur 2: STS-afhængigheder og eksterne snitflader

• NewSecurityTokenService -- Udstedelse af STS-signeret id-kort. Erstatter samtidig NameId til et kanonisk format (nødvendigt hvis id-kortet skal veksles til OIOSaml). SOSI Seal biblioteket benyttes af STS til serialisering/deserialisering af web service kaldet samt signering af udstedte ID-kort.
• SecurityTokenService -- Legacy udgave af ovennævnte service (uden erstatning af NameId). Benyt NewSecurityTokenService hvis muligt.
• Sosi2OIOSaml -- Ombytter STS-signeret id-kort fra SOSI ID-kort til OIOSAML assertion rettet mod et specifikt audience, f.eks. sundhed.dk. Bemærk at dette id-kort skal være udstedt af NewSecurityTokenService.
• OIOSaml2Sosi -- Ombytter OIOSaml token til signeret id-kort. Token skal være signeret af troværdig tredjepart.
• Bst2Idws -- Ombytter OIOSaml bootstrap token til signeret identitytoken rettet mod et givet audience, f.eks. FMK. Token skal være signeret af troværdig tredjepart.
• JWT2Idws -- Ombytter JSON Web token til signeret identity-token rettet mod et givet audience, f.eks. FMK. Token skal være signeret af troværdig tredjepart (pt. en OID connector).

Komponentsnitflader

Figur 6: Komponent-interfaces i STS

OcesCrlService

Check af OCES-spærrelistecheck:

• isRevoked: Checker om et X509-certifikat er spærret
• getCrlTimestamp: Returnerer tidsstemplet for den underliggende spærreliste

Sker op mod en lokal kopi af revokationslister, vedligeholdt af NSP-platformen.

OcesCvrRidService

Validering eller opslag af CPR-nummer ud fra et MOCES certifikats ”subject serial number” (SSN), hvor den relevante service
afgøres udfra certifikatets issuer, f.eks. OCES1 vs OCES2:

• isRelated: Afgør om SSN og CPR-nummer hører sammen
• findRelatedCpr: Slår tilhørende CPR-nummer op ud fra SSN

OcesUUID2CPRService

Validering eller opslag af CPR-nummer ud fra et MOCES certifikats ”subject serial number” (mere specifikt medarbejder uuid'et):

• isRelated: Afgør om UUID og CPR-nummer hører sammen
• findRelatedCpr: Slår tilhørende CPR-nummer op ud fra UUID

OcesPidService

Validering af CPR-nummer ud fra et POCES-certifikats ”subject serial number” (SSN):

• isRelated: Afgør om SSN og CPR-nummer hører sammen

ProcurationService

Hentning af fuldmagter fra fuldmagtsservicen. Validering af CPR-nummer ud fra en borgers CPR-nummer:

• getProcurationPrivileges: Henter listen af privilegier udstedt til den aktuelle bruger (borger) fra en anden borger.
  
  

AuthorizationService

Verificerer og beriger ID-kort med autorisation ID udfra CPR-nummer:

• getAuthorizations: Finder autorisationer tilknyttet et CPR-nummer

Sker op mod en lokal kopi af autorisationsregisteret, vedligeholdt af NSP-platformen.

Datamodel

STS-anvendelse af database begrænser sig primært til læsning af konfigurationsdata og persistering af cachede værdier til (se Figur 5), og består af følgende tabeller:

• • Skema	Tabel	Beskrivelse	Benyttes pt
    STS (backoffice)	iboConfig	indeholder audience specifik konfiguration for SOSI ID-kort til OIOSAML omveksling	Ja
    STS (backoffice)	audienceConfiguration	indeholder konfiguration vedrørende billetomveksling fra bootstrap token til IDWS token og fra JWT token til OIOSaml token	Ja
    STS (backoffice)	roleDefinitions	Indeholder opsætning af gyldige nationale roller, og hvorledes disse repræsenteres i id-kort og i SEB	Ja
    STS (backoffice)	authorizationDefinitions	Indeholder valide uddannelseskoder. Primært 4 cifre, men kan også indeholde bogstaver.	Ja
    STS (backoffice)	trustedCvr	Indeholder en liste af CVR numre, der kan angive nationale roller uden at få disse valideret.	Ja
    STS (lokal)	cprcache	indeholder relationer mellem certifikat og CPR-nummer. Anvendes hvis deploymiljøet er godkendt til opbevaring af relationen i klartekst (Nødvendig hvis ikke CPR web servicen altid skal kaldes med manglende CPR i ID-kort).	Ja
    STS (lokal)	cprhash	indeholder et hash af mapningen mellem certifikat og CPR-nummer. Oprindeligt tænkt anvendt hvis relationerne ikke ønskes opbevaret som klartekst. Ikke længere muligt, idet der er behov for at kunne tilføje cpr nummer til et id-kort uden dette er angivet i input.	Nej
    STS (lokal)	whitelist	indeholder information (CVR-nummer og system navn), der anvendes til at at give systemer adgang til udstedelse af ID-kort. Benyttes ikke længere.	Nej
    STS (lokal)	blacklist	indeholder information (X509 certifikat subject serial number), der anvendes til at blokere for udstedelse af ID-kort for specifikke certifikater.	Nej
    SDM	autreg	Indeholder aktuelle autorisationskoder for autoriserede sundhedsfaglige medarbejdere. Vedligeholdes af Autorisations importeren	Ja
    SDM	nationalRoles	Indeholder roller importerede fra SEB	Ja
    CRA	crl	Indeholder et antal spærrelister incl. metadata omkring seneste hentning af disse	Ja
    CRA	revoked	Indeholder replika af en given spærreliste indeholdende aktuelt revokerede certifikater Hvis en CRL er udstedt af en CA og denne CA trækkes tilbage, så vil alle dens rækker i revoked blive slettet og en enkelt række med NULL i serialnumber vil blive oprettet. Et certifikat skal derfor betragtes som trukket tilbage hvis dets CRL enpoint findes i crl og dets serienummer findes i revoked eller der findes en række med serienummeret NULL.	Ja

    
    

    Databasemodellen er simpel og indeholder ingen bindinger til specifikke databaser. Tabellerne cprhash og cprcache fungerer som en simpel cache for CPR-opslag, og repopuleres automatisk, hvorfor rækkerne kan slettes efter behov.

* Hver kasse i ovenstående diagram har en kort forklaring, som kommer frem i et nyt browservindue, når der klikkes på kassen.

Entitetsindhold

audienceConfiguration

DB: sts_audconf

Indeholder konfiguration af borger-billetomveksling med angivelse af audiences, og adgang til disse. Bruges også til at sætte sløring (kald til IDSAS) for et givet audience.

Objektet indeholder informationen:
--------------------------------------
audience
attribute
attribute_value

authorizationDefinitions

DB: sts_audconf

Objektet indeholder informationen:
--------------------------------------
role

cprcache

DB: sts

cprcache fungerer som en simpel cache for CPR-opslag, og repopuleres automatisk, hvorfor rækkerne kan slettes efter behov.

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

iboConfig

DB: sts_audconf

Indeholder konfiguration af (Medarbejder) billet omveksling fra id-kort til OIOSaml token (sikker browseropstart)

Objektet indeholder informationen:
--------------------------------------
audience
publicKey
recipientURL
includeBST
deliveryNotOnOrAfterOffset
notBeforeOffset
notOnOrAfterOffset
idCardMaxAgeMins

trustedCvr

DB: sts_audconf

Objektet indeholder informationen:
--------------------------------------
cvr
endpoint

NSP Keystore (Luna box)

Indeholder certifikat og nøgler for føderationen, samt trustede 3. parter der kan foretages billetomveksling fra.

Placeret i dedikeret LUNA boks for maximim sikkerhed

roleDefinitions

Indeholder opsætning af gyldige nationale roller, og hvorledes disse repræsenteres i id-kort og i SEB (Sundhedsvæsenets Elektroniske Brugerstyring)

DB: sts_audconf

Objektet indeholder informationen:
--------------------------------------
source -- Hvem har udstedt rollen, ex: 'NationalFederation'
externalName -- rollenavn, ex: 'nspSundAssistR1'
code -- rolle kode, ex: '41001'
value -- rolle navn, ex: 'SundAssistR1'

Tabelbeskrivelser

Tabel: audienceConfiguration

DB: sts_audconf

CREATE TABLE audienceConfiguration (
audience VARCHAR(255) NOT NULL,
attribute VARCHAR(128) NOT NULL,
attribute_value VARCHAR(4095));
CREATE UNIQUE INDEX audienceConfiguration_uniq ON audienceConfiguration (audience, attribute);

Tabel: authorizationDefinitions

-- new table to hold authorizationDefinitions

USE sts_audconf;
CREATE TABLE authorizationDefinitions (
role VARCHAR(4) NOT NULL)
ENGINE=InnoDB DEFAULT CHARSET=utf8;

Tabel: cprcache

CREATE TABLE cprcache (
ssn VARCHAR(64) NOT NULL,
cpr VARCHAR(16) NOT NULL,
createdDate datetime);
CREATE UNIQUE INDEX cprcache_ssn ON cprcache (ssn);

Tabel: iboConfig

DB: sts_audconf

CREATE TABLE iboConfig (
audience VARCHAR(255) NOT NULL,
publicKey TEXT NOT NULL,
recipientURL VARCHAR(255) NOT NULL,
includeBST BOOL NOT NULL,
deliveryNotOnOrAfterOffset BIGINT NOT NULL,
notBeforeOffset BIGINT NOT NULL,
notOnOrAfterOffset BIGINT NOT NULL,
idCardMaxAgeMins BIGINT,
KEY audience (audience)

Tabel: trustedCvr

-- new table to hold trustedCvr for national roles
USE sts_audconf;

CREATE TABLE trustedCvr (
cvr VARCHAR(8) NOT NULL,
endpoint VARCHAR(64) NOT NULL,

roleValue VARCHAR(64)) ENGINE=InnoDB DEFAULT CHARSET=utf8;

create unique index trustedCvr_uniq on trustedCvr (cvr, endpoint);

Tabel: roleDefinitions

-- new table to hold roleDefinitions for national roles
USE sts_audconf;

DROP TABLE IF EXISTS roleDefinitions;
CREATE TABLE roleDefinitions (
source VARCHAR(255) NOT NULL,
externalName VARCHAR(255) NOT NULL,
code VARCHAR(255) NOT NULL,
value VARCHAR(255)) ENGINE=InnoDB DEFAULT CHARSET=utf8;

GRANT ALL ON sts_audconf.roleDefinitions TO 'sts'@'%';

Sløring af sundhedsfaglige - IDSAS

STS'en kalder IDSAS for at finde ud af, om en given sundhedsfaglig ønsker at blive sløret over for et givet CPR-NR. Der er lavet en integration til IDSAS i STS'en, som laver et internt SOAP-kald til IDSAS, for at hente evt. aktive sløringer.

Disse sløringer sættes på billetten som STS returnerer. 

Sløring sker kun for de audiences som sløring er konfigureret for.

STS Deployment

STS-applikationen er en JEE web applikation, som afvikles i driftsmiljøerne som en docker container. Containeren afvikles med en række konfigurationsfiler mounted ind i containeren, disse bestemmer STS runtime egenskaber, herunder føderation (test eller produktion), eksterne services og konfiguration af logning.

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.

For nærmere detaljer omkring konfigurations- og deploymentmuligheder henvises til installationsvejledningen [R2].

Referencer

[R0] Kravspecifikation Identitetsservice (version 1.3, 20. April 2006), Ribe Amt
[R1] The SOSI Library Programmers Guide, (version 2.1, 4. Februar 2013), Lakeside
[R2] STS Installationsvejledning (version 0.1?, ??. Februar 2013), Arosii
[R3] Den Gode Webservice (version 1.1, 1. Juli 2008), MedCom