Koppeltaal 2.0 Implementation Guide (Full Documentation)
0.15.0 - ci-build
NL
Koppeltaal 2.0 Implementation Guide (Full Documentation)
0.15.0 - ci-build
NL
Koppeltaal 2.0 Implementation Guide (Full Documentation) - Local Development build (v0.15.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions
| Page standards status: Draft |
| Datum | Wijziging |
|---|---|
| 2025-12-29 | De waarde van de idp_hint moet nu altijd gevuld worden met een logische identifier |
| 2025-12-02 | Drie interactiediagrammen samengevoegd tot één diagram met alt scenarios |
| 2025-12-02 | Functionele eis toegevoegd: lege lijst resulteert in default IdP |
| 2025-12-02 | Interne links toegevoegd naar paragrafen |
| 2025-12-02 | "De volgende opties zijn mogelijk" gewijzigd naar "Hieronder staan drie voorbeelden" |
| 2025-11-24 | Overwegingen sectie herschreven met focus op idp_hint keuze |
| 2025-11-24 | Initiële versie van de pagina |
Deze pagina beschrijft de ondersteuning voor meerdere Identity Providers (IdPs) per gebruikerstype binnen een Koppeltaal domein. Deze functionaliteit maakt het mogelijk om per launch aan te geven bij welke IdP de gebruiker geauthenticeerd moet worden.
Als platform die Koppeltaal 2.0 launches uitvoert, wil ik in de launch kunnen aangeven waar de gebruiker geauthenticeerd moet worden, zodat er per gebruiker een andere IdP gebruikt kan worden. Dit maakt het bijvoorbeeld mogelijk om onderscheid te maken tussen:
Deze functionaliteit is een uitbreiding op de bestaande Identity Provisioning configuratie. Waar voorheen per combinatie van domein, applicatie-instantie en gebruikerstype maximaal één IdP geconfigureerd kon worden (0..1), wordt dit uitgebreid naar meerdere IdPs (0..*).
idp_hint claimDe gekozen oplossing is een custom claim idp_hint in het HTI launch token. De voordelen van deze aanpak:
idp_hint is betrouwbaar zonder extra JWTid_token_hintInitieel werd de OIDC id_token_hint parameter overwogen. Dit alternatief is afgewezen vanwege:
id_token_hint is bedoeld voor re-authenticatie van dezelfde gebruiker, niet voor IdP-selectieid_tokenDe idp_hint wordt gevuld met een unieke logische identifier, bijvoorbeeld: idp-relatedperson-digid. Vanuit domeinbeheer kan deze toegekend worden aan een IdP. Deze kan runtime aangepast worden, zonder dat er in de applicaties iets aangepast hoeft te worden.
De lancerende applicatie dient de juiste waarde te verkrijgen via domeinbeheer of de bijbehorende documentatie.
De technische flow voor het gebruik van de idp_hint is als volgt:
Aanmelding bij lancerende applicatie: De gebruiker meldt zich aan bij de lancerende applicatie. Als dit met OIDC gebeurt, komt hier een id_token uit voort.
Toevoegen idp_hint aan HTI token: Tijdens de launch wordt aan het HTI token het veld idp_hint toegevoegd.
Ontvangst door gelanceerde applicatie: De gelanceerde applicatie (module) ontvangt de launch en start de SMART on FHIR app launch flow met de autorisatie service.
Verwerking door autorisatie service: De autorisatie service ontvangt het HTI token in de launch parameter en vindt daarin het idp_hint veld. Vervolgens past de autorisatie service de logica zoals beschreven in IdP resolutie algoritme toe.
idp_hint waardeHet HTI launch token wordt uitgebreid met een optionele idp_hint claim:
{
"iss": "client_id_portal",
"aud": "Device/123",
"sub": "Patient/456",
"resource": "Task/789",
"definition": "ActivityDefinition/abc",
"idp_hint": "https://idp.example.com/idp1/",
"iat": 1234567890,
"exp": 1234567950
}
In domeinbeheer moet de volgende functionaliteit beschikbaar zijn:
idp_hint claimDe autorisatie service bepaalt welke IdP gebruikt wordt volgens het volgende algoritme:
ALS idp_hint NIET aanwezig in launch token:
ALS geen custom IdP geconfigureerd voor gebruikerstype:
Gebruik default Koppeltaal 2.0 IdP
ANDERS:
Gebruik eerste geconfigureerde IdP (default)
ALS idp_hint WEL aanwezig in launch token:
ALS idp_hint waarde geconfigureerd voor dit gebruikerstype:
Gebruik deze IdP
ANDERS:
Log misconfiguratie
Voer fallback uit (alsof geen hint gegeven)
Bij een misconfiguratie van de IdP (bijvoorbeeld een ongeldige idp_hint) moet een AuditEvent aangemaakt worden. Dit valt onder de bestaande AuditEvent logging voor authenticatie (type 110114, User Authentication).
idp_hint worden verwerkt als voorheenidp_hint meestuurt, is het fallback scenario van toepassing. De autorisatie service gebruikt dan automatisch de eerste (default) IdP uit de geconfigureerde lijst. Dit maakt een gefaseerde uitrol mogelijk waarbij applicaties op hun eigen tempo kunnen worden bijgewerkt.idp_hint claim in het launch token wordt herkend door de autorisatie serviceidp_hint wordt fallback naar default uitgevoerdHet volgende diagram toont de drie scenario's voor IdP selectie:
