1. Billetomveksling

På den nationale service platform (NSP) anvendes id-kort som single sign-on mekanisme til at autentificere anvendere op mod platformens services. I andre sammenhænge som f.eks. på sundhed.dk eller borger.dk anvendes den fælles offentlig brugerstyring (Nem-Login). STS'en tilbyder billetomveksling for at lette integration mellem disse, så anvendere nemt kan kalde services på tværs af NSP og andre systemer.

2. Fælles offentlig brugerstyring

Fællesoffentlig brugerstyring skal gøre det digitale Danmark mere sikkert, mindske investeringerne i infrastruktur for offentlige myndigheder og skabe bedre service for borgerne. Dette sker ved at lade en række webapplikationer og webservices indgå i en fælles føderation (sikkerhedskontekst).

Brugeren autentificeres ved anvendelse af NemLog-in og får hermed adgang til alle applikationer og services inden for NemLog-in føderationen (Single sign-on). Autentifikation med NemLog-In kan enten være baseret på NemId (papkort) eller anvendelse af digital signatur (OCES-certifikater).

NemLog-In er leveret af NNIT og har Digitaliseringsstyrelsen som operatør og CSC som driftsleverandør.

En oversigt over relevante materialer findes på http://www.digst.dk/Loesninger-og-infrastruktur/NemLogin/Det-nye-nemlogin. En kort intro til NemLog-In kan ses under http://www.digst.dk/Loesninger-og-infrastruktur/NemLogin/Det-nye-nemlogin.

3. Adgang til NemLog-in føderationen

Når en uidentificeret bruger tilgår en webapplikation, der indgår i NemLog-In føderationen, foretages autentifikation ikke af webapplikationen selv, men derimod med anvendelse af NemLog-In som Identity Provider (IdP).

Brugeren videredirigeres til IdP'en i form at et autentifikationsrequest. IdP'en efterspørger om nødvendigt credentials fra brugeren (i form af digitalt certifikat eller papkort) og dirigerer herefter brugeren tilbage til webapplikationen med et krypteret token.

Det krypterede NemLog-in token er altid målrettet en given webapplikation. Det er signeret af NemLog-in og krypteret med webapplikationens offentlige nøgle og kan derfor kun anvendes af denne applikation. Dekryptering åbner op for at aflæse de indeholdte informationer omkring brugerens identitet.

Applikationen har tillid til NemLog-in (trust) og kan derfor stole på de oplysninger dette token indeholder.

Undervejs etableres en browser-session med NemLog-In IdP'en, som gør det muligt at undgå gentagen afgivelse af credentials ved tilgang til en anden webapplikation indenfor føderationen (Single sign-on). Samme session mellem bruger og IdP kan således give adgang til flere webapplikationer - ved at føde et NemLog-In token for hver applikation.

3.1. Sikker browseropstart

Et krav til webapplikationer er at de skal understøtte modtagelse af tokens, som ikke direkte er efterspurgt af applikationen selv. Dette kan anvendes til sikker browseropstart af applikationen. Applikationen modtager et token initieret af et eksternt system og ikke som svar på et autentifikationsrequest, og etablerer herefter en lokal session på baggrund af det modtagne token.

4. Indhold af et NemLog-in token

Et NemLog-In token er et eksempel på en OIO-SAML assertion. OIO-SAML er en dansk profilering af den internationale SAML 2.0 standard. Dvs. man har taget standarden og skræddersyet den til danske forhold - herunder f.eks. hvordan cpr- og cvr-numre kan anvendes til at identificere personer og virksomheder.

Endvidere findes en OCES subprofil, som beskriver andre relevante ting f.eks. at en OIO-SAML assertion er udstedt på baggrund af et OCES-certifikat. Indholdet er beskrevet i OIO-SAML-Profil.

Den udstedte OIO-SAML assertion er møntet på et enkelt audience (system) - ved kryptering sikres det, at det kun kan anvendes af det tilsigtede system. Dette token kan derfor betragtes som en "personlig billet" der giver en bruger adgang til et givet system.

En OIO-SAML assertion (og dermed et NemLog-In token) udstedt på baggrund af OCES-certifikat indeholder følgende elementer:

• Issuer. Den IdP (typisk NemLog-In) der har udstedt token.
• Signature. Udsteders digitale signatur af det samlede token. Signaturen kan verificeres med udsteders offentlige nøgle.
• Subject. Anvenders identitet. Ved udstedelse på baggrund af OCES-certifikat skal dette være certifikatets Distinguished Name.
• Conditions. Beskriver gyldighed af token, herunder tidsperiode samt hvilket audience (aftagersystem) dette token er rettet mod. Token er krypteret med offentlig nøgle for aftagersystemet.
• AuthnStatement. Beskriver hvordan anvenders identitet er bekræftet. I nærværende sammenhæng altid via X.509 (OCES) certifikat.
• AttributeStatement. Indeholder et antal attributter (udsagn) omkring brugeren f.eks. navn, email og organisatoriske tilhørsforhold. Beskrevet nærmere nedenfor.

4.1. Attributter i et NemLog-In token

Et token indeholder en række attributter, hvoraf nogle er obligatorisk for alle OIO-SAML assertions, mens andre kun er relevante, hvis de er udstedt på baggrund af OCES-certifikater (som ifm. billetomveksling).

Attributter som er obligariske for alle OIO-SAML assertions:

• oid:2.5.4.4 (surName). Brugerens efternavn.
• oid:2.5.4.3 (commonname). Brugerens fulde navn.
• oid:0.9.2342.19200300.100.1.1 (uid). Beskriver brugerens id i context af hans organisation. For assertions udstedt på baggrund af OCES-certifikater skal dette være certifikatets subjectSerialNumber (CVR-RID).
• oid:0.9.2342.19200300.100.1.3 (email). Brugerens email-adresse.
• AssuranceLevel. Angiver pålidelighed af data i henhold til Vejledning vedrørende niveauer af autenticitetssikring, typisk 3 eller 4.
• SpecVer. Beskriver OIO-SAML version, pt. DK-SAML-2.0

For assertions udstedt på baggrund af OCES-certifikater er yderligere en række attributter obligatoriske:

• oid:2.5.4.5 (serialNumber). Serienummer på brugerens OCES-certifikat.
• oid:2.5.29.29 (certifikat udsteder). Udsteder af certifikatet. Enten rodcertifikatet eller et underliggende krydscertifikat. Sammen med serienummer identificerer dette certifikatet unikt.
• oid:2.5.4.10 (organizationName). Brugerens organisation. Obligatorisk ved VOCES/MOCES certifikat.
• IsYouthCer. Angivelse af om det er et særligt ungdomscertifikat udstedt til personer i alderen 15-18 år, som kan identificere brugeren men ikke anvendes til juridisk bindende aftaler.
• CvrNumberIdentifier. CVR-nummer for brugerens organisation. Obligatorisk ved MOCES/VOCES certifikat.
• RidNumberIdentifier. Obligatorisk ved MOCES-certifikat og hentet herfra.

OIO-SAML beskriver yderligere nogle relevante attributter, som ikke er obligatoriske:

• oid:1.3.6.1.4.1.1466.115.121.1.8 (userCertificate). Det certifikat der er baggrund for udstedelse af token. Optionelt, men er indeholdt i NemLog-In tokens og kræves af STS billetomveksling.
• CprNumberIdentifier. Brugerens CPR-nummer. Optionelt og kun tilladt under visse omstændigheder (bl.a. at aftager skal være en offentlig instans).

4.2. Adgang til webservices på baggrund af NemLog-In token

