Technisch Detail Ontwerp Externe IdP Configuratie Koppeltaal

In het Koppeltaal launch proces wordt optioneel gebruik gemaakt van een Externe Identity Provider (IdP) om de identiteit van de externe gebruiker te verifiëren voor deze toegang krijgt tot een doel-applicatie. De Externe Identity Provider en daarvoor benodigde Autorisatieregels moeten met behulp van het Koppeltaal Beheerportaal (kt2admin) geconfigureerd worden in een specifiek Koppeltaal 2 domein.

Context

Doel is om in het Koppeltaal Beheerportaal (kt2admin) de bestaande Autorisatieregels en Externe Identity Providers Configuraties te kunnen opvragen om ze in te zien, en te kunnen wijzigen.
N.B. De Autorisatieregels en Externe Identity Providers Configuraties worden niet opgeslagen in het StelselRegister; ze worden alleen opgeslagen in de database van de Autorisatie-server binnen het domein.

De Koppeltaal2 OAuth2 Launch flow met gedelegeerde authenticatie

De op deze pagina beschreven configuratie wordt gebruikt binnen de Koppeltaal2 OAuth2 Launch flow. Als er sprake is van gedelegeerde authenticatie ziet de happy flow er als volgt uit:

N.B. De nummering van de pijlen in het plaatje hierboven wordt in deze pagina gebruikt om aan te geven waar welke informatie wordt gebruikt.

Launch flow en gebruik van de Autorisatieregels en Externe Identity Provider

In de Koppeltaal2 OAuth2 Launch gebaseerd op de OAuth2 Authorization flow wordt er gecheckt of er sprake is van Delegated Authentication door de volgende query uit te voeren (pijl 3 in het diagram):

CODE

SELECT DoDelegate, ApplicationName, ExtraScopes, IDTokenClaim, IdentifierSystem FROM OAuth2Server_Koppeltaal.Configuration
 WHERE Aud = {request.aud}
   AND (SubTypes like {resourceType uit body.sub} or SubTypes is null)
   AND (TargetApplications like {body.aud} OR TargetApplications is null)

Indien er een match is, en het gevonden record is actief (DoDelegate = 1), dan wordt er een OAuth2 Authorization flow gestart naar de externe Identity Provider zoals geconfigureerd via de Client Configuratie met de naam ApplicationName (pijl 4 in het diagram).

De externe Identity Provider authenticeert de gebruiker (pijl 5, 6 en 7 in het diagram). Nadat dat met succes is uitgevoerd, vindt er redirect plaats terug naar het geconfigureerde redirection endpoint (pijl 8).

De KT2 Authorization Server haalt dan het IdToken op (pijl 9), en vraagt daarna de FHIR resource met de referentie body.sub op (pijl 10), Daarmee kan worden gecheckt of die een identifier bevat met system = IdentifierSystem en value = de waarde zoals gevonden in IdToken claim zoals geconfigureerd in IDTokenClaim (pijl 11).

Toelichting:

Via kolom SubTypes kan onderscheid gemaakt worden op basis van resourceType (Patient, Practitioner, RelatedPerson). Deze kunnen ook worden gecombineerd door een komma-gescheiden lijst met meerdere types op te nemen. Indien niet gevuld geldt de regel voor alle resource Types
Via kolom TargetApplications kan onderscheid gemaakt worden op basis van de doelapplicatie. Indien de configuratie van toepassing is op meerdere doel-applicaties kan een komma-gescheiden lijst worden opgegeven. Indien niet gevuld geldt de regel voor alle doel-applicaties
In de huidige architectuur is de tabel uniek voor 1 domein, en zal request.aud altijd gevuld zijn met de FHIR Base URL van het eigen domein. In die zin is het toevoegen / filteren op Aud redundant.

Autorisatieregels

Per domein kunnen er 0, 1 of meer actieve Autorisatieregels worden aangemaakt met de volgende inhoud. Deze regels worden via de daarvoor ontwikkelde API opgeslagen in tabel in de tabel OAuth2Server_Koppeltaal.Configuration in het domein.

Autorisatieregels

