BEB - Beheren van entiteiten en bevoegdheden

Inleiding

Dit document beschrijft de entiteiten en bevoegdheden op de beheerschermen. De beheerschermen bevat o.a. gegevens van domeinen, applicaties, applicatieinstanties, gebruikers (beheerders), applicatierollen, en logging. Verschillende gegevens zijn tevens bepalend voor het verlenen van toegang tot resources.

Bij het ontwerpen van de beheerschermen zijn vanuit discussie tussen testteam en architectuur verschillende eisen en wensen aangegeven. Tijdens het ontwikkelproces met Itzos zijn hierop enkele aanpassingen of keuzes gemaakt om een werkbaar geheel te krijgen. Voor logging van de beheerschermen waren de eisen zeer minimaal en is de logging naar beste inzicht vorm gegeven.

Beschrijving

Applicatierollen en autorisatieregels (zie ook KT-TOP-005).

Rollen en autorisatieregels kunnen vastgelegd worden. De naam van de rol is uniek en niet wijzigbaar. Binnen de rol moet per resource vastgelegd kunnen worden of een Create, Read, Update en Delete actie is toegestaan. Daarnaast moet bij Read, Update en Delete aangegeven worden of dit alleen voor de resource is toegestaan die de applicatieinstantie zelf heeft aangemaakt (OWN), of dat de applicatieinstantie de actie op al deze resources in hetzelfde domein mag uitvoeren (ALL).

Dit is een domein- en applicatie onafhankelijke taak. Vastlegging wordt uitgevoerd door Support (de systeembeheerder).

N.B. De 'GRANTED' optie is i.v.m. complexiteit niet gebouwd in de Itzos omgeving.

N.B. Er zijn nog geen procesafspraken gemaakt over hoe we in de praktijk om moeten gaan met rollen en autorisatieregels. Voor nu gaan we uit van een rol die beperkt is tot de resources (en de CRUD acties hierop) die gelijk is aan waarvoor applicatie geaccepteerd is/wordt.

N.B. Het is nog niet mogelijk om applicatierollen, die niet in gebruik zijn, te beëindigen/verwijderen. (bevinding)

Domein

Het domein bevat (minimaal) de volgende gegevens/attributen:

• Een unieke domein identifier. (Deze is aanwezig, maar niet zichtbaar op het scherm.)

• Een (leesbare) naam van het domein. (verplicht, en niet wijzigbaar) Verder gelden de volgende eisen:

  o   De naam moet beginnen met een letter en eindigen met een letter of cijfer.

  o   Spaties en speciale tekens zijn niet toegestaan, behalve het minteken (-).

  o   Tussen het 1^e en laatste teken is een combinatie mogelijk van letters, cijfers en het minteken (-).

  o   Maximaal 32 tekens.

  • Wordt niet voldaan aan de eisen dan verschijnt de melding: "De naam moet beginnen met een letter en eindigen met een letter of cijfer. Spaties en speciale tekens zijn niet toegestaan, behalve het minteken (-). Het minteken mag niet aan het begin of einde staan. Maximaal 32 tekens."

  • Als de ingevoerde domeinnaam eerder gebruikt is, wordt de volgende melding getoond: “Er bestaat al een domein met deze naam.".

