1. Introduktion
1.1. Formål med dokumentet
Formålet med dette dokument er at give en detaljeret beskrivelse af de konkrete services, der udbydes af STS i forbindelse med anvendelsesområdet DGWS.
1.2. Læsevejledning
Dokumentet henvender sig primært til udviklere, der skal i gang med at anvende de konkrete DGWS snitflader udbudt af STS.
Dokumentet bygger i høj grad på den overordnede STS - Guide til anvendere, som giver et overblik over STS og levere i denne sammenhæng et mere dybdegående teknisk beskrivelse af de services i STS, der ligger i anvendelsesområdet DGWS.
2. Overblik over services og anvendelse
Som beskrevet i STS - Guide til anvendere, så findes der i STS to services indenfor anvendelsesområdet DGWS.
| /sts/services/NewSecurityTokenService | Niveau 3-4 | Udstedelse af SOSI Idkort. |
| /sts/services/SecurityTokenService | Niveau 3-4 | Legacy udgave af ovennævnte service (uden erstatning af NameId). Benyt NewSecurityTokenService hvis muligt |
Denne guide vil primært fokusere på servicen NewSecurityTokenService (i eksemplerne), da det er denne service, der skal anvendes fremadrettet.
Anvenders tilgang til DGWS services på STS kan ske med hjælp fra Seal.Java [SPG] eller Seal.NET [SN], som er biblioteker der bl.a. hjælper til med at understøtte brugen af DGWS herunder opbygning af requests til STS (NewSecurityTokenService).
Materiale omkring udstedelse af id-kort samt eksempler på kald af servicen fra en java-applikation kan findes under STS - Kom Godt i Gang.
Som nævnt i STS - Guide til anvendere, så kan STS DGWS services anvendes til at udstede to typer af SOSI Idkort:
- System Idkort (baseret på et OCES/OCES certifikat, niveau 3)
- Bruger Idkort (baseret på et OCES certifikat, niveau 4)
Det er den samme service, der skal anvendes til begge typer af billetter, men indholdet af requesten vil være forskellige. I afsnittet nedenfor med eksempler på requests vil der gives eksempler på begge typer af requests. For Bruger Idkort vil der yderligere være eksempler på udstedelse til brugere med og uden sundhedsfaglig autorisation.
2.1. Claims og valideringer
Det Idkort der genereres af anvendersystemet og indgår i requestet til STS kan indeholde en mængde attributter, som vil være at opfatte som claims (påstande) om den pågældende bruger. Følgende attributter er interessante i forhold til validering af STS:
- medcom:UserCivilRegistrationNumber: Brugerens CPR nummer. Dette bliver valideret af STS vha OCES service til validering af RID-CPR (RID står i certifikatet).
- medcom:UserRole: Kan indeholde enten en uddannelseskode (for sundhedsfaglige) eller en national (SEB) rolle eller lokal rolle for brugere uden sundhedsfaglig autorisation.
- medcom:UserAuthorizationCode: Kun relevant for sundhedsfaglige brugere. Valideres af STS ved hjælp af autorisationsregisteret.
For sundhedsfaglige brugere valideres uddannelsekoden (medcom:UserRole) og autorisationsnummeret (medcom:UserAuthorizationCode) på følgende måde:
- Hvis både autorisationsnummer og uddannelseskode er medsendt, verificeres disse via autorisationsregisteret og indsættes i det returnerede Idkort.
- Hvis enten autorisationsnummer eller uddannelseskode er medsendt, verificeres at dette matcher præcis én autorisation i autorisationsregisteret, og denne indsættes i det returnerede Idkort.
- Hvis hverken autorisationsnummer eller uddannelseskode er medsendt, verificeres at brugeren har præcis én autorisation i autorisationsregisteret, og denne indsættes i det returnerede Idkort.
For brugere uden sundhedsfaglig autorisation kan der angives en rolle (medcom:UserRole).
- Hvis der er angivet en national rolle (afgøres udfra prefix), så tjekker STS op i mod sin kopi af stamdata, at den pågældende bruger er i besiddelse af den angivne rolle.
- Hvis claimet om en national rolle kommer fra en trusted anvender (afgøres udfra CVR nummer op i mod STS konfiguration af trustede anvendere), så indsættes den nationale rolle uden tjek i stamdata.
- Hvis en anvender ikke har angivet en national rolle i claim-attributten, men den pågældende medarbejder er i besiddelse af netop én nationale rolle i stamdata, så vil denne automatisk inkluderes i det udstedte SOSI Idkort.
- Lokale roller (roller, der ikke har national rolle-prefix) inkluderes i det udstedte Idkort uden yderlige validering.
De nationale roller kan genkendes på, at de alle har prefixet urn:dk:healthcare:national-federation-role:
Eksempler på nationale roller er:
- urn:dk:healthcare:national-federation-role:SundAssistR1
- urn:dk:healthcare:national-federation-role:SundAssistR2
Der er også mulighed for at angive at brugeren ikke vil anvende en eventuel autorisation (eller national rolle). Dette gøres ved at angive "urn:dk:healthcare:no-role".
Skematisk ser algoritmen til validering/bestemmelse af rolle og/eller autorisationskode således ud:
3. Service Endpoint
Afhængig af miljø udstilles tjenesten på:
|
Der findes endvidere en ældre udgave placeret under /sts/services/SecurityTokenService, men ovennævnte endpoint anbefales til alle nye anvendelser.
4. Eksempler på requests
I det følgende gives eksempler på følgende typer af requests:
- Udstedelse af System Idkort
- Udstedelse af Bruger Idkort (med sundhedsfaglig autorisation)
- Udstedelse af Bruger Idkort (uden sundhedsfaglig autorisation men med national rolle)
NB! Det er vigtigt, at den i svaret medsendte sikkerhedsbillet opfattes som binær data og håndteres som sådan i anvendersystemet. Af hensyn til validitet af signering må der ikke laves om i billetten (f.eks. parsning og serialisering af XML), da dette kan have betydning for gyldigheden af de beregnede digests.
4.1. Udstedelse af System Idkort
Udstedelse af System Idkort sker på baggrund af et OCES certifikat. Et System Idkort identificerer som navnet antyder et anvendersystem, der ønsker at kalde services på NSP. Det kunne f.eks. være et anvendersystem, der i batch overfører data til MinLog fra en patientjournal.
Selve requestet til STS ser således ud:
En succesfuld validering af requestet i STS resulterer i et succesfuldt response (bemærk, at det udstedte System Idkort er signeret af 'SOSI Test Federation (funktionscertifikat)'):
4.2. Udstedelse af Bruger Idkort (med sundhedsfaglig autorisation)
For at få udstedt et Bruger Idkort med oplysninger om brugerens sundhedsfaglige autorisation, så må anvender systemet opbygge et request, der indeholder de claims (påstande) vedrørende autorsationsoplysninger (og cprnummer) for den pågældende bruger. I dette eksempel anvendes et OCES certifikat, der tilhører en person, der er i besiddelse af en lægefaglig autorisation.
Selve requestet til STS ser således ud (bemærk især claims om brugeren 'medcom:UserCivilRegistrationNumber' og 'medcom:UserAuthorizationCode', der angiver autorisationskoden samt 'medcom:UserRole', der angiver den tilhørende uddannelseskode):
En succesfuld validering af requestet i STS resulterer i et succesfuldt response (bemærk, at det udstedte Bruger Idkort er signeret af 'SOSI Test Federation (funktionscertifikat)' og indeholder de nu af STS validerede claims fra requestet. Bemærk også at medcom:UserRole er erstattet med uddannelseskoden, der hører til brugerens autorisation i autorisationsregisteret):
4.3. Udstedelse af Bruger Idkort (uden sundhedsfaglig autorisation, men med national rolle)
I dette eksempel anvendes et OCES certifikat for en bruger uden sundhedsfaglig autorisation men med netop én national rolle. Eksemplet illusterer, hvorledes STS automatisk sætter oplysninger ind om en medarbejders (unikke) nationale rolle, hvis en sådan findes.Selve requestet til STS ser således ud (bemærk især claims om brugeren 'medcom:UserCivilRegistrationNumber' og 'medcom:UserRole', der er sat til 'ingen_idkort_rolle' for at angive en uspecificeret rolle):
En succesfuld validering af requestet i STS resulterer i et succesfuldt response (bemærk, at det udstedte Bruger Idkort er signeret af 'SOSI Test Federation (funktionscertifikat)' og indeholder de nu af STS validerede claims fra requestet mht cprnummer og den automatisk påstemplede nationale rolle, som medarbejderen har):