Introduktion

Formål med dokumentet

Nærværende dokument henvender sig til nuværende og kommende brugere af STS (Secure Token Service).

...

Derudover giver dokumentet et overblik over de af STS understøttede brugsscenarier med udgangspunkt i konkrete eksempler og med links til mere uddybende dokumentation af disse.

Læsevejledning og forudsætninger

Dokumentet henvender sig primært til IT arkitekter, udviklere og forretningskonsulenter med fokus på sikkerhedsinfrastrukturer og applikationssikkerhed i forhold til National Service Platform (NSP).

Det forudsættes at læseren har en forståelse for grundlæggende koncepter og begreber indenfor applikationssikkerhed herunder certifikater (OCES), sikkerhedsprotokoler f.eks. Den Gode Webservice (DGWS), SAML og OIO IDWS og kendskab til sikkerhedsbilletter f.eks. Java JSON Webtokens (JWT), SOSI Idkort og SAML billetter.

Dokumentet vil løbende linke til ekstern dokumentation, hvor dette er relevant.

Hvad er STS?

STS er i dette dokument synonymt med en konkret NSP service - SOSI STS. Men STS kan også opfattes som et koncept: I denne sammenhæng står STS for Security Token Service (se f.eks. https://en.wikipedia.org/wiki/Security_token_service).

...

Det er vigtigt at forstå, at det alene er service-udbyderens ansvar at foretage adgangsstyring i forhold til den udbudte service og de adgangskritierier, som denne kræver. Beslutning om adgang/ikke-adgang træffes altså udelukkende af service-udbyderen. Grundlaget for denne beslutning er sikkerhedsbilletten og dennes indhold (attributter) og service-udbyderens trust til den udstedende Security Token Service.

STS på National Service Platform (NSP)

Der findes i dag en række forretnings- og støtteservices på NSP. Disse services dækker forskellige formål - fra datadeling via Dokumentdelingsservice (DDS)  til logning via MinLog2. 

...

• SOSI Idkort (medarbejder og systemadgang til DGWS beskyttede services)
• OIO IDWS billet (borgerbilletter til f.eks. adgang til OIO IDWS beskyttede services)
• OIO SAML billet (medarbejderbillet eller borgerbillet feks. til sikker browseropstart til løsningerne sundhed.dk eller forløbsplaner.dk)

Anvendelse af STS på NSP

Som beskrevet i afsnittet ovenfor, så skal en potentiel anvender til en NSP service først integrere med STS og autentificere sig overfor denne med henblik på at få udstedt en til formålet passende sikkerhedsbillet.

...

De enkelte beskrivelser vil have links til mere detaljeret dokumentation.

Overblik over STS

I diagrammet nedenfor vises et overblik over STS.

...

De viste services i figuren udenfor er uddybet i tabellen nedenfor.

De enkelte services kan kræve speciel opsætning af STS (f.eks. whitelisting af anvenders CVR nummer). De specifikke krav og opsætninger gennemgåes Anvendere af STS skal sættes op og tilføjes til STS konfiguration, inden de kan begynde at anvende udstedelses- og omvekslingsservices. Anvendere identificeres vha CVR nummer, som er inkluderet i OCES certifikater. Når en anvender autentificerer sig overfor STS vha et OCES certifikat, så konsulterer STS sin konfiguration og tjekker, om det pågældende CVR nummer er konfigureret, og om det f.eks. har adgang til det specificerede intended audience. De specifikke valideringer og regler gennemgåes i afsnitene nedenfor vedr DGWS, medarbejderomvekslinger og borgeromvekslinger.

Som nævnt i de forgående afsnit, så autentificerer anvendere sig overfor STS ved hjælp af OCES certifikater. Alle OCES-certifikater udstedes af Nets DanID der varetager denne opgave for Digitaliseringsstyrelsen. OCES certifikater kan tilbagekaldes (revokeres), hvis f.eks. den private nøgle bliver kompromiteret. Tilbagekaldte certifikater publiceres på revokeringslister (CRL = Certificate Revocation Lists). Revokeringslisterne hentes løbende og opbevares i en database (CRL database på tegningen). Oplysningerne vedrørende revokering tjekkes i forbindelse med kald af STS udstedelses- eller omvekslingsservices. Således kan revokerede/spærrede certifikater ikke anvendes til at få udstedt/vekslet sikkerhedsbilletter.

STS indeholder synkroniseret data fra følgende registre:

• Autorisationsregisteret: Angiver sammenhæng mellem CPR numre på sundhedspersoner samt disses autorisationsid(er). Muliggør berigelse af sikkerhedsbilletter med autorisationsid for sundhedspersoner.
• Nationale roller: STS synkroniserer med faste intervaller de i SEB administrerede roller. Denne synkronisering muliggør berigelse af sikkerhedsbilletter med nationale roller for medarbejdere (med/uden sundhedsfaglig autorisation)

STS har også integration til de tre services PID-CPR, RID-CPR og UUID2CPR udbudt af Nets. Denne integration muliggør verifikation af et påstået (claim) CPR nummers sammenhæng med PID, RID eller UUID. Disse egenskaber er f.eks tilstede i MOCES certifikater og OIO Saml sikkerhedsbilletter udstedt af NemLog-in.

STS indeholder synkroniseret data fra følgende registre:

• Autorisationsregisteret: Angiver sammenhæng mellem CPR numre på sundhedspersoner samt disses autorisationsid(er). Muliggør berigelse af sikkerhedsbilletter med autorisationsid for sundhedspersoner.
• Nationale roller: STS synkroniserer med faste intervaller de i SEB administrerede roller. Denne synkronisering muliggør berigelse af sikkerhedsbilletter med nationale roller for medarbejdere (med/uden sundhedsfaglig autorisation)

STS har også integration til de tre services PID-CPR, RID-CPR og UUID2CPR udbudt af Nets. Denne integration muliggør verifikation af et påstået (claim) CPR nummers sammenhæng med PID, RID eller UUID. Disse egenskaber er f.eks tilstede i OCES certifikater og OIO Saml sikkerhedsbilletter udstedt af SEB. Derudover validerer STS anvendte OCES certifikater. Alle OCES-certifikater udstedes af Nets, der varetager denne opgave for Digitaliseringsstyrelsen. OCES certifikater kan tilbagekaldes (revokeres), hvis f.eks. den private nøgle bliver kompromiteret. Tilbagekaldte certifikater publiceres på revokeringslister (CRL = Certificate Revocation Lists). Revokeringslisterne hentes løbende og opbevares i en database (CRL database på tegningen). Oplysningerne vedrørende revokering tjekkes i forbindelse med kald af STS udstedelses- eller omvekslingsservices. Således kan revokerede/spærrede certifikater ikke anvendes til at få udstedt/vekslet sikkerhedsbilletter.

Digitaliseringsstyrelsens fuldmagtsregister Digitaliseringsstyrelsens fuldmagtsregister giver borgere i Danmark mulighed for at tildele fuldmagt til venner og pårørende til at opnå dataadgang. Borgere kan vedligeholde deres fuldmagtstildelinger via portalen http://borger.dk. I forbindelse med borgerbilletter har STS via fuldmagtsregisteret mulighed for at tjekke claims om fuldmagt, som angives i forbindelse med omveksling af borgerbilletter.

Anvendelseområder

De ovenfor nævnte anvendelsesområder uddybes i følgende afsnit. Hvert område beskrives kort med hensyn til overordnet formål. Dernæst skitseres flowet indenfor det pågældende område. Hver beskrivelse afsluttes med link til uddybende dokumentation.

Anvendelse: DGWS

STS indeholder to services til udstedelse af SOSI Idkort. Det overordnede formål er, at udstede SOSI Idkort der gør det muligt for anvendere at tilgå DGWS services på National Service Platform f.eks. MinSpærring, DRS eller andre Forretningsservices.

...

• System Idkort: Udstedes på vegne af en "anvenderservice". Kravene til autentifikation overfor STS ved udstedelse er certifikater af typen VOCES eller FOCES.
• Bruger Idkort: Udstedes på vegne af en medarbejder (enten med eller uden sundhedsfaglig autorisation). Kravene til autentifikation overfor STS ved udstedelse er certifikater af typen MOCESOCES.

Anvendernes interaktion med STS i forbindelse med udstedelse af SOSI Idkort er fælles i begge tilfælde:

Pilene på tegningen viser følgende flow:

1. Anvendersystemet bygger et SOSI Idkort indeholdende informationer om brugeren/systemet og signerer det med et certifikat (VOCES/FOCES/MOCES certifikat udstedt af CA rodcertifikatet i den fællesoffentlige føderation).

2. SOSI Idkortet sendes i udstedelsesforespørgsel til STS, der validerer signaturen. Ydermere tjekkes det om certifikatet er spærret (revokeret) for anvendelse.

3. Korrektheden af attributterne i anvendersystemets SOSI Idkort verificeres af STS. En del af attributterne i SOSI Idkortet vil kunne valideres op i mod det anvendte certifikat. I tilfældet med Bruger Idkort (signeret med MOCES certifikat) vil en del af attributterne være at betragte som claims. Disse attributter valideres på følgende måde (se i øvrigt overblikket over STS ovenfor):

   1. CPR nummer: RID-CPR servicen hos Nets anvendes til at verificere, om et givent CPR nummer hører sammen med et givent RID i det anvendte MOCES certifikat.

   2. Autorisationsnummer: Til dette formål anvendes STS'ens kopi af autorisationsregisteret til at verificere, at det angivne autorisationsnummer hører sammen med det angivne CPR nummer.

   3. Uddannelseskode: Til dette formål anvendes STS'ens kopi af autorisationsregisteret til at verificere, at den angivne uddannelseskode hører sammen med det angivne CPR nummer.

   4. National rolle: Hvis der er angivet en national rolle, så tjekker STS op i mod sin kopi af stamdata, at den pågældende bruger er i besiddelse af den angivne rolle. Hvis en anvender ikke har angivet en national rolle i claim, men den pågældende medarbejder er i besiddelse af netop én nationale rolle vil denne automatisk inkluderes i det udstedet SOSI Idkort. Der er en whitelist for trustede CVR-organisationer, som selv administrere nationale roller lokalt. For disse trustes den nationale rolle der er claimet - dvs. ingen opslag i stamdata.

   5. Hvis der kaldes med et MOCES certifikat og CVR validering er slået til, så tjekkes at CVR nummeret findes i konfigurationstabellen whitelistedUserIdCardCvr ellers afvises kaldet.
4. STS opbygger et nyt SOSI Idkort med de samme informationer som det SOSI Idkort, der udgjorde forspørgslen fra anvenderen. Dette Idkort signeres med STS'ens eget certifikat.
5. STS sender det nye SOSI Idkort retur til anvendersystemet, der gemmer dette i brugerens/systemets session.
6. Anvendersystemet anvender det nye SOSI Idkort i forespørgelser mod NSP-komponenter. Bemærk at et SOSI Idkort kan anvendes til flere forespørgelser mod flere forskellige services, så længe det endnu ikke er udløbet.
7. NSP-komponenten verificerer at SOSI Idkort er signeret af føderationens certifikat. SOSI STS'ernes certifikater er kendte af alle komponenter i føderationen.

Der henvises til STS - Guide til anvendere: DGWS for yderligere detaljer.

Anvendelse: Medarbejderomveksling

STS indeholder tre services til brug for medarbejderomveksling:

• Omveksling fra Bruger SOSI Idkort til OIO SAML billet
• Omveksling fra OIO SAML billet til Bruger SOSI Idkort
• Omveksling fra OIO fra OIO Saml bootstrap token til Bruger til Bruger SOSI Idkort (en videreudvikling af SOSI sikkerhedsinfrastrukturen så den understøtter MitID, Nemlog-in3 og MitID og OCES3)

Som det blev beskrevet i forgående afsnit er formålet med at anskaffe et Bruger SOSI Idkort at få adgang til en eller flere NSP DGWS Services.

Formålet med at fremskaffe en OIO SAML billet vil typisk være at foretage kald i NemLogin føderationenføderation, som kræver OIO SAML billet. Dette kunne f.eks. være at opnå en "sikker browser opstart" for en sundhedsfaglig bruger til sundhed.dk.

...

Pilene på tegningen viser følgende flow:

1. Anvendersystemet er i besiddelse af en OIO SAML billet eller en OIOSAML-baseret bootstraptoken for en given medarbejder (i praksis udstedt af NemLogin, SEB eller andre af SOSI STS trustede lokale IdP'er/udstedere). Denne sendes i en forespørgsel til STS på omvekslingsendpointet. Der kan være brug for at det udstedte SOSI Idkort er beriget med flere oplysninger, end dem, der er til stede i den af NemLogin udstedte den udstedte OIO SAML billet eller bootstraptoken. Disse specificeres af anvendersystemet i en af dette system defineret SAML billet (i praksis kan denne SAML billet betragtes som en holder for anvendersystemets claims) eller angives som WS Trust claims.
2. STS validerer den indgående billet (den grønne i diagrammet) dvs at den udstedte billet ikke er udløbet, at det er udstedt af en troværdig udsteder (i praksis udstedt af NemLogin, SEB eller andre af SOSI STS trustede lokale IdP'er/udstedere) samt at ingen af de anvendte certfikater i forespørgslen er at finde på de publicerede certifikatspærrelister (CRL). De supplerende oplysninger (claims) defineret af den af anvendersystemet udstedte SAML billet eller medstendte WS Trust claims (den røde i diagrammet) valideres af STS på følgende måde:
   1. Hvis anvendersystemet har definerer et CPR nummer som et claim valideres dette. Det gøres ud fra RID oplysninger i billetten (vha RID-CPR service) hvis de er til stede, ellers ud fra det medsendte medarbejder uuid (vha UUID2CPR service).
   2. Hvis anvendersystemet ikke har defineret et CPR nummer, slås det op med RID-CPR servicen eller UUID2CPR servicen.
   3. Hvis anvendersystemet har claimet en national rolle, så valideres denne.
      1. Hvis BST tokenet har indlejret en liste af nationale roller, valideres i forhold til denne.
      2. Findes rollen ikke i indlejret liste, valideres i forhold til de registrerede stamdata (roller i SEB-registeret).
   4. Hvis anvendersystemet har claimet et autorisationsnummer for medarbejderen, så valideres dette op i mod autorisationsregisteret.
   5. Hvis anvendersystemet hverken har claimet rolle eller autorisation og medarbejderen identificeret i den indkommende billet har netop én autorisation i autorisationsregisteret, vil denne automatisk indsættes i det udstedte SOSI Idkort.
   6. Hvis anvendersystemet hverken har claimet rolle eller autorisation og medarbejderen har netop én national rolle (i enten indlejret liste eller SEB-registeret) og ingen autorisationer, vil denne rolle automatisk indsættes i det udstedte SOSI Idkort.
   7. Hvis anvendersystemet har claimet en lokal (ikke national) rolle, så kopieres denne til det udstedte SOSI Idkort uden yderligere validering.
3. Hvis forespørgslen er i orden danner STS et SOSI Idkort med oplysninger fra hhv OIO SAML billetten og claims og underskriver dette med sit eget certifikat.
4. Det udstedte SOSI Idkort sendes tilbage til anvendersystemet.
5. Anvendersystemet anvender det nye SOSI Idkort i forespørgelser mod NSP-komponenter. Bemærk at et SOSI Idkort kan anvendes til flere forespørgelser mod flere forskellige services, så længe det endnu ikke er udløbet.
6. NSP-komponenten verificerer at SOSI Idkort er signeret af føderationens certifikat. Den offentlige nøgle for STS'ens certifikat er kendt af alle komponenter i føderationen.

...

Der henvises til STS - Guide til anvendere: Medarbejderomvekslinger for yderligere detaljer.

Anvendelse: Borgeromveksling

Der er to typer af borgeromvekslinger:

...

1. Anvendersystemet er i besiddelse af en JWT eller bootstrap token for en borger (i praksis udstedt af NemLogin eller en af en loginbroker, fx den der anvendes i forbindelse med MinLæge app'en). Denne OIO billet sendes i en forespørgsel til STS på omvekslingsendpointet.
2. Der kan være brug for at det udstedte IDWS token er beriget med flere oplysninger, end dem, der er til stede i JWT eller bootstrap tokenet. Disse specificeres af anvendersystemet som claims i forespørgslen. Følgende claims er relevante:
   
   1. CPR nummer for borgeren
   2. CPR nummer for anden borger, hvis billetten skal bruges til at tilgå  andre borgeres oplysninger. Dette kræver, at der er fuldmagt til dette.
3. STS validerer det indgående JWT/bootstrap billet dvs tjecker at den medsendte billet ikke er udløbet, at det er udstedt af en troværdig udsteder samt at ingen af de anvendte certifikater i forespørgslen er at finde på de publicerede certifikatspærrelister (CRL). De supplerende oplysninger (claims) som er defineret af anvendersystemet valideres af STS på følgende måde:
   1. Hvis anvendersystemet definerer et CPR nummer som et claim valideres dette udfra PID (vha CPR-PID service) eller CPR oplysninger i input billetten.
   2. Hvis anvendersystemet har claimet et andet CPR nummer (dvs identiteten på den borger b, som borgeren i pkt a forsøger at tilgå), så vil STS tilgå fuldmagtsregisteret og finde de fuldmagter, der er givet fra borger b til borger a i forhold til det claimede audience. Listen af disse vil være inkluderet i IDWS tokenet, og det er op til den modtagende service at validere disse.
   3. Det er obligatorisk at angive et audience for det IDWS token, som ønskes udstedt. Audience angiver, hvilken service, som man har tiltænkt at bruge tokenet mod. STS validerer det ønskede audience op i mod sin konfiguration (liste af lovlige audiences). For veksling af JWT tokens bliver det tjekket at det indgående token er i besiddelse af nødvendige scopes (en mapning fra JWT scopes til audiences er konfigureret for STS).
4. Det udstedte IDWS token sendes tilbage til anvendersystemet.
5. Anvendersystemet anvender det nye IDWS token i forespørgelser mod NSP-service, som IDWS tokenet er udstedt til. Bemærk at et IDWS token kan anvendes til flere forespørgelser, så længe det endnu ikke er udløbet. Dog er det begrænset, hvilke services det udstedte token kan anvendes til (audience).
6. NSP-komponenten verificerer at IDWS tokenet er signeret af et føderationens certifikat. Familie af føderationscertifikater for SOSI STS er kendt af alle services i føderationen.

Der henvises til STS - Guide til anvendere: Borgeromvekslinger for yderligere detaljer.

Adgang til STS

Når en anvender skal i gang med at bruge STS på NSP skal følgende være på plads:

• Anvenderen skal være i besiddelse af et OCES certifikat (test- hhv produktionsføderationen).
  
  • Der kan findes test OCES certifikater til at komme i gang med her.
  • Anvendere kan desuden kontakte NETS med henblik på at få en tjenesteudbyderaftale, hvilket vil gøre det muligt at få udstedt egne OCES certifikater til både test og produktion.
• Anvenderen skal oprettes som anvender til STS. Dette gøres i praksis ved at rette henvendelse til servicedesk på nspop.dk. Henvendelsen skal indeholde oplysninger om:
  • Det certifikat/de certifikater, som anvenderen ønsker at benytte i forbindelse med brugen af STS.
  • Angivelse af hvilke (hvis nogen) omvekslingsservices, der ønsker benyttet.
  • Ekstra informationer (i forbindelse med de enkelte STS services) inkluderes. Brug tabellen nedenfor.

Anvendelse: eHDSI omveksling

Der findes en enkelt omveksling her:

• Omveksling fra DKNCP Bootstrap token til eHDSI Idws Xua token

Det udstedte eHDSI IDWS XUA token indeholder altid et audience, der angiver, hvordan billetten er tænkt anvendt.

Adgang til STS

Når en anvender skal i gang med at bruge STS på NSP skal følgende være på plads.

De konkrete krav variere fra service til service. Nedenstående tabel viser de krav, der hører til de konkrete snitflader.

Anvenderen skal være i besiddelse af et OCES certifikat (test- hhv produktionsføderationen) til flere af de ovenstående services.

Der kan findes test OCES certifikater til at komme i gang med her.

Anvendere kan desuden kontakte NETS med henblik på at få en tjenesteudbyderaftale, hvilket vil gøre det muligt at få udstedt egne OCES certifikater til både test og produktion. Se feks. https://www.nets.eu/dk-da/kundeservice/nemid-tjenesteudbyder/implementering/Pages/adgang-til-testsystem.aspx

For de services, hvor anvenderen skal konfigureres i SOSI STS (feks whitelisting), skal der rettes henvendelse til servicedesk på nspop.dk.

Henvendelsen skal indeholde oplysninger om:

• • Den service, der ønskes anvendt
  • De informationer, der skal konfigureres. Brug tabellen ovenfor.