Kolom	Beschrijving	UI
ID nr.	Door de server toegewezen unieke ID	readonly
ApplicationName	Moet verwijzen naar de ApplicationName van een bestaande OAuth2 Client Configuratie, wordt gebruikt om te bepalen welke IdP gebruikt moet worden.	verplicht
Aud	Is altijd gelijk aan de FHIR Base URL (FHIR server) van het domein; wordt uit de configuratie overgenomen.	wordt automatisch gevuld
DoDelegate	Deze zal normaal gesproken de waarde 1 hebben. Een regel wordt feitelijk uitgezet als hier de waarde 0 in wordt gezet. In dat geval kan er een andere Autorisatieregel zijn die wordt gebruikt, indien er een andere regel is die aan de selectiecriteria voldoet. Als die niet wordt gevonden zal er geen Delegated Authentication plaatsvinden.	readonly
SubTypes	(Komma-gescheiden combinatie van) Patient, Practitioner en RelatedPerson, indien leeg geldt deze regel voor alle resourceTypen	checkbox
TargetApplications	(Komma-gescheiden combinatie van) de ClientIds van de applicaties, indien leeg geldt deze regel voor alle applicaties In de UI zal dit een multi-select control moeten zijn waarin de doel-applicaties kunnen worden geselecteerd.	checkbox; optioneel
ExtraScopes	In de OAuth Authorize call naar de externe IdP (pijl 4) worden standaard de scopes `openid` en `profile` meegegeven. Het kan zijn dat met alleen die standaard scopes de property genoemd in IDTokenClaim niet aanwezig is in het IDToken. In dat geval moet er een extra scope worden toegevoegd in ExtraScopes. Zie ook de OpenId documentatie sectie 5.4. Requesting Claims using Scope Values: profile (is default geselecteerd) - Geeft toegang tot `name`, `family_name`, `given_name`, `middle_name`, `nickname`, `preferred_username`, `profile`, `picture`, `website`, `gender`, `birthdate`, `zoneinfo`, `locale`,en `updated_at`. email - Geeft toegang tot `email` en `email_verified` address - Geeft toegang tot `address` phone - Geeft toegang tot `phone_number` en`phone_number_verified`	optioneel
IDTokenClaim	Uit welke IdToken claim moet de waarde worden gebruikt? Heeft vaak de waarde “sub”, maar soms ook “email” of andere waarden. Wordt gebruikt in pijl 11.	verplicht
IdentifierSystem	Identifier system zoals gebruikt in de FHIR resource van het domein om de resources te koppelen aan een IdP-identiteit, bijv. “https://medicore.id.nl/identifier/keycloakidentifier”. Wordt gebruikt in pijl 11.	verplicht

Per domein kunnen 0, 1 of meer Externe Identity Providers worden geconfigureerd met de volgende inhoud:

Externe Identity Providers

Server Entiteit	Attribuut	Beschrijving
OAuth2 Client / Server Description		Basisinformatie voor de externe IdP Let op: In elk domein is ook een OAuth2 Client / Server Description aanwezig voor de KT2AuthorizationServer op https://[acc21\|acc22\|prd2].koppeltaal.nl /api/v1/{domein}/oauth2. Omdat deze in de Launch geen rol speelt, wordt deze bij bevraging via de API weg gefilterd.
	Issuer Endpoint	Hiermee wordt metadata zoals authorization_endpoint opgehaald bij de externe IdP (Discovery). Dit gebeurt eenmalig, en is daarom niet in bovenstaand diagram te zien. De Issuer Endpoint moet door de aanvrager (zorgaanbieder of IT-deelnemer) beschikbaar worden gesteld. Voorbeeld: “https://dev-keycloak.tenzingerinfra.com/auth/realms/xyz”
	SSL/TLS Configuration	“Default” Opmerking: Als je SSL/TLS gebruikt bij de configuratie van een Identity Provider (IdP), betekent dat dat alle communicatie tussen de client en de IdP versleuteld is, zodat gegevens zoals wachtwoorden, tokens en gebruikersinformatie veilig en beschermd tegen afluisteren of manipulatie worden verzonden
