Denne "Kom Godt i Gang Guide" omhandler billetomveksling i STS-komponenten. Guiden er beregnet til it-faglige personer som skal til eller er i gang med at udvikle systemer, der skal integrere med STS-komponenten på platformen. Det anbefales at Platformsintroduktion og STS - signering læses inden denne guide.
BilletomvekslingPå 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. Fælles offentlig brugerstyringFæ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. Adgang til NemLog-in føderationenNå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. Sikker browseropstartEt 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. Indhold af et NemLog-in tokenEt 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:
Attributter i et NemLog-In tokenEt 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:
For assertions udstedt på baggrund af OCES-certifikater er yderligere en række attributter obligatoriske:
OIO-SAML beskriver yderligere nogle relevante attributter, som ikke er obligatoriske:
Adgang til webservices på baggrund af NemLog-In tokenI 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. SOSI Id-kortI 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:
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. Omveksling fra NemLog-In token til id-kortSTS 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:
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. Validering af signaturerSTS'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. Håndtering af CPR-nummerBrugerens 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. Håndtering af autorisationsnummer og uddannelseskodeHvis 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:
Det er den samme algoritme, der anvendes ved signering. Eksempel på anvendelseEn 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. 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:
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. 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:
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. Anvendelse af billetomvekslingBilletomveksling 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:
Hele processen kræver således gensidigt kendskab og aftale mellem STS og den eksterne webapplikation XYX, idet
Eksempel på anvendelseEn 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. EksemplerTil 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: 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. TestdataI 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. Medarbejdercertifikater
Funktionscertifikater
Øvrige certifikater
OIOSAMLToIDCardExample.javaEksemplerne 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. IDcardToOIOSAMLExample.javaEksemplerne 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. |