i STS Anvenderdokument
ii REVISION HISTORY NUMBER DATE DESCRIPTION NAME 0.4 2014-07 N
iii Indhold 1 Introduktion 1 1.1 Målgruppen...................................................... 1 2 STS 1 2.1 Snitflade........................................................ 1 2.2 Behandlingen af en forespørgsel om signering af ID-kort.............................. 1 2.2.1 Check ID-kort................................................ 2 2.2.2 Check certifikat................................................ 2 2.2.3 Check adgangsliste (ACL).......................................... 2 2.2.4 Check systemoplysninger.......................................... 2 2.2.5 Check brugeroplysninger........................................... 2 2.2.6 Signér ID-kort................................................ 3 3 ITS 3 3.1 Snitflade........................................................ 4 3.2 Behandling af forespørgsel om veksling af ID-kort til OIOIDWS-H token..................... 4 3.2.1 Check om ID-kort er af bruger-type..................................... 4 3.2.2 Check om ID-kort er gyldig i tid....................................... 4 3.2.3 Check om ID-kort er gyldig ifht. audience.................................. 4 3.2.4 Fremstil token................................................ 4 4 Billetomveksling: OIOSAML assertion til ID-kort 4 4.1 Snitflade........................................................ 5 4.2 Behandling af forespørgsel.............................................. 5 4.3 Indhold af en OIOSAML assertion.......................................... 5 5 Billetomveksling: ID-kort til OIOSAML assertion 5 5.1 Snitflade........................................................ 6 5.2 Normalisering af audience.............................................. 6 5.3 Behandling af forespørgsel.............................................. 6 5.4 Konfiguration..................................................... 7 6 Referencer 7 A STS 1.1 til 1.3 migrering 7 B STS 1.3 til 2.0 migrering 8 C STS 2.0 til 2.1 migrering 8
1 / 8 1 Introduktion Nærværende dokument henvender sig til nuværende og kommende anvendere af STS (Security Token Service), ITS (Identity Token Service) samt OIOSAML Billetomveksling og formålet med dokumentet er, at give hjælp til disse i arbejdet med integration mod STS og ITS. Dette sker ved en overordnet gennemgang af de udstillede services og beskrivelse af specifikke elementer, der er væsentlige for at opnå en basal forståelse på anvenderniveau. Gennemgangen kan være understøttet af ekstern dokumentation. STS og relaterede services udstilles som webservices og i produktion altid på sundhedsdatanettet, hvilket kræver separat tilslutning. 1.1 Målgruppen En typisk anvender af STS eller ITS, som kan drage nytte af dette dokument er karakteriseret ved eksempelvis, at være leverandør af et lægepraksissystem eller leverandør af et fagsystem implementeret på et hospital, f.eks. et laboratoriesystem eller et medicineringssystem. ID-kort spiller en central rolle for single-signon scenariet, der understøttes af STS, og det er en absolut nødvendighed med en god forståelse af begreberne for at arbejde med STS. ID-kortet anvendes ifm. autentifikation og autorisation af en bruger, der opererer på sundhedsdatanettet via en serviceaftager. Specifikationen af DGWS [A3] har en god og uddybende beskrivelse af, hvordan et ID-kort er konstrueret og kan anvendes i praksis. 2 STS Formålet med STS er at sikre identiteten af og autorisere brugere der ønsker at tilgå services indenfor en føderation [A1] på sundhedsdatanettet. I dette afsnit beskrives de væsentlige faser, som eksisterer ifbm. behandlingen af en forespørgsel til STS. Undervejs vil de væsentlige begreber og elementer, der indgår i en forespørgsel være forklaret. Der henvises endvidere til yderligere dokumentation, hvor det er relevant, så helheden og meningen fremgår. 2.1 Snitflade Anvenderes tilgang til STS vil ofte være med hjælp fra Seal.Java [A2] eller Seal.NET [A3], som er biblioteker der bl.a. hjælper til med at understøtte brugen af DGWS [A4] og håndtere sikkerhedsaspekterne. Der eksisterer fyldig dokumentation for begge offentliggjorte biblioteker med beskrivelser af anvendelsen af disse. En tredje mulighed er en properitær løsning mod STS, hvor kaldet skal overholde DGWS. Indirekte tilgang er også mulig gennem SOSI-GW [A5], men det dokumenteres ikke her. Et eksempel på hvordan et kald konstrueres med Seal.Java findes i SOSI Programmers Guide ([A2]) under "Use case 1: How to authenticate an ID-card". Afhængig af miljø udstilles tjenesten på: http://<sts-host>:<port>/sts/services/securitytokenservice 2.2 Behandlingen af en forespørgsel om signering af ID-kort Her fokuseres på den forretningmæssige del, så dokumentation af den trivielle husholdning (serialisering m.m.) bag en forespørgsel er udeladt. Sekvensen er følgende: 1. Check ID-kort 2. Check certifikat 3. Check ACL 4. Check systemoplysninger 5. Check brugeroplysninger 6. Signér ID-kort Enhver af disse skridt i sekvensen kan resultere i en fejlsituation, hvorved videre normal processering af forespørgelsen ophører og der svares tilbage til kalder med en fejlbesked. For en mere detaljeret gennemgang af STS fejlsituationer henvises til [A10].
2 / 8 2.2.1 Check ID-kort Forretningslogikken er består af tre skridt, som på baggrund af ID-kortet checker om: 1. ID-kortet er en understøttet version (vha. Seal-biblioteket) 2. ID-kortet er autentifikationsniveau niveau 3 (VOCES/FOCES) eller 4 (MOCES) 3. ID-kortet har korrekt udstedelsestidspunkt og varighed 2.2.2 Check certifikat Anvendelsen af et OCES-certifikat er beskrevet i DGWS [A3]. Denne del af sekvensen handler om, at afgøre om OCEScertifikatet [A6] kan accepteres og om certifikatet er gyldigt i føderationen. I praksis undersøges et X.509 v3 certifikat i følgende trin: 1. Afgør om certifikatet er af typen VOCES/FOCES eller MOCES 2. Afgør om certifikatet er gyldigt på kaldstidspunktet 3. Afgør om certifikatet er af samme type som angivet på ID-kortet 4. Afgør om certifikatet er tilbagetrukket 5. Afgør om certifikatet er gyldigt i føderationen, dvs. udstedt af samme CA 2.2.3 Check adgangsliste (ACL) I praksis anvendes ACL check ikke længere på STS miljøerne, men implementations understøtter to check: whitelist: Har kalder (CVR og systemnavn) adgang til at udstede ID-kort? blacklist: Er kalder (subject serial number) blokeret for at udstede ID-kort? 2.2.4 Check systemoplysninger Dette skridt skal afgøre om CVR nummeret er det samme på ID-kort og OCES-certifikat. 2.2.5 Check brugeroplysninger Udføres kun for MOCES-certifikater. Her afgøres om CVR nummeret, som angivet i MOCES-certifikatet, har en relation til brugerens CPR nummer, som angivet på ID-kortet. I forbindelse med det spørges et, for STS, eksternt system om denne relation eksisterer. I det tilfælde, hvor brugerens CPR nummer på ID-kortet mangler foretages et opslag i det eksterne system udelukkende på baggrund af MOCES-certifikatets oplysninger for at afgøre om en relation eksisterer. Verifikation af CPR Til check af CPR-nummer anvendes DanID s RID-CPR tjeneste, som med subject serial number fra et MOCES certifikat kan slå det tilhørende CPR op. I STS er der to scenarier: a. ID-kort indeholder ikke CPR, hvilket betyder at STS slår CPR op og beriger ID-kortet med det fundne. b. ID-kort indeholder CPR, hvorfor STS slår CPR op og bekræfter at de to matcher. Det antages at subject serial number er på formen CVR:xxxxxxxx-RID-yyyyyyyy hvor xxxxxxxx er det 8-cifrede cvr nummer, mens RID kan indeholde vilkårlige tekststrenge, dog uden mellemrum, plus (+) eller komma (,). Såfremt dette er tilfældet, ignoreres den sidste del. Eksempler:
3 / 8 CVR:12345678-RID-123456 Her er er RID=123456 CVR:12345678-RID-123456-01 Her er er RID=123456-01 CVR:12345678-RID-123456 01 Her er er RID=123456 Et MOCES signeret ID-kort indeholder således altid et verificeret CPR-nummer. Verifikation af autorisation Check af autorisation benytter sig af autorisationsregisteret, og baserer sig på de autorisationsoplysninger der er udfyldt i ID-kortet. Mere specifikt anvendes autorisations- og uddannelseskoden til at finde en matchende autorisation: a. Hvis der ikke findes en matchende autorisation sker en af følgende: 1. Hvis autorisationskoden er angivet i autorisationsoplysningerne og ikke er en tom streng, afvises ID-kort udstedelsen. 2. Hvis uddannelseskoden er angivet i autorisationsoplysningerne og består af fire heltal, afvises ID-kort udstedelsen. 3. Hvis autorisationskoden enten mangler eller er en tom streng og uddannelseskoden enten mangler eller ikke består af fire heltal, fortsættes udstedelsesprocessen. b. Hvis der findes én matchende autorisation beriges ID-kortet med oplysningerne. c. Hvis mere end én autorisation findes afvises udstedelsen da en entydig autorisation ikke kan afgøres. En autorisation i autorisationsregisteret matcher autorisationsoplysningerne på ID-kortet hvis følgende punkter er opfyldt: a. Autorisationskoden på ID-kortet er ikke udfyldt, eller autorisationskoden på ID-kortet er en tom streng, eller autorisationskoden på ID-kortet er den samme som autorisationskoden på autorisationen i autorisationsregisteret. b. Uddannelseskoden på ID-kortet er ikke udfyldt, eller uddannelseskoden på ID-kortet består ikke af fire tal, eller uddannelseskoden på ID-kortet er den samme som uddannelseskoden på autorisationen i autorisationsregisteret. bemærk Gælder kun for STS miljøer hvor adgang til autorisationsregiser er konfigureret. Indtil alle STS miljøer har adgang til autorisationsregister kan service udbydere således ikke forlade sig på at autorisationen i et ID-kort er verificeret af en STS. 2.2.6 Signér ID-kort I det tilfælde, at sekvensen i alle foregående skridt har været fejlfri oprettes nu et svar, som indeholder en kopi af kalderens ID-kort, der signeres med et STS VOCES-certifikat. Dette vil effektivt give gyldighed til ID-kortet i føderationen. 3 ITS Formålet med ITS er at veksle et STS signeret ID-kort til et OIOIDWS-H Identity Token [A7]. Dette token kan efterfølgende anvendes til at opnå adgang til andre systemer i føderationen, hvor et token fungerer som adgangsgiver. Det genererede token bliver typisk anvendt indlejret i en HTTP-URL. Se endvidere [A8]. I dette afsnit beskrives de væsentlige faser der eksisterer ifbm. en forespørgsel til ITS. Undervejs vil de væsentlige begreber og elementer, der indgår i en forespørgsel være forklaret. Der henvises endvidere til yderligere dokumentation, hvor det er relevant, så helheden og meningen fremgår.
4 / 8 3.1 Snitflade Anvenderes tilgang til ITS vil enten være med hjælp fra Seal.Java/Seal.NET eller en properitær løsning forudsat, at kaldet overholder DGWS. En forespørgsel består basalt set af et SOSI ID-kort og et ønsket audience, som bestemmer hvordan det vekslede Identity Token behandles. Et eksempel på hvordan et kald konstrueres med Seal.Java findes i SOSI Programmers Guide ([A2]) under "Use case 5: Request an Identity token from a STS". For Seal.NET anvendere findes der et.net-eksempel på kald af ITS ([A9]). Afhængig af miljø udstilles tjenesten på: http://<sts-host>:<port>/sts/services/identitytokenservice 3.2 Behandling af forespørgsel om veksling af ID-kort til OIOIDWS-H token Her fokuseres igen på den forretningsmæssige side af sagen og den trivielle husholdning er udeladt fra dette dokument. Sekvensen er følgende: 1. Check om ID-kort er af bruger-type 2. Check om ID-kort er gyldig i tid 3. Check om ID-kort er gyldig ifht. audience konfiguration 4. Fremstil token 3.2.1 Check om ID-kort er af bruger-type Dette skridt har det simple formål at afgøre om ID-kortet er af bruger-typen. Denne information fås fra ID-kortet, som er indlejret i forespørgselsen. 3.2.2 Check om ID-kort er gyldig i tid Dette skridt har det simple formål at afgøre om ID-kortet er gyldigt i tid udfra ID-kortets angivne oprettelsesdato og udløbsdato. 3.2.3 Check om ID-kort er gyldig ifht. audience Audience [A6] begrebet dækker over den service, hvortil det aktuelle token skal udstedes. Audience er en logisk adresse på denne service. Det er defineret en række, parametre for et audience som afgør, hvilke egenskaber det aktuelle audience har. Disse parametre er lokale for ITS og vedligeholdes af driftsoperatøren direkte på databasen. Såfremt der findes en audience konfiguration for det aktuelle audience skal dette skridt afgøre om ID-kortet er gyldigt i tid ifht. audience konfigurerede maksimale levetid på et ID-kort. 3.2.4 Fremstil token I det tilfælde at sekvensen i alle foregående skridt har været fejlfri oprettes nu et token vha. Seal.Java, som indlejres i svaret. 4 Billetomveksling: OIOSAML assertion til ID-kort Formålet med omvekslingen er at tillade anvendere af NemLogin at kalde foretage DGWS kald, som kræver SOSI ID-kort, ved at veksle en eksisterende OIOSAML assertion til et ID-kort.
5 / 8 4.1 Snitflade Anvendere vil typisk bruge Seal.Java eller Seal.Net. En forespørgsel består af en OIOSAML assertion og yderligere attributter, der bruges af STS til at skabe ID-kortet. Et eksempel på hvordan et kald til billetomvekslingen konstrueres med Seal.Java findes i SOSI Programmers Guide ([A2]) under "Use case 9: Exchange an OIOSAML assertion to an IDCard at a STS". Afhængig af miljø udstilles tjenesten på: http://<sts-host>:<port>/sts/services/oiosaml2sosi 4.2 Behandling af forespørgsel Omvekslingen validerer det medsendte OIOSAML assertion og tilhørende attributter om i følgende skridt: 1. Validér forespørgslens signatur 2. Validér OISAML assertion (signatur, tid og assurance level) 3. Anvender STS forretningslogik til a. validering af CPR nummer b. validering af autorisation 4. Checker at system navn findes 5. Byg og signér SOSI ID-kort 4.3 Indhold af en OIOSAML assertion OIOSAML er en specialisering af SAML2.0 standarden profileret til danske forhold. Denne samt en subprofil baseret på OCES certifikater er beskrevet i [A11]. Billetomveksling er kun mulig for OIOSAML assertions dannet på baggrund af MOCES certifikater. Bemærk at mandatory betyder at attributten skal være udfyldt for OIOSaml assertions udstedt på baggrund af MOCES, men ikke nødvendigvis for alle OIOSAML assertions. Følgende attributter anvendes af billetomvekslingen: cvr nummer (mandatory): Anvendes til at danne System info i det udstedte id kort. organisationsnavn (mandatory): Anvendes til at danne System info i det udstedte id kort. certifikat (optionel): Hvis tilstede vedhæftes et digest af certifikatet i det udstedte id-kort og SubjectSerialNumber anvendes til opslag/validering af cpr nummer. cpr nummer (optionel): Hvis tilstede valideres det i sammenhæng med SubjectSerialNumber (cvr-rid). commonname (mandatory): Benyttes til id-kortets UserInfo såfremt forespørslen IKKE er vedhæftet fornavn/efternavn. mail (mandatory): Benyttes til id-kortets UserInfo. uid (mandatory): Skal indeholde SubjectSerialNumber (cvr-rid) for det underliggende MOCES certifikat. Benyttes til validering/opslag af cpr nummer, såfremt certifikatet ikke er vedhæftet. 5 Billetomveksling: ID-kort til OIOSAML assertion Formålet med omvekslingen er at tillade anvendere af ID-kort at foretage kald i NemLogin federationen, som kræver OIOSAML assertions, ved at veksle et eksisterende ID-kort til et OIOSAML assertion.
6 / 8 5.1 Snitflade Anvendere vil typisk bruge Seal.Java eller Seal.Net. En forespørgsel består af et ID-kort og yderligere attributter, der bruges af STS til at skabe et assertion. Et eksempel på hvordan et kald til billetomvekslingen konstrueres med Seal.java findes i SOSI Programmers Guide ([A2]) under "Use case 11: Exchange an IDCard to and encrypted OIOSAML assertion at a STS". Afhængig af miljø udstilles tjenesten på: http://<sts-host>:<port>/sts/services/sosi2oiosaml Det skal bemærkes at ikke alle STS signerede ID-kort kan anvendes til omveksling. Signeringen skal foregå via følgende snitflade: http://<sts-host>:<port>/sts/services/newsecuritytokenservice På sigt vil alt funktionalitet i denne flyttes over på den gamle URL. Dette vil kun have betydning for anvendere af den gamle URL, så det anbefaldes at den nye snitflade benyttes i alle sammenhænge. Forskellen mellem de 2 snitflader er at NameID/AlternativeIdentifier vil blive overskrevet i den nye snitflade. Dermed kan anvendere ikke længere bestemme indhold heraf. 5.2 Normalisering af audience Audience (repliesto i forespørgelser) anvendes til at identificere konfigurationen, der bruges under omveksling; krypteringsnøgle og andre parametre vælges herunder. Audience skal tolkes som URI med en normalisering, som beskrives herefter. Denne normalisering bruges ved sammenligninger, dvs. ved opslag af konfiguration. Det er derfor vigtigt at der i forespørgelser anvendes audiences, der kan normaliseres til den rette konfiguration. En general URI ser således ud: <scheme>://<authority><path>?<query>#<fragment> Normaliseringen vil udføre følgende: lower-case af scheme og authority. hvis path blot er /, så vil path delen blive fjernet. query og fragment vil forblive uberørt. Port-angivelse, hvis sådan et findes, ændres heller ikke. Hvis scheme undlades, så vil : (kolon) også blive undladt. 5.3 Behandling af forespørgsel Omvekslingen validerer det medsendte ID-kort og de tilhørende attributter og udfører følgende skridt: 1. Validér forespørgslens signatur samt trust til det benyttede certifikat. Dette kan være slået fra pga. interoperabilitet med SOSI-GW. 2. Validér ID-kort (trust og udløb) 3. Udvælgelses af audience baseret på normalisering (se Afsnit 5.2) 4. Byg af OIOSAML assertion a. Inkludér bootstrap token (ID-kort), hvis dette er konfigureret for fundne audience. b. Signér assertion. c. Kryptér hele svaret med den for audience konfigurerede offentlige nøgle.
7 / 8 5.4 Konfiguration Anvendere af systemet skal være opmærksom på at omvekslede tokens er rettet mod et modtager system, og vil kun kunne bruges hertil. Der afkræves derfor af modtager systemet visse oplysninger til konfiguration; disse er: audience identifikation af modtagersystemet som en URI, der skal være på normalform jvf. tidligere afsnit. publickey den offentlige nøgle som anvendes til kryptering af den omvekslede token. recipienturl den URL hvor modtagersystemet kan nåes på. includebst om ID-kort/bootstrap token skal inkluderes i den svarede assertion. deliverynotonorafteroffset det offset i tid fra omvekslingstidspunktet, der angiver hvornår det udstede må anvendes af modtagersystemet. notbeforeoffset offset i tid fra omvekslingstidspunkt, der bruges til opsætning af gyldighed af udstede assertion. notonorafteroffset offset i tid fra omvekslingstidspunkt, der bruges til opsætning af gyldighed af udstede assertion. 6 Referencer [A1] SOSI Executive Summary - (forklaring af føderationsbegrebet), Lakeside http://www.sosi.dk/twiki/bin/view/projectmanagement/sositechexecutiveoverview [A2] The SOSI Library Programmers Guide (version 2.2.5), Lakeside https://svn.softwareborsen.dk/sosi/tags/release-2.2.5/modules/seal/src/site/- SOSI%20programmers%20guide.doc [A3] Seal.NET (version 1.0), SDSD http://digitaliser.dk/resource/444315/artefact/dgws+seal.net.docx [A4] Den Gode Web Service (version 1.0 og 1.0.1), MedCom http://digitaliser.dk/resource/248311/artefact/dengodewebservice_1.0.pdf [A5] SOSI-GW Subversion repository https://svn.softwareborsen.dk/sosi-gw/ [A6] OCES-certifikatpolitikker (MOCES v4, VOCES v3) https://www.nemid.nu/digital_signatur/oces-standarden/oces-certifikatpolitikker/ [A7] FMKi projektet, Veksling til OIOIDWS-H Identity Tokens, NSI [A8] [A9] [A10] [A11] FMKi projektet, Brugsscenarier for OIODWS-H Identity Tokens, NSI Seal.NET ITS eksempel https://svn.softwareborsen.dk/medcomdgws/trunk/modules/sbo/src/securebrowserlogin.cs STS Fejlsituationer, Arosii A/S OIOSAML, http://digitaliser.dk/resource/2377872/artefact/oio+web+sso+profile+v2+09.pdf A STS 1.1 til 1.3 migrering I forbindelse med opgradering af systemer, der tidligere har været integreret til og fungeret med STS version 1.1, til at benytte STS version 1.3 er en række forhold, som opmærksomheden bør rettes mod: Autorisations-ID: der er indført et check på brugerens autorisations-id og det afgøres om brugerens rolle og autorisationskode, som angivet på ID-kortet, stemmer overens med lige præcis en tilladelse i lokale autorisationsoplysninger, førend brugeren kan godkendes. Fejlkoder og fejlbeskeder ændres i 1.3. Se [A10] for yderligere oplysninger.
8 / 8 Support for whitelisting i STS udgår Introduktion af ITS: den nye service er beskrevet i afsnit 4 Seal.Java opgradering til version 2.1.x B STS 1.3 til 2.0 migrering For eksisterende anvendelser af STS 1.3, bør STS 2.0 ikke kræve ændringer. Introduktion af billetomveksling: den nye service er beskrevet i Afsnit 4 Seal.Java opgradering til version 2.1.5 C STS 2.0 til 2.1 migrering For eksisterende anvendelser af STS 2.0, bør STS 2.1 ikke kræve ændringer. Introduktion af ny billetomveksling: den nye service er beskrevet i Afsnit 5 samt introduktion af ny signeringssnitflade, der overskriver NameId feltet. Seal.Java opgradering til version 2.1.6