Nærværende dokument udgør udviklervejledningen for EAS (EHMI AdresseringsService). EAS fungerer som opslagsservice, som baseret på forskellige parametre kan fremsøge modtagere på EHMI-netværket.
Komponenten er udviklet som en Java-applikation baseret på HAPI FHIR Plain Server og understøttes på JBoss Application Server version 8 (Wildfly). Komponenten integrerer til PersonInformation, SikredeInformation, SORES og EER.
Projektet bygges ved at udføre en af disse:
mvn clean package
eller via nspbuilder:
docker run --rm -it -v "$PWD":/workspace -w /workspace -e revision="snapshot" registry.nspop.dk/tools/nspbuilder:4.0.3 mvn -B -Drevision=snapshot clean install
Derefter kan EAS-servicen startes ved at skifte til compose/development og køre:
docker-compose up --build
Når EAS-servicen er startet lokalt, kan servicens operationer (jf. OperationDefinitions i EAS implementation guiden) tilgås på følgende URL'er:
http://localhost:8081/eas/fhir/Organization/$getListOfGpByPostalCode
http://localhost:8081/eas/fhir/Organization/$getReceivingOrganizationByGPId
http://localhost:8081/eas/fhir/Organization/$getReceivingOrganizationByPatientId
http://localhost:8081/eas/fhir/Organization/$getReceivingOrganizationBySORId
Eksemplerne fra implementation guiden kan benyttes som input, fx således (NB: uden Authorization header):
curl -X POST 'http://localhost:8081/eas/fhir/Organization/$getReceivingOrganizationBySORId' \
-H 'Content-Type: application/fhir+json' \
-H 'Accept: application/fhir+json' \
-d '{
"resourceType" : "Parameters",
"id" : "EX-GetReceivingOrganizationBySORId-Request",
"parameter" : [
{ "name" : "sorId", "valueString" : "12345678" },
{ "name" : "messageType", "valueString" : "XDIS92" }
]
}'
Hele servicelandskabet i EHMI, (EHMI-SIK), er tiltænkt at køre med mutual TLS - fremover mTLS.
For at abstrahere håndteringen af dette væk fra selve kerneservicen anvendes dedikerede ingress og egress services til mTLS.
Udover at TLS terminere, forwarder den hhv. klientcertifikatet og JWT token mod EAS kerneservicen.
Derved opnåes, at selve kompleksiteten med mTLS er håndteret i ingress laget, mens applikationen selv kan håndtere authentication og validere Proof of Possession af JWT token.
Dette gøres i applikationen ved at sammenholde SHA256 thumbprint af det forwarded klientcertifikat mod cnf claim i JWT token.
ingress-nginx
Lytter på port 8079 og forwarder til 443 internt for nginx.
I udvikling er der oprettet nogle self-signed certifikater for domænenavnet eas.local
Disse er mounted via. docker compose ind i:
For at domænenavnet eas.local kan resolves lokalt, skal følgende tilføjes til hostfilen på udviklermaskinen:
127.0.0.1 eas.local
For at nginx kan validere det anvendte klientcertifikat ved mTLS skal den offentlige del af den udstedende certifikatmyndighed mountes ind i følgende mappe i nginx:
NOTE: samme certifikatmyndighed skal være at finde for kerneservicen i EAS - dog pakket ind i en java key store, jks, fil. For konfiguration heraf.... TODO.. - Yderligere information om access-handler NSP Access Handler - Driftvejledning#jtph.properties
Samme princip gør sig gældende for egress service som ingress. At abstrahere håndtering og kompleksiteten af mTLS væk fra kerneapplikationen og ud i et andet lag.
På grund af begrænsninger i nginx, at der kun kan defineres dns resolver på top-niveau, vil det anbefales at konfigurerer en egress nginx pr. netværkssegmentering.
F.eks. en egress der kan resolve services på sundhedsdatanettet, mens en anden egress service der har dns resolver konfigureret til - hvad end behovet er. (Det er muligt at sætte flere DNS ind i nginx, men de vil blive kaldt i round-robin https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver, så den ene segmentering vil altid fejle i første hug)
NOTE: Egress er kun udadgående mod andre beskyttede services. Internt på NSP kaldes direkte via en httpklient fra EAS kerneservicen.
egress-ehmi-authserver
Egress mod keycloak server. På nuværende tidspunkt mod KIT Test Keycloak.
Lytter internt på port 3128. Tanken er, at servicen kun skal eksponeres internt fra netværket. I udvikling er der dog åbnet op på port 8888 for at teste egress af manuelt.
Klientcertifikat til at kalde ud med skal mountes ind på følgende placering:
Hvis aftagers certifikat ikke er udstedt af en af de gængse eksisterende certifikatmyndigheder skal servicen konfigureres til at stole på denne.
Dette gøres ved at CA ind på:
/etc/ssl/certs/ca-certificates.crt
Alternativt en anden placering for ikke at overskrive eksisterende CA bundle. Så skal config dog rettes.
Dette er dog ikke nødvendigt for nu, da certifikatmyndighed for KIT Test Keycloak er at finde i standard CA bundle.
TODO
EAS implementation guiden indeholder "operation definitions" svarende til FHIR-operationerne i EAS-servicen. Når der tilføjes nye services i EAS, vil der optræde automatisk genererede operation definitions i /fhir/metadata-endpointet. Der findes ikke funktionalitet (annotations) til at berige de auto-genererede operation definitions med alle elementer, der normalt er ønskelige i implementation guiden. Derfor bør der ske følgende berigelser før tilføjelse til IG'en:
Implementation guiden, som skal ajourføres med nye OperationDefinitions, findes her: https://github.com/medcomdk/dk-ehmi-eas. Opdateringer udføres ved at lave et fork, og lave pull requests derfra, hvorefter man skriver til ehmi@medcom.dk og beder om godkendelse.