Client Configuration		De Client Credentials die nodig zijn om de externe IdP te benaderen (pijl 4 en 9 in het diagram).
	Application Name	Is een unieke naam voor de client configuratie die gebruikt wordt om vanuit de Autorisatieregels om te verwijzen naar een externe IdP. In de handmatige procedure wordt hier “applicatie+domein” zoals “MedicoreAdhdcentraal” ingevuld, maar er zijn ook andere waarden gebruikt. Kan initieel worden gevuld maar is daarna read-only.
	Enabled	Moet 1 zijn om deze configuratie te kunnen gebruiken. Omdat deze wel een andere waarde kan hebben wordt die wel bij opvragen mee terug gegeven.
	Client type	“confidential” of “public” Opmerking: Een public client is een app die geen geheim kan bewaren (zoals een mobiele of webapp), terwijl een confidential client wél een geheim (Client Secret) gebruikt om zich veilig te identificeren bij de identity provider.
	SSL/TLS Configuration	“Default” Opmerking: Als je SSL/TLS gebruikt bij de configuratie van een Identity Provider (IdP), betekent dat dat alle communicatie tussen de client en de IdP versleuteld is, zodat gegevens zoals wachtwoorden, tokens en gebruikersinformatie veilig en beschermd tegen afluisteren of manipulatie worden verzonden
	Client Redirect Url	Deze wordt gebruikt door de externe IdP om te bepalen of dit een geldig Authorization request is (direct na ontvangen van pijl 4), en om na succesvolle autorisatie te kunnen redirecten naar de Autorisatie Server (pijl 8 in het diagram). Voor de Redirect Url moet in de InterSystems Management Portal worden geconfigureerd als: useSSL = true host met waarde “[acc21\|acc22\|prd2].koppeltaal.nl” port kan leeg blijven prefix met waarde “api/v1/{domein}” Binnen de InterSystems OAuth2 Server is het laatste deel altijd “/csp/sys/oauth2/OAuth2.Response.cls” Dit leidt tot een redirect url als https://prd2.koppeltaal.nl/api/v1/adhdcentraal/csp/sys/oauth2/OAuth2.Response.cls Deze redirect URL moet wel meegegeven worden aan de API, maar kan afgeleid uit de voor het domein geconfigureerde FHIR Base URL en hoeft dus niet ingevoerd te worden. Zie ook https://vzvz.atlassian.net/wiki/spaces/KTSA/pages/edit-v2/1688829964#De-Koppeltaal2-OAuth2-Launch-flow-met-gedelegeerde-authenticatie
	Client Id	Client Id waarmee de Autorisatie Server zich aanmeld bij de externe IdP. Dit is een verplcht veld dat altijd moet worden ingevuld
	Client Secret	Moet worden aangeleverd door de aanvrager indien Client type = “confidential” De Client Secret moet worden aangeleverd door de beheerder van de external IdP

Een werkende configuratie bestaat uit een combinatie van een Externe IdP Configuratie die (via ApplicationName) gekoppeld is vanuit minimaal 1 Autorisatieregel.

API voor beheer van Autorisatieregels en Externe Identity Providers

Er is custom REST API beschikbaar gemaakt op de OAuth2Server in het domein waarmee de Autorisatieregels en Identity Provider Configuraties kunnen worden onderhouden.

API

De API is beschikbaar in dezelfde REST service als de in het kt2admin beheerportaal geconfigureerde OAuth2 registratie endpoint.

Als dat de waarde https://domein/iapi/v1/management/register heeft, zijn de api’s vervolgens beschikbaar op:

GET /authrules

Deze call geeft alle bestaande Autorisatieregels terug:

CODE

[
    {
        "id": "1",
        "fhirBaseUrl": "https://ont.koppeltaal.itzosservices.nl/api/v1/domein1/fhir/r4",
        "resourceTypes": "Patient",
        "enabled": true,
        "idpconfig": "oidcidp2",
        "idTokenClaim": "email",
        "identifierSystem": "http://irma.app"
    },
    {
        "id": "2",
        "fhirBaseUrl": "https://ont.koppeltaal.itzosservices.nl/api/v1/domein1/fhir/r4",
        "resourceTypes": "Practitioner",
        "enabled": true,
        "idpconfig": "oidcidp2",
        "idTokenClaim": "email",
        "identifierSystem": "http://irma.app"
    }
]

POST /authrules

Indien property "id" wordt meegegeven wordt de betreffende Autorisatieregel geupdate

CODE

{
    "fhirBaseUrl": "https://ont.koppeltaal.itzosservices.nl/api/v1/domein1/fhir/r4",
    "resourceTypes": "RelatedPerson",
    "enabled": false,
    "idpconfig": "oidcidp2",
    "idTokenClaim": "email",
    "identifierSystem": "http://irma.app"
}

DELETE /authrules

Hierbij hoeft alleen het "id"meegegeven te worden:

CODE

{
    "id": "3"
}

GET /idpconfig

Deze call geeft de bestaande Externe IdP Configuraties terug met uitzondering van de eigen OAuth2 server:

CODE

[
    {
        "applicationName": "domein1@headease",
        "enabled": true,
        "issuerEndpoint": "https://iam.koppeltaal.headease.nl/realms/kt2_tst",
        "clientType": "confidential",
        "clientId": "theotest",
        "clientSecret": "xyz123",
        "redirectUri": {
            "host": "ont.koppeltaal.itzosservices.nl",
            "useSSL": false,
            "prefix": "api/v1/domein1"
        }
    },
    {
        "applicationName": "oidcidp2",
        "enabled": true,
        "issuerEndpoint": "https://ont.koppeltaal.itzosservices.nl/oauth2",
        "clientType": "confidential",
        "clientId": "IRISDEV",
        "clientSecret": "1eWQnU6WsERlJnZ9rqdgzXkT9yyf9ZUtoAd9TRz7_0azPeNwThDhbBs6_BBMw5h59HBqm0eKMClmlBZ7lGjMLA",
        "redirectUri": {
            "host": "10.68.152.129",
            "useSSL": false,
            "port": "52775"
        }
    }
]

POST /idpconfig