• Url van de autorisatieserver (verplicht, begint met 'https'). Url wordt automatisch gevuld o.b.v de lowercase waarde van de domeinnaam. (Dit geldt ook voor de url's hieronder.)

• Url van de endpoint van de autorisatieserver (verplicht, begint met 'https').

• Url van de FHIR server (verplicht, begint met 'https').

• Contactpersoon voor het domein :

  • Naam (verplicht).

  • Email (verplicht). Zie beschrijving in BRL - Beheerdersrollen, hoofdstuk Gebruikers.

  • Telefoonnummer (optioneel). Zie beschrijving in BRL - Beheerdersrollen, hoofdstuk Gebruikers.

Daarbij bevat het domein ook gegevens van de bijbehorende domeinbeheerders, applicatieinstanties, connectieaanvragen en logging.

N.B. Het domein kan ingevoerd worden door de systeembeheerder nadat Itzos ook het complexe proces aan de 'achterkant' van het domein heeft ingericht. Een nieuw domein moet dus altijd aangevraagd worden bij Itzos.

Applicatie

De applicatie bevat (minimaal) de volgende gegevens/attributen:

• Een unieke applicatie identifier. (Deze is aanwezig, maar niet zichtbaar op het scherm.)

• Een (leesbare) naam van de applicatie (verplicht, en niet wijzigbaar).

  • Maximaal 32 karakters.

  • Toegestaan: alfanumeriek, spatie, uitroepteken, underscore, minteken en punt.

• Aanmaakdatum. (Deze wordt automatisch gevuld bij aanmaken en is niet wijzigbaar.)

• Eén of meer rollen. Te selecteren uit de lijst van (actieve) rollen. Minimaal 1 rol verplicht. (Bevinding: Deze is na aanmaken van de applicatie niet meer te wijzigen.)

• Contactpersoon voor de applicatie :

  • Naam (verplicht).

  • Email (verplicht). Zie beschrijving in BRL - Beheerdersrollen, hoofdstuk Gebruikers.

  • Telefoonnummer (optioneel). Zie beschrijving in BRL - Beheerdersrollen, hoofdstuk Gebruikers.

Daarbij bevat de applicatie ook gegevens van de bijbehorende applicatiebeheerders en connectieaanvragen.

Applicatieinstantie

Een applicatieinstantie is geen zelfstandige eenheid, maar de entiteit van de applicatie binnen een domein. Deze ontstaat als de applicatiebeheerder en zgn. connectieaanvraag doet vanuit de applicatie (status 'Actief' of 'In onderhoud') aan een domein, en de domeinbeheerder van dat domein deze connectieaanvraag (met status 'open') accepteert.

Een geaccepteerde connectieaanvraag wordt een applicatieinstantie en krijgt daarmee ook een ClientID en een resource Device. (In Itzos omgeving heeft het Device dezelfde id als de ClientID van de applicatieinstantie.). De connectieaanvraag is verdwenen uit de lijst van connectieaanvragen.

Indien de domeinbeheerder de connectieaanvraag weigert, dan wordt er geen applicatieinstantie aangemaakt en wordt dus de toegang tot het domein geweigerd. De connectieaanvraag blijft in de lijst van connectieaanvragen staan met de status 'geweigerd', en kan ook niet meer geaccepteerd worden.

Indien de applicatie reeds een connectieaanvraag heeft gedaan, dus bij status 'open', 'geaccepteerd' of 'geweigerd', is het niet meer mogelijk voor de applicatie een nieuwe connectieaanvraag te doen. De volgende melding verschijnt:  'Applicatieinstantie bestaat al.' Indien de aanvraag is afgewezen, verschijnt melding: “Er is eerder een connectieaanvraag ingediend. Het is niet mogelijk dit nogmaals te doen.”.

Een connectieaanvraag kan niet geaccepteerd worden als de applicatie de status 'Afgesloten' heeft. De volgende melding verschijnt bij het accepteren: "De Connectieaanvraag kan niet geaccepteerd worden, de applicatie heeft de status 'Afgesloten'."

Note: De systeembeheerder kan beide acties ook uitvoeren, maar mag dat procedureel níet.

Connectieaanvraag bevat (minimaal) de volgende gegevens/attributen:

• Een JWKS uri. Is een unieke resource identifier dat refereert naar een applicatie JSON Web Key Set bestand dat (roulerende) publieke sleutels van de applicatie bevat. Veld bevat controle of deze bereikbaar is. Getoonde melding: 'De JWKS URL is niet bereikbaar; controleer of de URL correct is.' Er zal geen controle plaatsvinden als het veld leeg gelaten wordt. Reden voor het leeg laten van het veld kan zijn als IT-deelnemer het ClientId van de applicatieinstantie nodig heeft om een JWKS uri aan te maken. De JWKS uri moet daarna alsnog toegevoegd worden aan de applicatieinstantie om deze te kunnen gebruiken. 

• De redirect_uri(s). Max. 3 uri's mogelijk. Is optioneel veld, maar moet wel ingevuld worden om een SHOF launch uit te kunnen voeren.

• De applicatienaam (wordt automatisch overgenomen en is niet wijzigbaar).

• Eén rol die gekoppeld is aan de applicatie. Het is niet mogelijk om een andere rol te selecteren, dan die bij de applicatie is vastgelegd.

• Domein waarnaar de connectieaanvraag gestuurd wordt. Het domein wordt geselecteerd uit een lijst van domeinen met status 'Actief' en 'In onderhoud'.

Indien de connectieaanvraag is ingediend, zijn alleen de velden JWKS uri en status aan te passen door geautoriseerden. De andere velden zijn niet muteerbaar.

Een ingediende connectieaanvraag krijgt automatisch een (leesbare) naam voor de aan te maken applicatieinstantie (zie onder 'applicatieinstantie').

Mailnotificatie connectieaanvraag:

• Het indienen van een connectieaanvraag resulteert in een mailnotificatie naar alle actieve domeinbeheerders die vastgelegd zijn bij het domein uit de connectieaanvraag.

  • Onderwerp: Nieuwe connectieaanvraag voor domein <domeinnaam> op <omgeving>

  • Tekst: Er is een connectieaanvraag ingediend voor applicatie <applicatienaam> in uw domein <domeinnaam>.

• Het accepteren van een connectieaanvraag resulteert in een mailnotificatie naar de indiener van de connectieaanvraag.

  • Onderwerp: Connectieaanvraag geaccepteerd.

  • Tekst: Uw aanvraag om applicatie <applicatienaam> toe te voegen aan domein <domeinnaam> is geaccepteerd.

  • Voor de applicatie-domein combinatie zijn de volgende gegevens geregistreerd:

Applicatieinstantie: <naam applicatieinstantie>

Client-Id: <client-id>.

Omgeving: <omgeving>

• Het weigeren van een connectieaanvraag resulteert in een mailnotificatie naar alle actieve applicatiebeheerders die vastgelegd zijn bij de applicatie.

  • Onderwerp: Connectieaanvraag geweigerd

  • Tekst: Uw aanvraag om applicatie <applicatienaam> toe te voegen aan domein <domeinnaam> op <omgeving> is afgewezen.

Voor deze functionaliteit is de omgeving uitgebreid met een mailserver.

De applicatieinstantie bevat (minimaal) de volgende gegevens/attributen:

• Een unieke client identifier (Client ID) (format: UUID).

• Een (leesbare) naam (format: <applicatienaam>@<domeinnaam>, max 128 karakters, wordt automatisch gegenereerd en is niet wijzigbaar).

• Een (logische) naam. (Deze is aanwezig, maar niet zichtbaar op het scherm.)

• De JWKS uri. Is een unieke resource identifier dat refereert naar een applicatie JSON Web Key Set bestand dat (roulerende) publieke sleutels van de applicatie bevat.

• De redirect_uri(s). Max. 3 uri's mogelijk. Is optioneel veld, maar moet wel ingevuld worden om een SHOF launch uit te kunnen voeren.

• De domeinnaam.

• De applicatienaam.

• De rol.

Het overzicht van applicatieinstanties bevat ook een datum van aanmaken, maar dit is geen onderdeel van het detailscherm.

Logging - view AuditEvents

Het Audit Events scherm biedt de mogelijkheid om de events zoals beschreven in TOP-KT-011 - Logging en tracing te kunnen doorzoeken zoals die zijn opgeslagen in de Resource KT2_AuditEvent in de FHIR-Store. Iedere beheerder die toegang heeft tot het domein, kan de AuditEvents inzien, ook als het domein de status 'afgesloten' heeft.

Algemeen:

• Bij het openen van het scherm wordt de Start datum gevuld met de datum/tijd  van een week geleden, en worden de betreffende records getoond.

• Er wordt maximaal 100 resultaten getoond op het scherm, met vervolgpagina’s.

• Sortering is standaard op datum van nieuw naar oud.

• Het zoeken moet, net als elke GET actie, een AuditEvent aanmaken.

• Het is mogelijk om met de knop ‘Exporteren’ van de resultaten van de zoekopdracht een csv bestand te maken. (Dit bevat dus alleen de informatie van het overzicht, niet van de details. Bevat max. 1000 records.) De export bevat de volgende kolommen: DeviceId, Application, Datum, TraceId, RequestId, CorrelationId, Type, Subtype, ResourceType, Outcome en Error.

Het overzichtsscherm logging bevat de volgende gegevens boven de kolommen:

De velden zijn gevuld indien de gegevens beschikbaar zijn in de details van de AuditEvent.

Het detailscherm toont de hele resource AuditEvent in Json format.

Zoeken van de logging is mogelijk op:

• Timezone: Hier kan gekozen worden tussen 'Europe/Amsterdam' of 'UTC' (lokale tijd of UTC tijd). Standaard is het veld gevuld met 'Europe/Amsterdam'. (N.B. In de details van het AuditEvent wordt lastUpdated altijd als UTC tijd getoond.)

• Start datum: Standaard is de startdatum ingevuld met de datum/tijd (uit lastUpdated t/m de seconden) van een week geleden. Bij Timezone 'Europe/Amsterdam' is Start datum vertaald naar lokale tijd.

• Eind datum: Hier kan een t/m datum/tijd ingevuld worden.

• Type: Keuze uit: rest, launch/statuschange, notification, authentication.

• Subtype (rest): Keuze uit: read, search-type, create, update, delete, operation.

• Resource-type: Er kan op resource gezocht worden.

• Resultaat: Keuze uit: Success (outcome=0) en Failure (outcome<>0).

• DeviceId: Zodat op applicatieinstantie (resource-origin) gefilterd kan worden.

• Trace Id.

• Request Id.

• Correlation Id.

Logging - Beheerschermen

De applicatie Beheerschermen bevat een loggingscherm van de acties die op de beheerschermen worden uitgevoerd. Dit betreft het inloggen en uitloggen van beheerders, en alle create, update en delete acties die op de gegevens in de beheerschermen worden uitgevoerd.

Algemeen:

• Bij het openen van het logscherm zijn de datumvelden leeg "dd-mm-jjjj --:--", en worden de laatste 10 records getoond.

• Rechts onderin staat "Totaal: <aantal>. Pagina: x van y". Het Totaal is het aantal van alle records.

• Links onderin staat de knop 'Vorige' en/of 'Volgende', afhankelijk van noodzaak.

• Sortering is standaard op datum van nieuw naar oud.

Het overzichtsscherm logging bevat de volgende gegevens boven de kolommen:

• Datum/tijd → De datum en tijd (lokale tijd) dat het event heeft plaastgevonden

• Gebruiker → De gebruiker die het event heeft gegenereerd of voor wie het event is gegenereerd.

• Actie → De type actie die is uitgevoerd (bijvoorbeeld Aanmelden, Afmelden, E-mail Notificatie etc. etc.)

• Voor → Bevat het relevante deel van de url waarvoor een actie heeft plaatsgevonden. Bijv. de naam van domein, applicatie, applicatieinstantie, gebruiker of soort notificatie. Kolom 'Voor' is leeg bij actie Aanmelden, Afmelden en Wachtwoordherstel. Het detaillog bevat in deze log geen url. De kolom 'Gebruiker' geeft aan voor wie de log van toepassing is.

• Resultaat → De indicatie of de actie succesvol is geweest “OK” of niet succesvol is geweest “Fout Server” of “Fout Client” is geweest

• Foutmelding → Wanneer er een “Fout Server”of een “Fout Client”wordt gelogd wordt de Event Error in deze kolom getoond . (Deze zijn zichtbaar vanaf de releasedatum KTV2.2.1.KTS2.0.1. Oudere foutmeldingen konden niet hersteld worden.)

• Het detailscherm kan worden getoond door op hyperlink in de “Actie” kolom te klikken. De hele logging wordt dan in Json format getoond. De inhoud is afhankelijk van het soort logging. Wachtwoorden worden niet getoond in de logging. Deze worden vervangen door asterisken “*”.

• Indien er meerdere foutmeldingen zijn op 1 “Actie”, geeft het Log event-venster de informatie weer middels een scrollbar. Hieronder wordt een voorbeeld getoond van de details van een eventlog regel.

Zoeken van de logging is mogelijk op:

• Datum/tijd → De Datumvelden zijn initieel leeg bij het openen van de Logging page. Hierdoor zijn per direct zoekresultaten beschikbaar op basis van de huidige sessie van de gebruiker die als parameter aanhoudt.

• Resultaat → Er kan geselecteerd worden uit een lijst, waarin gekozen kan worden voor logging van acties die goed gegaan zijn, of acties die fout gegaan zijn.

• Gebruiker → Vrij veld waar de user van de beheerder ingevuld kan worden. De volledige user moet ingevoerd worden.

• Actie → Er kan geselecteerd worden uit een lijst met verschillende activiteiten.

Datums in logging:

De Datums in de detail-log is UTC tijd. De datums in het log-overzichtscherm en van de datum-zoekvelden maken gebruik van locale tijd. Dus 1 of 2 uur later dan de UTC tijd, afh. van zomer- of wintertijd. De browser rekent de tijd om naar UTC, waarna het pas naar de server wordt gestuurd. 

 Bij het vullen van de datumvelden moet zowel de datum als tijd (uu:mm) gevuld zijn. Dit kan door de gegevens in te tikken of middels de popup. Is de datum gevuld, maar de tijd leeg gelaten, dan wordt zoekopdracht niet uitgevoerd.

Knoppen popup datumvelden: De knop 'vandaag' wijzigt de datum naar vandaag, maar laat de tijd staan als die al gevuld is. Als de datum/tijd leeg is, dan wordt de huidige datum en tijd erin gezet. Bij 'wissen' wordt zowel datum als tijd gewist.

Logging emailnotificaties

De logging van emailnotificaties is met terugwerkende kracht toegevoegd aan de logging. De volgende emailnotificaties zijn aanwezig:

• Wijzigen email gebruiker (User EmailChanged)

• Reset wachtwoord (UserPasswordReset)

• Verlopen wachtwoord (UserEmailExpired)

• Indienen Connectieaanvraag (NewApplicationinstance)

• Accepteren connectieaanvraag (ApplicationinstanceAccepted)

• Weigeren connectieaanvraag (ApplicationinstanceRejected)

In de detaillog van de emailnotificatie bevat het onderdeel 'bericht' de invoer die gebruikt kan worden in de template van de email. De kolom 'Gebruiker' is voor notificaties altijd gevuld met de user (username) naar wie de email wordt verzonden. Voorbeeld:

{

  "iid": "5111",

  "username": "IlseTestA1",

  "timestamp": "2025-03-03T08:54:53.3Z",

  "method": "EmailNotification",

  "url": "UserEmailChanged",

  "status": "200 OK"

}

Bericht

{

  "newemailadres": koppeltaal-testteam@vzvz.nl,

  "username": "IlseTestA1",

  "fullname": "Ilse van der Wijngaard",

  "host": "acc21.koppeltaal.nl",

  "omgeving": "acc21"

}

Logging Configuratie IdP en Autorisatieregels

In koppeltaal beheer is het mogelijk een externe IdP te configureren. Voor elke aangemaakte IdP configuratie wordt een audit regel gelogd. Daarnaast wordt ook voor elke aangemaakte autorisatieregel een audit regel gelogd. Naast de aanmaak van beide regels worden ook updates en deletes van IdP’s en autorisatieregels gelogd.

Hieronder wordt een aantal voorbeeld getoond van een audit regels:

Aanmaken IdP

{
  "iid": "7093",
  "username": "ilsesysteem",
  "timestamp": "2025-08-22T06:07:50.5Z",
  "method": "CreateIdpconfig",
  "url": "TestIlse4@vzvzacc21testdomein2",
  "status": "200 OK"
}

Bericht

{
  "applicationName": "TestIlse4",
  "issuerEndpoint": "https://iam.koppeltaal.headease.nl/realms/kt2_tst",
  "clientType": "confidential",
  "clientId": "TestIlse1234",
  "clientSecret": "**********",
  "redirectUri": {
    "host": "acc21.koppeltaal.nl",
    "useSSL": true,
    "prefix": "api/v1/vzvzacc21testdomein2"
  },
  "enabled": true,
  "create": true
}

Aanmaken Autorisatie Regel

{
  "iid": "7454",
  "username": "devikasysteem",
  "timestamp": "2025-09-29T10:07:30.6Z",
  "method": "CreateAuthrule",
  "url": "16@vzvzacc21testdomein2",
  "status": "201 Created"
}

Bericht

{
  "idTokenClaim": "emaildevika123??????",
  "identifierSystem": "http://kt-launch-identifier.tst",
  "extraScopes": "openid",
  "id": "",
  "resourceTypes": "Patient,Practitioner,RelatedPerson",
  "targetApplications": "Testteam Admin@vzvzacc21testdomein2",
  "idpconfig": "0d77052c-6c5b-11f0-a7f0-02c61bf3bb01",
  "enabled": true,
  "fhirBaseUrl": "https://acc21.koppeltaal.nl/api/v1/vzvzacc21testdomein2/fhir/r4"
}

Bewerken Autorisatie Regel

{
  "iid": "7196",
  "username": "devikasysteem",
  "timestamp": "2025-08-27T10:35:20.2Z",
  "method": "UpdateAuthrule",
  "url": "15@vzvzacc21testdomein2",
  "status": "200 OK"
}

Bericht

{
  "idTokenClaim": "email",
  "identifierSystem": "http://kt-launch-identifier.tst",
  "extraScopes": "openid",
  "id": "15",
  "resourceTypes": "Patient,RelatedPerson",
  "targetApplications": "testapplicatie@vzvzacc21testdomein2,Testteam Admin@vzvzacc21testdomein2,Testteam Zorg ondersteuning@vzvzacc21testdomein2",
  "idpconfig": "Testdev1",
  "enabled": false,
  "fhirBaseUrl": "https://acc21.koppeltaal.nl/api/v1/vzvzacc21testdomein2/fhir/r4"
}
 

BEB - Eisen (en aanbevelingen) Beheren van entiteiten en bevoegdheden