Denne "Kom Godt i Gang Guide" omhandler signering 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 læses inden denne guide.
IdentitetsserviceAdgang 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 der en fælles komponent, som kan udstede adgangsgivende billetter, som kun kræver simpel verifikation. En sådan komponent betegnes generelt som en "Identitetsservice" eller IdP (IdentityProvider). På NSP hedder servicen Security Token Service (STS). Introduktionen af STS 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. Føderation, ombytning af id-kort og servicekaldFølgende er et eksempel på hvad der sker i de forskellige skridt når en anvender ombytter sit id-kort til et signeret af STS:
Bemærk at et id-kort kan anvendes til flere forespørgelser, så længe det endnu ikke er udløbet. Offentlige Certifikater til Elektronisk ServiceTil generel identifikation, dels som anvender overfor STS og dels for id-kortet overfor services på NSP, kræves digitale certifikater. På NSP skal disse overholde den fælles offentlige standard for certifikater. Standarden hedder OCES, Offentlige Certifikater til Elektronisk Service. OCES-certifikaterOCES certifikater indeles i fire hovedgrupper, hvoraf de tre anvendes på NSP:
Den sidste gruppe af certifikater betegnes som Personcertifikater, og udstedes til identifikation af privatpersoner. Digitaliseringsstyrelsen og Nets DanIDAlle OCES-certifikater udstedes af Nets DanID der varetager denne opgave for Digitaliseringsstyrelsen. Nets DanID har et rodcertifikat og herunder en række krydscertifikater som bruges til at udstede OCES-certifikaterne. Specielt kan det nævnes at det certifikat, en STS service er konfigureret med, blot er endnu et udstedt certifikat, ganske som alle andre udstedte certifikater. Dog definerer dette certifikat den omtalte føderation. I praksis er det anvender-bibliotekerne Seal.Java og Seal.Net, der kender til dette certifikat og dermed kan verificere id-kort med en signatur, der stammer fra certifikatet. Id-kortId-kortet er det bærende element ifm. signering i STS'en. Som beskrevet i platformsintroduktionen er id-kortet et XML-dokument der indeholder informationer om den person, virksomhed eller applikation, som foretager en forespørgsel mod en NSP-service. Når man ombytter et id-kort i STS'en, placeres id-kortet under SOAP Body elementet. Når man medsender et id-kort ifm. kald af NSP-services placeres det under SOAP Header elementet. AttributterEt id-kort består af en mængde attributter som anvendersystemet udfylder. En del af disse attributter bliver verificeret af STS, og nogle bliver valideret af komponenterne. Verifikationen i STS gennemgås i næste hovedafsnit.
Hvis der er tale om et brugerid-kort er følgende attributter også tilstede
Certifikat og signaturNår et id-kort signeres, enten af anvenderen eller af STS, bliver certifikatets offentlige nøgle lagt ind på id-kortet og kortet signeres med certifikatets private nøgle. Seal-bibliotekerne udfører disse opgaver for een. Hvis man ønsker at vide hvordan det praktisk foregår, så er hele processen beskrevet i "Den Gode Webservice". VerifikationNår STS'en modtager en signeringsforespørgsel verificeres id-kortet og anvenderens certificat i flere skridt. Disse skridt er kort beskrevet i de følgende afsnit, og er yderligere uddybet i STS dokumentationen. Verifikationen betyder at komponenter kan stole på korrektheden af de nævnte attributer, hvis id-kortet er signeret af STS'en. GyldighedEt id-kort er kun gyldigt i en bestemt periode. STS'en tjekker derfor at denne periode er oplyst på id-kortet og at det indeholder kaldstidspunktet. Dette gøres for at sikre at man ikke kan udstede et id-kort, der først bliver gyldigt en gang ude i fremtiden. Et id-kort kan maksimalt være gyldigt i 24 timer, derfor tjekker STS at den ønskede gyldighedsperioden ikke er længere end 24 timer. CertifikatDet certifikat, som anvender har brugt til at signere id-kortet i forespørgslen, skal være signeret af Nets DanID's rodcertifikatet (eller af et af krydscertifikaterne). Da der findes flere gyldige sæt af disse (test og produktion), er det vigtigt at anvender har styr på hvilket sæt den kaldende STS er en del af. SpærrelisterSelv om et certifikat er korrekt udstedt til føderationen, kan det godt blive nægtet adgang. Dette sker ved hjælp af en såkaldt blackliste, der indeholder certifikater, der ikke længere må anvendes. Denne liste vedligeholdes som en del af certifikatinfrastrukturen og anvendes af STS til at afvise certifikater, der f.eks. er blevet kompromiteret eller på anden måde har mistet deres autoritet. CVR-nummerSTS verificerer at det angivne CVR-nummer matcher det CVR-nummer, der er angivet i certifikatet. PersonnummerHvis forespørgslen indeholder et brugerid-kort tjekkes at det angivne personnummer matcher det personnummer, der blev brugt da medarbejdercertifikatet blev udstedt. Verifikationen anvender en ekstern webservice til at finde det personnummer der er knyttet til CVR/RID-nummeret i certifikatet. Hvis der ikke var tilknyttet er CPR-nummer til certifikatet ved udstedelse, så kan dette certifikat ikke bruges til at få et signeret id-kort. AutorisationHvis forespørgslen indeholder et brugerid-kort, så laves der et opslag i autorisationsregisteret for at finde den autorisation, som brugeren anvender. Hvis der er angivet en rolle og/eller et autorisationsID i forespørgelsen, anvendes disse til at udvælge autorisationen. I "STS Anvender dokumentet" er udvælgelsesalgoritmen beskrevet i detaljer. Den følgende liste beskriver de gængse situationer med angivelse af autorisation. Disse situationer er også indeholdt i medfølgende eksempler.
Den konkrete udformning af forespørgelsen til STS kan ses i eksemplerne. EksemplerTil denne guide hører der to kodeeksempler, der viser hvordan man ved hjælp af Seal.Java kan kalde STS'en og få omvekslet et id-kort. Eksemplerne kan hentes via Subversion på følgende adresse: 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 UserIdCardExample.java og SystemIdCardExample.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
Virksomhedscertifikater
UserIdCardExample.javaEksemplerne i denne fil anvender nogle af medarbejdercertifikaterne fra modulet common. Hver eksempelmetode sætter først klassens variable op for derefter at kalde issueIdCard(). Denne metode har indlejrede kommentarer der forklarer hvert skridt i processen. userWithOneSpecificAuthorization I dette eksempel ombyttes id-kortet for en person, der kun har en enkelt autorisation. Autorisationskoden og uddannelseskoden angives begge og det returnerede id-kort har derfor en verificeret autorisation indlejret. userWithOneAuthorization I dette eksempel udstedes der id-kort til den samme person som i det tidligere eksempel. Men her angiver anvenderen ikke hvilken autorisation id-kortet skal indeholde. Fordi personen har én og kun én 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 kan vælge en tilfældig. Det anbefales altid at anvender udfylder autorisationskode og uddannelseskode på id-kortet. Hvis anvenderen ikke har adgang til disse og derfor ønsker at benytte 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 et 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. SystemIdCardExample.javaEksemplerne i denne fil anvender virksomhedscertifikatet og funktionscertifikatet fra modulet common. Hver eksempelmetode sætter først klassens variable op for derefter at kalde issueIdCard(). Denne metode har indlejrede kommentarer der forklarer hvert skridt i processen. companyIdCardExample Dette eksempel ombytter et id-kort signeret med et virksomhedscertifikat. I forhold til eksemplerne med medarbejdercertifikater så er den største forskel at der ikke skal gives nogle oplysninger om brugeren. functionIdCardExample I dette eksempel anvendes et funktionscertifikat i stedet for et virksomhedscertifikat som i det tidligere eksempel. |