I en senere fase vil NemLog-In udover data for brugeren også levere et såkaldt OIO bootstrap token (ligeledes signeret af NemLog-In IdP'en) som via en service (STS) i NemLog-In kan veksles til en identitetstoken (adgangsbillet) til en webservice indenfor NemLog-In føderationen.

Bemærk, at der her er tale om en Security Token Service (STS) i NemLog-In føderationen, i modsætning til STS'en i NSP-føderationen, der er emnet for den øvrige del af nærværende dokument.

Scenarier for anvendelse af identitetsbaserede webservices er beskrevet i OIO Identity-Based Web Services Scenarios.

5. SOSI Id-kort

I modsætning til de generelle OIO-SAML assertions udstedt af NemLog-In, er et SOSI id-kort skræddersyet til anvendelse i fagsystemer indenfor sundhedsvæsenet. Der er nogle væsentlige forskelle mellem SOSI id-kort og OIO-SAML tokens:

• Det samme SOSI id-kort kan være adgangsgivende til flere services fra flere kaldende it-systemer, hvorimod en OIO-SAML assertion kun kan anvendes til et enkelt modtagende system.
• Et SOSI id-kort indeholder typisk enkelte sundhedsspecifikke attributter som f.eks. et autorisationsnummer, der kan anvendes af modtagende it-systemer.
• Et SOSI id-kort anvendes til at tilgå webservices mens en OIO-SAML assertion anvendes af webapplikationer (men kan indeholde et bootstrap token der kan veksles til adgangsbilletter til webservices).
• Et SOSI id-kort er et eksempel på en SAML assertion men opfylder ikke betingelserne i henhold til OIO-SAML profilen, og er derfor ikke en OIO-SAML assertion.

STS billetomveksling kan anvendes til at veksle mellem de to slags tokens. Det muliggør at autentifikation (udstedelse af id-kort) overfor STS'en kan omveksles til adgang til systemer indenfor NemLog-In føderationen som f.eks. sundhed.dk.

6. Omveksling fra NemLog-In token til id-kort

STS kan anvendes til omveksling af særlige OIO-SAML assertions til et ækvivalent id-kort der kan anvendes til at få adgang til NSP-platformen. Visse oplysninger fremgår af et SOSI id-kort men ikke af et NemLog-In token. Disse skal derfor angives eksplicit i forespørgslen som supplerende information, i det omfang de ikke automatisk kan fastlægges.

Omveksling kræver:

• Det skal være en OIO-SAML assertion udstedt og signeret af en IdP som STS'en stoler på. Dette betyder i praksis NemLog-In.
• Det skal være et OIO-SAML token udstedt på baggrund af et MOCES-certifikat.
• Det skal have AssuranceLevel 3 eller 4 (opfyldt for tokens udstedt på baggrund af OCES-certifikat).
• Medarbejderens CPR-nummer skal enten være angivet i forespørgslen eller kunne bestemmes ud fra certifikatet.
• Autorisationsnummer og uddannelseskode skal enten være angivet i forespørgslen eller kunne bestemmes entydigt (ud fra CPR-nummer og autorisationsregister).
• It-system-navn skal være angivet i forespørgslen da dette ikke indgår i et NemLog-In token.

Herudover kan man vælge at medsende brugerens fornavn/efternavn i forespørgslen, idet fornavnet ikke kan bestemmes ud fra en OIO-SAML assertion.

Såfremt omvekslingen går godt, vil slutresultatet være et STS-signeret id-kort med oplysninger sammensat fra NemLog-In token, supplerende info og opslag, som herefter kan benyttes som adgangsbillet til NSP-platformens services.

6.1. Validering af signaturer

STS'en verificerer at forespørgslen er signeret med et gyldigt certifikat (ikke udløbet, ikke spærret), som er udstedt af rodcertifikatet (eller af et af krydscertifikaterne).

STS'en verificerer at den indeholdte OIO-SAML assertion er signeret med et gyldigt certifikat (ikke udløbet, ikke spærret), som er udstedt af rodcertifikatet (eller af et af krydscertifikaterne). Herudover skal det være et certifikat som STS'en stoler på. STS'en er derfor konfigureret med trust af en eller flere kilder. I produktion stoles i skrivende stund alene på NemLog-In.

6.2. Håndtering af CPR-nummer

Brugerens CPR-nummer er valgfrit i en OIO-SAML assertion. Såfremt dette er medsendt, valideres korrektheden ved opslag ud fra det medsendte CvrRid. Alternativt vil det blive fremsøgt. Herved sikres at det returnerede id-kort altid indeholder et CPR-nummer, hvis ægthed er bekræftet.

6.3. Håndtering af autorisationsnummer og uddannelseskode

Hvis brugeren har en autorisation i henhold til autorisationsregisteret, skal denne være beskrevet i et STS-signeret id-kort med autorisationsnummer og uddannelseskode. Disse er ikke indeholdt i en OIO-SAML assertion, men kan være medsendt som supplerende information i billetomvekslingsforespørgslen.

Disse håndteres på følgende måde:

• Hvis både autorisationsnummer og uddannelseskode er medsendt, verificeres disse via autorisationsregisteret og indsættes i det returnerede id-kort.
• Hvis enten autorisationsnummer eller uddannelseskode er medsendt, verificeres at dette matcher præcis én autorisation i autorisationsregisteret, og denne indsættes i det returnerede id-kort.
• Hvis hverken autorisationsnummer eller uddannelseskode er medsendt, verificeres at brugeren har præcis én autorisation i autorisationsregisteret, og denne indsættes i det returnerede id-kort.

Det er den samme algoritme, der anvendes ved signering.

6.4. Eksempel på anvendelse

En sygeplejerske er i færd med at anvende fmk-online.dk. Hun loggede på fmk-online.dk ved hjælp af NemLog-In. I forbindelse med login modtog fmk-online.dk et NemLog-In token (OIO-SAML assertion). Undervejs i arbejdet har fmk-online.dk behov for at anvende SCES (stamdata enkelt-opslags service) på NSP. Derfor kalder fmk-online.dk STS-billetomveksling og får derved et STS-signeret id-kort, som herefter benyttes til at kalde SCES.

Dette eksempel er tænkt og svarer ikke nødvendigvis til et egentlig brugsmønster på fmk-online.dk.

7. Omveksling fra id-kort til OIO-SAML assertion.

STS tilbyder ligeledes omveksling af id-kort til OIO-SAML assertions rettet mod udvalgte it-systemer. I forespørgslen angives:

• Et gyldigt STS-signeret id-kort niveau 3 eller 4 (dvs. baseret på et MOCES-, VOCES- eller FOCES-certifikat).
• Et audience, dvs. navnet på den webaplikation, som det udstedte token skal gælde for.

Det angivne audience skal være kendt af STS'en. STS'en vil kvittere med en gyldig OIO-SAML assertion signeret af STS og rettet mod den angivne webapplikation. Denne assertion er baseret på oplysningerne i id-kortet, samt suppleret med information som STS er konfigureret med for den givne applikation.

Endvidere krypteres med webapplikationens offentlige nøgle, så token kun kan verificeres og anvendes til denne ene applikation. Det oprindelige id-kort medsendes evt. (afhænger af konfiguration) som en del af den returnerede assertion, så den webapplikation der kaldes har dermed direkte adgang til services på NSP-platformen uden at skulle foretage en omveksling.

Billetomvekslingen kan således anvendes af alle med adgang til NSP. Men kan kun veksle til en assertion som giver adgang til et system kendt og konfigureret i STS.

7.1. Konfiguration af audience i STS.

For at tilgå et tredjepartssystem (f.eks. sundhed.dk) via billetomveksling, skal dette være kendt af og konfigureret i STS. Konfigurationen omfatter:

• navn på audience - benyttes som nøgle og er formatteret som en URI.
• Certifikat for dette audience - benyttes til kryptering af det returnerede token, så kun dette audience kan aflæse informationen.
• recipient - loginUrl hos den webapplikation som det returnerede token skal anvendes på.
• includeBootstrapToken - angivelse af hvorvidt det fremsendte id-kort skal rummes i det returnerede token. Bemærk at en OIO-SAML assertion udstedt af STS ikke kan veksles tilbage til et id-kort. Med inkludering af bootstrap token bliver dette unødvendigt.
• diverse tekniske attributter der benyttes til at beregne hvilken periode den returnerede OIO-SAML assertion vil være gyldig i.

Bemærk, at da det returnerede OIO-SAML token indeholder brugerens CPR-nummer sætter det visse juridiske begrænsninger (persondataloven) for hvilke webapplikationer det er muligt at konfigurere.

Konfigurationen er yderligere beskrevet i STS dokumentationen.

7.2. Anvendelse af billetomveksling

Billetomveksling kan anvendes af et fagsystem (f.eks. et EPJ-system), som allerede har et gyldigt id-kort for den aktuelle bruger, til at integrere med en fremmed webapplikation.

Integrationen foregår på følgende måde:

• Fagsystemet ABC kalder billetomveksling med det STS-signerede id-kort samt angivelse af applikationen XYZ og signerer hele forespørgslen med eget certifikat.
• STS validerer forespørgslens signatur, konstaterer at XYZ er et kendt audience, og returnerer en gyldig OIO-SAML assertion, signeret af STS og krypteret med XYZ's offentlige nøgle.
• ABC åbner en browser på brugerens lokale PC som kalder en adresse (URL) hos fagsystemet.
• Den kaldte adresse (URL) redirigerer herefter til XYZ med OIO-SAML assertion indlejret (typisk som en formular i et HTTP POST request).
• XYZ dekrypterer assertion med egen private nøgle.
• XYZ verificerer at OIO-SAML assertion er signeret af en troværdig IdP og betragter herved brugeren som autentificeret.

Hele processen kræver således gensidigt kendskab og aftale mellem STS og den eksterne webapplikation XYX, idet

1. STS skal kende den eksterne applikation og være konfigureret med bl.a. dennes offentlige nøgle
2. XYZ skal kende til STS'en som en troværdig IdP og dermed stole på assertions signeret af STS.

7.3. Eksempel på anvendelse

En læge på et sygehus arbejder lige nu i sygehusets EPJ-system og ønsker at se patientens journal i sundhed.dk. Han beder derfor EPJ-systemet om at få åbnet sundhed.dk.

I EPJ-systemet er han allerede autentificeret og har et id-kort. EPJ-systemet foretager derfor billetomveksling til et OIO-SAML assertion (krypteret med sundhed.dk's nøgle) og åbner en browser på en adresse (engangs-URL) på EPJ-systemets server, som herefter dirigeres til en login-URL på sundhed.dk med medsendelse af den krypterede assertion. sundhed.dk dekrypterer denne og konstaterer at den er signeret af STS og stoler derfor på de indeholdte oplysninger. sundhed.dk betragter derfor brugeren som autentificeret.

8. Eksempler

Til denne guide hører der 2 kodeeksempler der viser hvordan man ved hjælp af Seal.Java kan kalde STS'en og få omvekslet et idkort til en OIO-SAML assertion eller omvendt. Eksemplerne kan hentes via Subversion på følgende addresse:

• https://svn.nspop.dk/public/guides

Eksemplerne er lavet som et Maven projekt med et fælles modul og et modul for hver guide. Eksemplerne til denne guide ligger i modulet STS og hedder IDcardToOIOSAMLExample.java og OIOSAMLToIDCardExample.java. Klasserne er lavet som unittests og kan afvikles direkte i en hvilken som helst IDE der understøtter JUnit 4.

8.1. Testdata

I modulet common ligger et antal Java Keystore filer der hver indeholder et enkelt certifikat. På testmiljøerne er nogle af disse certifikater knyttet til et antal autorisationer således at eksemplerne kan vise forskellige anvendelser af STS'en.

8.1.1. Medarbejdercertifikater

8.1.2. Funktionscertifikater

8.1.3. Øvrige certifikater

8.2. OIOSAMLToIDCardExample.java

Eksemplerne i denne fil anvender nogle af medarbejdercertifikaterne fra modulet common. Hver eksempelmetode sætter først klassens variable op, danner xml'en for en OIOSamlAssertion signeret med den private nøgle i test-trusted-IdP.jks, for derefter at kalde getSTSSignedIdCard(). Denne metode har indlejrede kommentarer der forklarer hvert skridt i processen.

userWithOneSpecificAuthorization

I dette eksempel ombyttes OIO-SAML assertion for en person der kun har en enkelt autorisation. Autorisationsnummeret og uddannelseskoden angives begge og det returnerede idkort har derfor en verificeret autorisation indlejret.

userWithOneAuthorization

I dette eksempel udstedes der idkort til den samme person som i det tidligere eksempel. Forskellen er at her angiver anvenderen ikke hvilken autorisation som idkortet skal indeholde. Fordi personen har en og kun en autorisation vælger STS'en denne og der udstedes et id-kort med en verificeret autorisation. Hvis personen havde haft flere autorisationer ville kaldet fejle da STS'en ikke vil vælge en tilfældig.

Det anbefales altid at anvender udfylder autorisationsnummer og uddannelseskode på id-kortet. Hvis anvenderen ikke har adgang til disse og derfor ønsker at udnytte denne funktionalitet i STS'en skal man være opmærksom på at uddannelseskoden ikke må være null/nil, en tom streng eller 4 cifre.

userWithSeveralAuthorization

Personen i dette eksempel har flere autorisationer og anvenderen angiver derfor hvilken autorisation der skal bruges. Det ombyttede id-kort indeholder derfor den verificerede autorisation.

userWithOneDoctorAuthorization

I dette eksempel udstedes der id-kort til den samme person som i det tidligere eksempel. Forskellen er at her angiver anvenderen ikke nogen autorisationsID og STS vælger derfor den autorisation, som har en matchende uddannelseskode. Dette opslag går kun godt fordi personen kun har en enkelt autorisation med uddannelseskoden for en læge.

userWithNoAuthorization

Dette eksempel viser at det er muligt for anvender at få udstedt et id-kort for en person der ikke har nogen autorisation. Det skal dog bemærkes at nogle services på NSP vil afvise sådan et id-kort da der ikke er en verificeret autorisation i det.

8.3. IDcardToOIOSAMLExample.java

Eksemplerne i denne fil anvender certifikater fra modulet common.

convertIdCardToSamlAssertion

Dette eksempel ombytter et STS-signeret id-kort udstedt på baggrund af en læge med en enkelt autorisation. Id-kortet veksles til en OIO-SAML-assertion rettet mod audience //sundhed.dk og krypteret med en nøgle svarende hertil.

Den private nøgle i audience-certificate.jks anvendes herefter til dekryptering.

Denne metode har indlejrede kommentarer der forklarer hvert skridt i processen.