Hiermee worden achtereenvolgens:

Indien "create" de waarde true heeft, gecheckt of de applicationName uniek is. Zo niet, dan wordt melding ‘OAuth2 Client met de naam ”applicationName” bestaat al’ gegeven.
Een Server Definition met de betreffende waarde voor issuerEndpointgezocht. Indien deze nog niet bestaat wordt die aangemaakt en wordt de Discovery uitgevoerd.
Een OAuth2 Client aangemaakt met de overige properties uit het request.

CODE

{
    "applicationName": "domein1@headease",
    "enabled": true,
    "issuerEndpoint": "https://iam.koppeltaal.headease.nl/realms/kt2_tst",
    "clientType": "confidential",
    "clientId": "theotest",
    "clientSecret": "xyz123",
    "redirectUri": {
        "host": "ont.koppeltaal.itzosservices.nl",
        "prefix": "api/v1/domein1"
    },
    "create": true,
}

DELETE /idpconfig

Hierbij moeten alleen applicationName en issuerEndpoint meegegeven worden. Eerst wordt de OAuth2 Client op basis van de applicationName gezocht en verwijderd, gevolgd door het verwijderen van de Server Definition:

CODE

{
    "applicationName": "domein1@headease",
    "issuerEndpoint": "https://iam.koppeltaal.headease.nl/realms/kt2_tst"
}

CRUD Audit trail

Op basis van eerder beschreven API calls worden de Create, Update en Delete acties van de eindgebruikers gelogd. De Read actie is buiten beschouwing gelaten omwille de logging trail leesbaar en overzicht te behouden in de Logging scherm. Hieronder een beknopte overzicht van de selectie uit de keuzelijst van de loggingscherm om de IdP en Autorisastieregel logregels te weergeven.

Eindgebruikers Actie	IdP’s API actie	Keuzelijst in loggingscherm	Toelichting
Create	`"API method": "POST"` `"method": "CreateIdpconfig"`	Aanmaken/bijwerken IdP	Indien de eindgebruiker een nieuwe configuratie opzet via de “Aanmaken+“ wordt de variable `"create"`met de waarde true meegegeven. Dan wordt het vastgelegd in de Auditlog als `"CreateIdpconfig"` onder Aanmaken IdP in het tabeloverzicht.
Read	`"API method": "GET"` `"method": "ReadIdpconfig"`	Niet beschikbaar als optie
Update	`"API method": "POST"` `"method": "UpdateIdpconfig"`	Aanmaken/bijwerken IdP	Om de onderscheid te houden tussen Create en Update acties op de POST method, wordt de variable `"create"`met de waarde false meegegeven. Dit waarde wordt toegekend via de hyperlink actie vanuit de tabeloverzicht om een IdP configuratie bij te werken. Vervolgens wordt het als `"UpdateIdpconfig"` vastgelegd in de Auditlog onder Bijwerken IdP in het tabeloverzicht.
Delete	`"API method": "DELETE"` `"method": "DeleteIdpconfig"`	Verwijderen IdP

Eindgebruikers Actie	Autorisatieregels API actie	Keuzelijst in loggingscherm	Toelichting
Create	`"API method": "POST"` `"method": "CreateAuthrule"`	Aanmaken/bijwerken Autorisatieregel	Indien de eindgebruiker een nieuwe autorisatieregel via de “Aanmaken+“ aanmaakt, wordt de variable `"create"`met de waarde true meegegeven. Vervolgens is het in de Auditlog als `"CreateAuthrule"` vastgelegd en te zien als Aanmaken Autorisatieregel in het tabeloverzicht.
Read	`"API method": "GET"` `"method": "ReadAuthrule"`	Niet beschikbaar als optie
Update	`"API method": "POST"` `"method": "UpdateAuthrule"`	Aanmaken/bijwerken Autorisatieregel	Om de onderscheid te houden tussen Create en Update acties op de POST method, wordt de variable met de waarde `"create": false`meegegeven. Dit waarde wordt toegekend via de hyperlink actie vanuit de tabeloverzicht om een autorisatieregel bij te werken. Vervolgens wordt het als `"UpdateAuthrule"` vastgelegd in de Auditlog onder Bijwerken Autorisatieregel in het tabeloverzicht.
Delete	`"API method": "DELETE"` `"method": "DeleteAuthrule`	Verwijderen Autorisatieregel

Alle Create-, Update- en Delete-acties (met uitzondering van Read-acties) worden vastgelegd in de Auditlog en zijn beschikbaar in het Loggingscherm van de beheerportaal voor de daarvoor geautoriseerde gebruikersaccounts. Raadpleeg de onderstaande link voor meer informatie:

BEB - Beheren van entiteiten en bevoegdheden | Logging-Configuratie-IdP-en-Autorisatieregels