Sikkerhedsprotokollen

Hvad er VDX API’ets sikkerhedsprotokol

API’et anvender sikkerhedsprotokollen OIO IDWS REST.

På API token flow diagram viser et sekvensdiagram for at få udstedt et token samt kalde Video API servicen. Den ses længere nede på siden.

Det skridt (se overblikstegningen under API token flow diagram), hvor WSC komponenten trækker et token fra STS er det skridt, der giver flest udfordringer.

Nedenfor vises et eksempel på et simpelt request og response mellem WSC og STS.

Request

Address: https://sts.vconf.dk/sts/service/sts Encoding: UTF-8 Http-Method: POST Content-Type: text/xml Headers: {Accept=[*/*], SOAPAction=[“http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Issue”]}

Payload:

Response:

Som det ses i eksemplet ovenfor udstedes tokenet med en række attributter, som anvendes af API’et:

• dk:medcom:organisation_id viser, hvilken organisation kaldet til API’et kommer fra (der skal være angivet een)
• dk:medcom:email viser, hvilken bruger kaldet til API’et laves på vegne af (der skal være een)
• dk:medcom:video:role viser, hvilke roller den pågældende bruger har

Brugerens identitet

Det kan være nyttigt for kaldende systemer at kunne angive f.eks. brugerens identitet: Hvis det kaldende system selv har stået for login i forhold til brugeren og dennes identitet derfor er kendt af det kaldende system, kan dette bede STS’en om at indlejre en brugeridentitet i tokenet. Dette forgår ved hjælp af claims i kaldet til STS (læs mere om claims i request her OIO WS-Trust Profile V1.2.pdf.

Nedenfor ses et eksempel på request og response til STS, hvor kalderen (WSC) claimer en bestemt identitet.

Request

Address: https://sts.vconf.dk/sts/service/sts Encoding: UTF-8 Http-Method: POST Content-Type: text/xml Headers: {Accept=[*/*], SOAPAction=[“http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Issue”]}

Payload:

Response:

Certifikater og krav til disse

Der anvendes en række certifikater i forbindelse med sikkerhedsprotokollen. Disse og kravene til disse er beskrevet nedenfor.

Certifikater anvendt til HTTPS kommunikation

Alt kommunikation sker via HTTPS. De certifikater der anvendes her er udstedt af Let’s Encrypt. I praksis betyder det at alle systemer automatisk stoler på dette rodcertifikat og der skal dermed ikke gøres yderligere for validere certifikaterne korrekt.

STS

Når STS’en skal udstede et token så skal det request der sendes signeres af klienten. Den offentlige del af dette certifikat skal være konfigureret i STS’en. Der skal anvendes et funktionscertifikat udstedt af nets.

Svaret, der indeholder token, er også signeret. Certifikatet der anvendes her er et self-signed certifikat. Derfor er det nødvendigt at truste dette certifikat. Den offentlige del af certifikatet kan hentes på https://docs.vconf.dk/sts/cert/sts.cer og har følgende SHA256 fingeraftryk 4C:1E:52:6E:79:D8:F2:44:0A:46:0F:4A:E7:F8:3D:56:D4:C2:10:9F:78:88:95:04:19:86:21:93:BA:FB:47:1B.

API kald

I forbindelse med API kald anvendes der mTLS. Det certifikat som klienten skal anvende er det samme som der er anvendt til at signere den request der er sendt til STS’en. Formålet med dette er at validere det token der sendes rent faktisk er udstedt til den der anvender token. Det er vigtigt at det kun er klientcertifikatet der anvendes og ikke hele certifikatkæden.

Certifikat krav

Nedenstående er de krav der er til certifikatet.

• Skal være udstedt af CA som servicen validerer op imod.
• Certifikatet skal indeholde emailadresse på brugeren.

Certifikatbaseret sikkerhed

Til enkelte services anvendes der certifikatbaseret sikkerhed (mTLS). Her er det et klientcertifikat, der f.eks. er installeret i anvenderens browser, der identificerer anvenderen.

For at et klientcertfikat kan give adgang skal dette være udstedt af den CA som servicen validerer op imod. Udover dette er der også krav til indholdet af certifikatet.

API token flow diagram

Nedenstående sekvensdiagram viser det flow der sker når en anvender skal kalde Video API’er.

I ovenstående eksempel er det Video API servicen der er anvendt som eksempel og derfor URL’er til Video API servicen der refereres til. Er det en anden service skal kaldes er det andre URL’er der skal anvendes.

1. Anvender beder STS’en om at udstede et SAML token. Dette sker via et SOAP kald. For at STS’en kan udstede et SAML token skal klienten være konfigureret i STS’en med et certifikat samt andre oplysninger om anvender. STS’en kan tilgås på https://sts.vconf.dk/sts/service/sts og dens WSDL kan tilgås på https://sts.vconf.dk/sts/service/sts?wsdl.
2. Er klienten konfigureret i STS’en og anvender klienten det rigtige certifikat udsteder STS’en et SAML token og returnerer dette til anvender.
3. Det returnerede SAML token i punkt 2 postes til Video API servicen. Det sker på https://videoapi.vconf.dk/videoapi/token
4. Der returneres et session id som skal anvendes når Video API servicen skal kaldes. Det samme session id kan anvendes indtil det ikke længere gyldigt. Dermed sparer man kaldende i punkterne 1-4.
5. Selve kaldet til Video API’et laves. Session id medsendes som en HTTP header. Hvis man f.eks. ønsker at oprette et møde sker det ved HTTP POST kald til https://videoapi.vconf.dk/videoapi/meetings
6. Video API’et svarer tilbage.

Det returnerede SAML token i punkt 2 udløber, som standard, efter 8 timer. Hvornår et givent token pæcist udløber er angivet i svaret fra STS servicen.

Eksempelkode

Overordnet set er der to måder at kalde VDX services på. Forskellen er om man selv ønsker at håndtere sikkerhedsprotokollen eller man vil overlade den del til en proxy service.

Ønsker man selv at håndtere sikkerhedsprotokollen er man selv ansvarlig for at få udstedt et SAML token fra STS’en og veksling af dette til et access token.

Hvis man overlader sikkerhedsprotokollen til en proxy service (WSC) så skal man blot kalde de rene REST snitflader i de forskellige services og WSC servicen sørger så for at få udstedt et token fra STS’en og vekslet dette til et access token.

Kald af service uden WSC proxy

Der findes både et C# og et Java eksempel på dette.

C# OIO-IDWS eksempel

Et fungerende kode eksempel kan findes: Her

Kode eksemplet beskriver login flow og token requests. Eksemplet er lavet i C#.Net

Java OIO-IDWS eksempel

Et fungerende Java eksempel kan findes på https://github.com/medcomdk/vdx-example-java. I eksemplet er der også dokumentation af hvordan man afprøver eksemplet.

Kald af service med WSC proxy

Der findes et Java eksempel på hvordan man kalder en service via en proxy.

Et fungerende Java eksempel kan findes på https://github.com/medcomdk/vdx-example-java-wsc. I eksemplet er der også dokumentation af hvordan man afprøver eksemplet.