Technical Specifications PoC 1 "Mitz x Nuts"

[jorritspee]

Script

• Step 0. Preparation
• Step 1. Data-holder subscribes to Mitz-consent-choice-changes for patient X
• Step 2. Data-user gets HealthcareProviderRoleType-credential from mocked HealthcareProviderRoleType-issuer
• Step 3. Data-user sends unsuccessful data-request to Data-holder because no Mitz-consent is in place
• Step 4. Patient X registers consent and Data-holder-receives notification
• Step 5. Data-user sends successful data-request to Data-holder
• Step 6. Mocked Vzvz-issuer revokes HealthcareProviderRoleType-credential from Data-user
• Step 7. Data-user sends unsuccessful data-request to Data-holder using a revoked HealthcareProviderRoleType-credential

Roles per vendors

Partij	Data holder	Data user
HINQ	Nee	Ja
Topicus	Ja	Nee
KPN	Ja	Ja
Nedap	Ja	Ja
Phoqus	Nee	Ja

Principles

1. Organization authentication is based on GF Authentication IG
2. GF Authentication is implemented using Nuts v6
3. Person authentication is out of scope
4. Localization is out of scope
5. Authorization is only in scope for checking Mitz consent ("gesloten autorisatievraag")
6. A read on Patient and TreatmentDirective2 as defined in the ACP/PZP IG is used to show the correct working
7. We use FHIR R4

Specifications per step

This section covers the specifications for each step of the script.

Step 0. Preparation

1. Deploy Nuts node
   • as part of Knooppunt
   • OR independent
2. Create Organization Identity:
   • https://wiki.nuts.nl/books/implementing-a-nuts-use-case/page/1-create-organization-identity
   • Only for Data-user: Use x509credential based on fake uzi cert or test uzi cert
3. Only for Data-holder: Configure/ arrange access to Mitz test/ sandbox-environment
   • Use OpenLine-proxy-work-around <-- ACTION: TEST IF THIS STILL WORKS
4. Only for Data-user: configure Nuts node to enable OpenID4VCI
   • Enable NUTS_AUTH_AUTHORIZATIONENDPOINT_ENABLED (true)
   • OR: (TODO: Make OpenID4VCI implementation ready for general use nuts-node#3972)
5. Only for Data-user using Nuts Admin: configure Nuts Admin with Fake Vektis issuer (see https://github.com/nuts-foundation/nuts-admin?tab=readme-ov-file#requesting-credentials)

   credentialprofiles:
       - type: HealthcareProviderRoleType Credential
         issuer: https://knooppunt-vektis.nuts-services.nl

6. Done

Step 1. Data-holder subscribes to Mitz-consent-choice-changes for patient X

1. XIS of Data-holder sends request to Knooppunt as specified here: https://github.com/nuts-foundation/nuts-knooppunt/blob/main/docs/INTEGRATION.md#creating-a-consent-subscription
   • Use bsn: 039899044
2. Knooppunt takes care of the communication with Mitz
3. Done

Step 2. Data-user gets HealthcareProviderRoleType-credential from mocked HealthcareProviderRoleType-issuer

Vendor	HealthcareProviderRoleType code	HealthcareProviderRoleType description
HINQ	V5	Universitair medisch centrum
HINQ	V6	Algemeen ziekenhuis
KPN	todo	todo
KPN	todo	todo
Nedap	R5	Verpleeghuis
Nedap	T2	Thuiszorg
PhoQus	todo	todo
Phoqus	todo	todo
Topicus	N6	Huisartsenpost
Topicus	Z3	Huisartsenpraktijk

Option 1: use Nuts Admin

1. Data-user admin goes to the "Request credential"-screen in the Nuts Admin App (deeplink: /admin/#/id/test)
2. Click button "Request credential"
3. In "Credential Type", select "HealthcareProviderRoleType"
4. In "Wallet DID", select the did:web-identifier of the correct tenant
5. Follow the on-screen steps, choose the correct HealthcareProviderRoleType
6. Tenant should get one of the HealthcareProviderRoleType specified in the table below
7. Done

Option 2: use Nuts APIs

POST <nuts node internal API>/internal/auth/v2/{subjectID}/request-credential
Content-Type: application/json

{
  "wallet_did": "{target wallet DID}",
  "issuer": "https://knooppunt-vektis.nuts-services.nl",
  "credential_type": "HealthcareProviderRoleTypeCredential",
  "redirect_uri": "{redirect URI at EHR after issuance}"
}

Yields:

{"redirect_uri": "https://knooppunt-vektis.nuts-services.nl/some/url"}

Redirect the user to this link (tip: show HTML form with auto-submit or JS redirect to avoid cross-domain redirect/CORS issues)

Step 3. Data-user sends unsuccessful data-request to Data-holder because no Mitz-consent is in place

1. data-holder communicates his URA number to the data-user by shouting it through the room
   • Because Localization is out of scope this will be they way to find a data-holder
2. data-user XIS finds endpoints of data-holder by URA
   • GET <QueryDirBase>/Organization?identifier=http://fhir.nl/fhir/NamingSystem/ura|<URA-number>&_include=Organization:endpoint.
   • You will need the Endpoint supporting payloadType=Nuts-OAuth
   • and an Endpoint supporting payloadType=https://api.iknl.nl/docs/pzp/r4/CapabilityStatement/ACP-CapabilityStatementProvider
3. request access token using Nuts-OAuth endpoint
   • https://wiki.nuts.nl/books/implementing-a-nuts-use-case/page/requesting-access-outbound
4. send patient-search request using PZP-Fhir endpoint
   • POST-search on bsn, see

     POST /fhir/Patient/_search
     
     Header: Content-Type = x-www-form-urlencoded
     Body: identifier=http://fhir.nl/fhir/NamingSystem/bsn|004895708
     

   • OR POST Patient/$match using bsn
5. Data-holder PEP receives incoming request
6. Data-holder PEP introspects access token
   • use introspect-token endpoint of Nuts-node
   • get data-user's value of URA and of HealthcareProviderRoleType
7. Data-holder PEP sends request authorization request to Data-holder PDP
   • claims from token introspection
   • subject.properties.subject_role: fixed value 01.015
   • subject.properties.subject_id: fixed value 900030757
   • patient can be referred by FHIR-Patient_id or bsn
8. Data-holder PDP sends gesloten-vraag-request to Mitz
   • use data-user's value of URA and of HealthcareProviderRoleType
   • use own URA and HealthcareProviderRoleType
   • Data-holder XIS send gesloten-vraag-request to Knooppunt as specified here OR Knooppunt PDP does this: TODO
   • Response of gesloten-vraag is "DENIED"
   • Data-holder PEP denies access (http-response 403 forbidden)
9. Data-user XIS informs user that access was denied
10. Done

Step 4. Patient X registers consent and Data-holder-receives notification

1. Patient with bsn 039899044 logs in to mijnmitz.nl
2. Input yellow consent choice
   • "ziekenhuizen, gespecialiseerde klinieken, ambulancezorg, laboratoria en diagnostische centra"
     • can share with
       • "Huisartsen en huisartsenposten"
       • AND "Verpleging en verzorging"
       • AND "ziekenhuizen, gespecialiseerde klinieken, ambulancezorg, laboratoria en diagnostische centra"
   • "Huisartsen en huisartsenposten"
     • can share with
       • "Huisartsen en huisartsenposten"
       • AND "Verpleging en verzorging"
       • AND "ziekenhuizen, gespecialiseerde klinieken, ambulancezorg, laboratoria en diagnostische centra"
   • "Verpleging en verzorging"
     • can share with
       • "Huisartsen en huisartsenposten"
       • AND "Verpleging en verzorging"
       • AND "ziekenhuizen, gespecialiseerde klinieken, ambulancezorg, laboratoria en diagnostische centra"
3. Data-holder receives notification on the configured endpoint (https://github.com/nuts-foundation/nuts-knooppunt/blob/main/docs/INTEGRATION.md#configuration)
4. Data-holder XIS optionally informs user that Mitz consent choices have changed (via UI dialog and or log in EHR)
5. Done

Step 5. Data-user sends successful data-request to Data-holder

1. data-user uses the same data holder URA that was shouted through the room in step 3
2. data-user XIS finds endpoints of data-holder by URA
   • GET <QueryDirBase>/Organization?identifier=http://fhir.nl/fhir/NamingSystem/ura|<URA-number>&_include=Organization:endpoint.
   • You will need the Endpoint supporting payloadType=Nuts-OAuth
   • and an Endpoint supporting payloadType=https://api.iknl.nl/docs/pzp/r4/CapabilityStatement/ACP-CapabilityStatementProvider
3. request access token using Nuts OAuth endpoint
   • https://wiki.nuts.nl/books/implementing-a-nuts-use-case/page/requesting-access-outbound
4. send patient-search request using PZP-FHIR endpoint
   • POST-search on bsn
   • OR POST Patient/$match using bsn
5. Data-holder receives incoming request
6. Data-holder introspects access token
   • use introspect-token endpoint of Nuts-node
   • get data-user's value of URA and of HealthcareProviderRoleType
7. Data-holder PEP sends request authorization request to Data-holder PDP
   • claims from token introspection
   • subject.properties.subject_role: fixed value 01.015
   • subject.properties.subject_id: fixed value 900030757
   • patient can be referred by FHIR-Patient_id or bsn
8. Data-holder PDP sends gesloten-vraag-request to Mitz
   • use data-user's value of URA and of HealthcareProviderRoleType
   • use own URA and HealthcareProviderRoleType
   • Data-holder XIS send gesloten-vraag-request to Knooppunt as specified here OR Knooppunt PDP does this: TODO
   • Response of gesloten-vraag is "ALLOWED"
   • PEP of Data-holder gives access and responds with Patient-resource
9. Data-user XIS gets id from Patient-resource and sends search-request for TreatmentDirective
   • FHIR-profile: https://api.iknl.nl/docs/pzp/r4/StructureDefinition-ACP-TreatmentDirective.html
   • Query: GET [base]/Consent?patient=[id]&scope=http://terminology.hl7.org/CodeSystem/consentscope|treatment&category=http://snomed.info/sct|129125009&_include=Consent:actor (see https://api.iknl.nl/docs/pzp/r4/data-exchange.html#client-requests)
10. Data-holder introspects access token
    • use introspect-token endpoint of Nuts-node
    • get data-user's value of URA and of HealthcareProviderRoleType
11. Data-holder sends gesloten-vraag-request to Mitz
    • use data-user's value of URA and of HealthcareProviderRoleType
    • use own URA and HealthcareProviderRoleType
    • Data-holder XIS send gesloten-vraag-request to Knooppunt as specified here OR Knooppunt PDP does this: TODO
    • Response of gesloten-vraag is "ALLOWED"
    • PEP of Data-holder gives access and responds with Consent-resource
12. Data-user XIS displays Patient and Consent resource
13. Done

Step 6. Mocked Vzvz-issuer revokes HealthcareProviderRoleType-credential from Data-user

1. An admin of the CredentialIssuer pushes a button in its admin app to revoke the HealthcareProviderRoleType-credential from Data-user
   • The URL at which the (fake) Vektis issuer admin can revoke credentials is the following: https://knooppunt-test.nuts-services.nl/nuts-admin/#/vc/issuer
   • Click on a credential to show its details, then hit the red "revoke" button at the bottom of the page
2. Admin shouts through the room at data-user that the HealthcareProviderRoleType-credential is revoked
3. Done

Step 7. Data-user sends unsuccessful data-request to Data-holder using a revoked HealthcareProviderRoleType-credential

1. data-user uses the same data holder URA that was shouted through the room in step 3
2. data-user XIS finds endpoints of data-holder by URA
   • GET <QueryDirBase>/Organization?identifier=http://fhir.nl/fhir/NamingSystem/ura|<URA-number>&_include=Organization:endpoint.
   • You will need the Endpoint supporting payloadType=Nuts-OAuth
   • and an Endpoint supporting payloadType=https://api.iknl.nl/docs/pzp/r4/CapabilityStatement/ACP-CapabilityStatementProvider
3. request access token using Nuts OAuth endpoint
   • https://wiki.nuts.nl/books/implementing-a-nuts-use-case/page/requesting-access-outbound
   • The script will end at this step (7.3) because the data holder won't issue an access token if one of the credentials has been revoked.
4. Data holder can see in logs that an access token has failed due to a revoked credential
   • Data holder should report (to who) that the credential is revoked
5. Done

[SimonVeldhuijzen]

2: This is very focused on clicking through a UI, one that we don't have. Could you include what the technical goal is here? What does clicking through the UI accomplish and how would you do that using the Nuts APIs?
3.2: As far as I know there's no Fhir way to get an endpoint through reverse searching by organization. Closest is probably to include the endpoints in the organization search. Example:

https://ngfs-development.ons.io/fhir/QUERY/Organization?identifier=http://fhir.nl/fhir/NamingSystem/ura|90000380&_include=Organization:endpoint

3.3: What scope will we use here?
3.7: Where do you get the HealthcareProviderType from? Is it part of the introspection result?
Those also apply to step 5.2/5.3/5.7
5.9: Are we doing this one or not? Wasn't clear yet to me

[SimonVeldhuijzen]

3.2: As far as I know there's no Fhir way to get an endpoint through reverse searching by organization.

Agree; just edited 3.2, 5.2 and 7.2 (I was editing while this discussions was happening...)

We just looked at this a bit more. This works:

https://ngfs-development.ons.io/fhir/QUERY/Endpoint?_has:Organization:endpoint:identifier=http://fhir.nl/fhir/NamingSystem/ura|90000380&payload-type=http://nuts-foundation.github.io/nl-generic-functions-ig/CodeSystem/nl-gf-data-exchange-capabilities|Nuts-OAuth

[SimonVeldhuijzen]

2: This is very focused on clicking through a UI, one that we don't have. Could you include what the technical goal is here? What does clicking through the UI accomplish and how would you do that using the Nuts APIs?

@reinkrul of @rolandgroen could you make a little bulleted list of steps on how to request the HealthcareProviderTypeCredential without the Nuts-admin-app but by using the Nuts-node-API's?

The technical goal is to have an organization type credential in the organization wallet, which is needed to do the Mitz check. It can be acquired in 2 ways:

• Request the credential from Vektis through OpenID4VCI. You trigger this by invoking a Nuts node API, which gives you a redirect URL using which the user requests the credential from Vektis. Ultimately, the user will be someone from the care organization who can log in with eHerkenning at Vektis. Vektis then issues the credential to the organization's wallet in the Nuts node.
• Alternatively, we could provide a manual-issuance feature in the (fake) Vektis credential issuer, so you can acquire a credential manually there, and load it into the Nuts node.

The title for step 2 references ZorgAB. That's different from Vektiz.

[hansvr2022]

The technical goal is to have an organization type credential in the organization wallet, which is needed to do the Mitz check. It can be acquired in 2 ways:

• Request the credential from Vektis through OpenID4VCI. You trigger this by invoking a Nuts node API, which gives you a redirect URL using which the user requests the credential from Vektis. Ultimately, the user will be someone from the care organization who can log in with eHerkenning at Vektis. Vektis then issues the credential to the organization's wallet in the Nuts node.
• Alternatively, we could provide a manual-issuance feature in the (fake) Vektis credential issuer, so you can acquire a credential manually there, and load it into the Nuts node.

What would that credential look like in relation to the AGB code in the URA X509 credential? In my understanding the AGB code in the x509 is from the main organization. When going through the AGB register for bigger organizations it's quite often the case that the main organization doesn't have the healthcarecategory to use for the consent. A location of the main organization could have it. IE: https://www.vektis.nl/agb-register/vestiging-47472049 is a location of https://www.vektis.nl/agb-register/onderneming-41410703. How would that work in the credential since the credential by AGB that could be linked to the URA credential could not have the healthcarecategory that the location of the requestor has?

[jorritspee]

2: This is very focused on clicking through a UI, one that we don't have. Could you include what the technical goal is here? What does clicking through the UI accomplish and how would you do that using the Nuts APIs?

@reinkrul of @rolandgroen could you make a little bulleted list of steps on how to request the HealthcareProviderTypeCredential without the Nuts-admin-app but by using the Nuts-node-API's?

The technical goal is to have an organization type credential in the organization wallet, which is needed to do the Mitz check. It can be acquired in 2 ways:

• Request the credential from Vektis through OpenID4VCI. You trigger this by invoking a Nuts node API, which gives you a redirect URL using which the user requests the credential from Vektis. Ultimately, the user will be someone from the care organization who can log in with eHerkenning at Vektis. Vektis then issues the credential to the organization's wallet in the Nuts node.
• Alternatively, we could provide a manual-issuance feature in the (fake) Vektis credential issuer, so you can acquire a credential manually there, and load it into the Nuts node.

The title for step 2 references ZorgAB. That's different from Vektiz.

changed section title

[jorritspee]

What would that credential look like in relation to the AGB code in the URA X509 credential? In my understanding the AGB code in the x509 is from the main organization. When going through the AGB register for bigger organizations it's quite often the case that the main organization doesn't have the healthcarecategory to use for the consent. A location of the main organization could have it. IE: https://www.vektis.nl/agb-register/vestiging-47472049 is a location of https://www.vektis.nl/agb-register/onderneming-41410703. How would that work in the credential since the credential by AGB that could be linked to the URA credential could not have the healthcarecategory that the location of the requestor has?

In the hackathon we controle the issuer ourselves so no problems there.
In the real situation the issuer will need to have a proper database behind it that links ALL supported HealthcareProviderRoleTypes to each Organization.

[melihaydogd]

We are using the nuts admin dashboard. I don't see a Request Credential button. I suppose it should be Issue Credential. Even after that, I can only see NutsOrganizationCredential and NutsUraCredential. I am using the latest nuts-admin deployment. Is there another version I should be using?

[reinkrul]

You need to configure the Credential Issuer in Nuts Admin; see https://github.com/nuts-foundation/nuts-admin?tab=readme-ov-file#requesting-credentials

E.g.:

credentialprofiles:
    - type: HealthcareProviderTypeCredential
      issuer: https://knooppunt-vektis.nuts-services.nl

(note that we're changing the credential name to HealthcareProviderRoleTypeCredential, but I haven't deployed that yet).

I'll add it to the script.

[melihaydogd]

I am using the environment variables to set the values. I expect it to work like the following since it is an array and it should have array indices. The config endpoint returns empty strings for both issuer and type the following variables.

  NUTS_CREDENTIALPROFILES_0_ISSUER: https://knooppunt-vektis.nuts-services.nl
  NUTS_CREDENTIALPROFILES_0_TYPE: HealthcareProviderTypeCredential

However, it only worked when I used it like this.

  NUTS_CREDENTIALPROFILES_ISSUER: https://knooppunt-vektis.nuts-services.nl
  NUTS_CREDENTIALPROFILES_TYPE: HealthcareProviderTypeCredential

I am using the main branch of nuts-admin tagged with v6.2.1. I tried to debug it but couldn't understand where the issue is. The koanf implementation seems correct.

[reinkrul]

Note that it should be HealthcareProviderRoleTypeCredential.

I haven't got time right now to look into the configuration issue. What I have configured (and works) in YAML is:

credentialprofiles:
    - type: HealthcareProviderRoleTypeCredential
      issuer: https://knooppunt-vektis.nuts-services.nl

[SimonVeldhuijzen]

Step 3.2: the payload type https://api.iknl.nl/docs/pzp/r4/CapabilityStatement/ACP-CapabilityStatementProvider is not yet added to the payload types

[bramwesselo]

@SimonVeldhuijzen where did you got/see this CapabilityStatement-link?

[Dirklectisch]

This has been added now. ✅

[SimonVeldhuijzen]

Steps 0.4 and 0.5: This is for the data-user, not the data-holder

[Dirklectisch]

I think this is correct and I made the change in the script. ✅

[SimonVeldhuijzen]

Step 2: we have only one URA on development, so we can only support one role

[Dirklectisch]

For this test it won't be a problem as the script doesn't require you to change roles. However we should take this up in the development team. It seems to me the current setup doesn't allow to gracefully handle multiple roles in one wallet so effectively you would need a Nuts subject per role and duplicate all organisation level credentials between those wallets.

[Dirklectisch]

Created a ticket here: nuts-foundation/nuts-knooppunt#384

[SimonVeldhuijzen]

Step 3.3: missing link to the policy

[Dirklectisch]

@SimonVeldhuijzen I think we should probably add this to step 0 instead of step 3 right as both data holder and data user will need to load the policy into their nuts node?

[SimonVeldhuijzen]

3.4: Example:

POST /fhir/Patient/_search

Header: Content-Type = x-www-form-urlencoded (zie https://www.hl7.org/fhir/http.html#search-post)
Body: identifier=[http://fhir.nl/fhir/NamingSystem/bsn|{bsn}](http://fhir.nl/fhir/NamingSystem/bsn%7C%7Bbsn%7D)

[Dirklectisch]

Added this example to the content. Thanks! ✅

[edwinrozendom]

3.8:

• the MITZ-Gegevenscategorie that the data-holder can use is: GGC002

[Dirklectisch]

This code is currently hard coded in the Knooppunt PDP.

https://github.com/nuts-foundation/nuts-knooppunt/blob/main/component/pdp/mitz.go#L58

✅

[SimonVeldhuijzen]

Step 7.9: Data-user XIS does not display Patient and Consent resource, and informs the user that access was denied

[Dirklectisch]

Check ✅

[reinkrul]

@edwindoit @jorritspee
Regarding the revocation steps;

• The URL at which the (fake) Vektis issuer admin can revoke credentials is the following: https://knooppunt-test.nuts-services.nl/nuts-admin/#/vc/issuer
  • Click on a credential to show its details, then hit the red "revoke" button at the bottom of the page
  • Should probably add it to the script (step 6.1)
• The script will end at step 7.3 (access token request), because the data holder won't issue an access token if one of the credentials has been revoked.
  • Remove step 7.4 to 7.7 (token introspection)
  • Data holder should report that the credential is revoked

[jorritspee]

Processed ✅

[SimonVeldhuijzen]

During the hackaton the PDP didn't yet work when gathering the TreatmentDirective. Is that fixed now? What call should we do to the PDP to authorize the call to the TreatmentDirective?

[Dirklectisch]

Just tested it out this PDP call works for me. You can either pass the BSN in or configure Knooppunt to fetch in from a FHIR PIP. We discussed during the hackathon reworking that functionality to not use FHR but haven't done anything on that since.

POST http://localhost:8081/pdp/v1/data/knooppunt/authz
Content-Type: application/json

{
  "input": {
    "subject": {
      "properties": {
        "subject_id": "900030757",
        "subject_role": "01.015",
        "subject_organization_id": "00000025",
        "subject_facility_type": "V5",
        "client_qualifications": [
          "pzp_gf"
        ]
      }
    },
    "request": {
      "method": "GET",
      "protocol": "HTTP/1.0",
      "path": "/Consent",
      "query_params": {
        "patient": ["Patient/1299837"],
        "scope": ["http://terminology.hl7.org/CodeSystem/consentscope|treatment"],
        "category": ["http://snomed.info/sct|129125009"],
        "_include": ["Consent:actor"]
      }
    },
    "context": {
      "data_holder_organization_id": "90000697",
      "data_holder_facility_type": "Z3",
      "connection_type_code": "hl7-fhir-rest",
      "patient_bsn": "900214181"
    }
  }
}