Page History

Indledning

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.

Opsætning af udviklingsmiljø

Projektet bygges ved at udføre en af disse:

...

docker run --rm -it -v "$PWD":/workspace -w /workspace -e revision="snapshot" registry.nspop.dk/tools/nspbuilder:4.0.35 mvn -B -Drevision=snapshot clean install

...

docker-compose up --build

IntelliJ IDEA

Hvis IntelliJ IDEA anvendes som IDE, så er der tilføjet to run configurations under .run mappen i roden af projektet.

• Start EAS Development - Bygger java moduler og docker images, samt opstarter development compose.
• Attach HAPI - Development compose konfiguration udstiller port 5005 som debugging port for HAPI FHIR servlet. Denne run konfiguration tilknytter debuggeren via. IntelliJ IDEA

Test

Når EAS-servicen er startet lokalt, kan servicens operationer (jf. OperationDefinitions i EAS implementation guiden) tilgås på følgende URL'er:

...

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" }
    ]
  }'

Ingress/Egress

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.

I Test1 og udvikling anvendes den gængse Testcertifikater der findes her NSP Test Identity Provider (NTIdP) - Leverancebeskrivelse under vedhæftninger.
For at lette setuppet for udviklere er lavet 2 shell scripts som klargører certifikaterne:

1. https://git.nspop.dk/projects/COM/repos/sundhedsadresseringsservice/browse/setup_keycloak_trust.sh?at=develop
2. https://git.nspop.dk/projects/COM/repos/sundhedsadresseringsservice/browse/setup_client_certificate.sh?at=develop

Disse scripts opsætter hhv. en Javakeystore med signeringscertifikatet fra Keycloak på Test1 (Inkl. hele certifikatkæden), samt opsætter klientcertifikater til anvendelse mod EAS og fra. EAS synspunkt mod EER.
Disse klientcertifikater er også indeholdende hele certifikatkæden.

For Keycloak trust henvises til information om access-handler NSP Access Handler - Driftvejledning#jtph.properties da konfiguration heraf er af NSP komponenten og sådan set ikke EAS.

De 2 scripts kan udføres via nspbuilder fra og med version 4.0.5:

docker run --rm -it -v "$PWD":/workspace -w /workspace -e revision="snapshot" registry.nspop.dk/tools/nspbuilder:4.0.5 ./setup_keycloak_trust.sh
docker run --rm -it -v "$PWD":/workspace -w /workspace -e revision="snapshot" registry.nspop.dk/tools/nspbuilder:4.0.5 ./setup_client_certificate.sh

Ingress

Udover at TLS terminereterminerer, 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.

...

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:

• /etc/ssl/ca.pem

...

Egress

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 

egress-ehmi-authserver

NOTE: Der skal nok laves 2 egress services - da DNS for reverse proxy nok er forskellig på SDN (keycloak) og EER (Er det på SDN?)

Release

NOTE:  Egress er kun udadgående mod andre beskyttede services. Internt på NSP kaldes direkte via en httpklient fra EAS kerneservicen.

egress-nginx

Egress for services i EHMI landskabet. På nuværende tidspunkt mod KIT Test Keycloak og KIT Test EER.

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.

Servicen udstiller i øjeblikket to reverse proxy paths:

• /ehmi-auth/
• /ehmi-eer/

Som eksempel vil følgende kald mod servicen http://egress-nginx:3128/ehmi-auth/auth/realms/ehmi/protocol/openid-connect/token blive transformeret til https://$ehmi_auth_host:443/auth/realms/ehmi/protocol/openid-connect/token hvor $ehmi_auth_host via. DNS bliver resolvet til en IP og HTTP Host header sættes tilsvarende til $ehmi_auth_host 

Samme gør sig gældende for /ehmi-eer/ blot med $ehmi_eer_host variablen istedet.

Klientcertifikat til at kalde ud med skal mountes ind på følgende placering for hhv. Auth og EER services:

• /etc/ssl/ehmi-auth/client.crt
• /etc/ssl/ehmi-auth/client.key
• /etc/ssl/ehmi-eer/client.crt
• /etc/ssl/ehmi-eer/client.key

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 mounte 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

Tilføjelse af Operation Definitions

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:

...