IRIS for Health FHIR Server SMART Scopes + Keycloak docker-compose demo

Preconditions

Add the following entry to your host’s hosts file:

127.0.0.1 keycloak

• Linux/macOS: /etc/hosts
• Windows: C:\Windows\System32\drivers\etc\hosts

This is required so that both:

• host tools (browser/Postman)
• containers (IRIS -> Keycloak)

use the exact same hostname, preventing issuer mismatch.

Run

From this directory:

docker compose up -d --build

When you see these kinds of lines in the output:

keycloak-init-1 | curl: (7) Failed to connect to keycloak port 8080 after 4 ms: Could not connect to server

Don’t worry as while the containers are starting up it will take some time for keycloak to answer.

Eventually you should see something like this:

keycloak-init-1 | [keycloak-init] Keycloak is reachable.

...

keycloak-init-1 exited with code 0

Expected URLs

Keycloak:

• http://keycloak:8080/keycloak

Issuer (must match exactly in discovery + tokens):

• http://keycloak:8080/keycloak/realms/fhir

IRIS for Health/FHIR Server (HTTPS via Web Gateway):

• https://localhost:8443/fhir/r4

(Direct IRIS Private Web Server remains on HTTP for debugging only:

• http://localhost:52773/csp/sys/UtilHome.csp )

Shared artifacts created at startup:

• shared/keycloak.iat
• shared/keycloak.ready
• shared/iris.client.json

Users and Passwords

IRIS

• SuperUser / SYS

Keycloak

• admin / admin

Postman Keycloak Authentication (see also below)

• alice / alice

Persistence (Durable %SYS + Keycloak dev-file)

This demo is configured so you can:

1. docker compose up --build
2. create FHIR resources / change config
3. docker compose down
4. docker compose up again

…and your IRIS data (including the FHIR repository) and Keycloak configuration will still be there.

How it works:

• IRIS durable %SYS: the IRIS instance data directory is redirected to a named volume using ISC_DATA_DIRECTORY=/dur/iris and iris_durable:/dur.
• Keycloak dev-file: Keycloak stores its dev database under /opt/keycloak/data, persisted via keycloak_data:/opt/keycloak/data.

To completely reset everything (destructive), remove the volumes:

docker compose down -v

Keycloak init scripts and non-destructive behavior

On startup, the keycloak-init container seeds the realm/user/scopes if missing. By default it does not reset the demo user’s password if the user already exists.

Postman (Authorization Code)

Authorization URL:

• http://keycloak:8080/keycloak/realms/fhir/protocol/openid-connect/auth

Token URL:

• http://keycloak:8080/keycloak/realms/fhir/protocol/openid-connect/token

Callback URL:

• https://oauth.pstmn.io/v1/callback

Scopes:

• openid profile email fhirUser user/Patient.rs user/Observation.rs?category=laboratory

User:

• alice / alice

FHIR call example:

• GET https://localhost:8443/fhir/r4/metadata
• Header: Authorization: Bearer <access_token>

Audience (aud) claim requirement

The IRIS for Health FHIR Server validates the access token audience (aud) against the request base URL (you’ll see Token aud failed validation in ^FSLOG if it doesn’t match).
Keycloak’s default access token audience is often account. This demo adds a Keycloak protocol mapper to the generated client so the access token includes:

• https://localhost:8443/fhir/r4

That mapper is configured by keycloak-postinit.sh.

If you still see aud validation failures:

• Re-run the Postman auth flow to get a new token after keycloak-postinit has completed.
• If your IRIS build expects aud as a single string (not an array), set AUD_MAPPER_MODE: "override" in docker-compose.yml under keycloak-postinit.

HTTPS for IRIS FHIR (required for Bearer tokens)

• Call FHIR over HTTPS so IRIS treats the request as secure (required for OAuth2 bearer tokens):
  • Base URL: https://localhost:8443/fhir/r4
• The certificate is self-signed (generated at Web Gateway container on first startup). Your browser/Postman will warn; accept the risk (browser) or disable SSL verification in Postman, or import the generated cert.
• Keycloak remains HTTP with issuer http://keycloak:8080/keycloak/realms/fhir.

webgateway healthcheck

I had to change the default healthcheck of the webgateway, because by default it made http requests which failed with a 404 (this didn’t harm the actual activity, but created many 404 log entries). See custom healthcheck in the docker compose file.