summary: Comprehensive guide for implementing user authentication in OHIF using Keycloak, covering setup with both Orthanc and DCM4CHEE, configuration with OAuth2 proxy, SSL implementation, and detailed steps for local and production deployment scenarios.
DISCLAIMER: We make no claims or guarantees regarding the security of this approach. If you have any doubts, please consult an expert and conduct thorough audits.
:::
Making a viewer and its medical imaging data accessible on the open web can
provide a lot of benefits, but requires additional security to make sure
sensitive information can only be viewed by authorized individuals. Most image
archives are equipped with basic security measures, but they are not
robust/secure enough for the open web.
This guide covers one of many potential production setups that secure our
- Acts as a reverse proxy server that handles incoming requests to the domain (mydomain.com:80) and forwards them to the appropriate backend services.
- It also ensures that all requests go through the OAuth2 Proxy for authentication.
**OAuth2 Proxy:**
- Serves as an intermediary that authenticates users via OAuth2.
- Works in conjunction with Keycloak to manage user sessions and authentication tokens.
- Once the user is authenticated, it allows access to specific routes (/ohif-viewer, /pacs, /pacs-admin).
**Keycloak:**
- An open-source identity and access management solution.
- Manages user identities, including authentication and authorization.
- Communicates with the OAuth2 Proxy to validate user credentials and provide tokens for authenticated sessions.
**OHIF Viewer:**
- Hosted under the route /ohif-viewer, which serves the static assets of the OHIF Viewer.
**Orthanc/DCM4chee:**
- PACS (Picture Archiving and Communication System) for managing medical imaging data.
Exposes two routes:
- /pacs: Accesses the DICOM web services.
- /pacs-admin: Provides administrative and explorer interfaces.
## Getting Started - Orthanc
### Requirements
- Docker
- [Docker for Mac](https://docs.docker.com/docker-for-mac/)
- [Docker for Windows](https://docs.docker.com/docker-for-windows/)
_Not sure if you have `docker` installed already? Try running `docker --version`
in command prompt or terminal_
### Setup 1 - Trying Locally
Navigate to the Orthanc Keycloak configuration directory:
`cd platform\app\.recipes\Nginx-Orthanc-Keycloak`
Due to the increased complexity of this setup, we've introduced a magic word `YOUR_DOMAIN`. Replace this word with your project IP address to follow along more easily.
Since we are running this locally, we will use `127.0.0.1` as our IP address.
In the `docker-compose.yml` file, replace `YOUR_DOMAIN` with `127.0.0.1`.
Finally, in the docker-nginx-orthanc-keycloak config file that lives in `platform/app/public/config/docker-nginx-orthanc-keycloak.js`, replace `YOUR_DOMAIN` with
Before:
```
wadoUriRoot: 'http://YOUR_DOMAIN/pacs',
qidoRoot: 'http://YOUR_DOMAIN/pacs',
wadoRoot: 'http://YOUR_DOMAIN/pacs',
```
After:
```
wadoUriRoot: 'http://127.0.0.1/pacs',
qidoRoot: 'http://127.0.0.1/pacs',
wadoRoot: 'http://127.0.0.1/pacs',
```
:::note
This is the config that is used inside the dockerfile to build the viewer, look at dockerfile
Now that you have successfully set up Orthanc with Keycloak and OHIF locally, you can deploy it to a server. While you can rent a server from any provider, this tutorial will demonstrate the process using Linode as an example.
You can watch the following video, which will guide you through the process.
Some notes:
- Since this is a remote machine we need to clone the repo
- Typically a Linux machine, you need to download and install Docker on it
- Use the Visual Studio Code Remote SSH extension to connect to the server
- Use docker extension in Visual Studio Code to manage the containers
- The public IP address of the server now becomes the YOUR_DOMAIN and is used in the configuration files.
Still we have not set up SSL, so we will use HTTP instead of HTTPS.
We should use the same one server configuration as we did locally for Nginx (but with the new server IP address)
:::info
Don't forget to change the `docker-ngix-orthanc-keycloak.js` file to use the new server IP address.
:::
After you run `docker compose up --build` you can navigate to the server IP address and see the viewer will not work...
We have encountered some strange issues with the Keycloak service not allowing non-HTTPS connections (around 10:00). To resolve this, we need to modify the Keycloak configuration to permit HTTPS. This requires accessing the container and making the necessary changes.
Don't forget to replace `YOUR_DOMAIN` with the new domain name in the `docker-nginx-orthanc-keycloak.js` file.
:::info
Remember to include `https://` when adding the domain name to the configurations.
:::
Now, we need to add a certificate. Let's assume we have the domain name `hospital.duckdns.org` and the email we registered with DuckDNS is `your_email@example.com`.
```
docker run -it --rm --name certbot \
-v ./config/letsencrypt:/etc/letsencrypt \
-v ./config/certbot:/var/www/certbot \
-p 80:80 \
certbot/certbot certonly \
--standalone \
--preferred-challenges http \
--email your_email@example.com \
--agree-tos \
--no-eff-email \
-d hospital.duckdns.org
```
:::note
Replace "hospital.duckdns.org" with your domain name and update the email address accordingly.
:::
:::warning
DuckDNS is suitable for testing and demonstration purposes only. For production environments, use a proper domain name and SSL certificate to ensure security.
:::
If you follow these steps, you'll encounter the error `invalid parameter: redirect_uri` when attempting to log in to Keycloak. This occurs because the redirect URL isn't set up correctly in the Keycloak client configuration. To resolve this, we need to log in and adjust these settings.
Navigate to:
```
http://IP_ADDRESS/keycloak
```
Log in using the admin credentials:
- Username: `admin`
- Password: `admin`
Replace all IP addresses with the new domain name, using HTTPS.
You can follow the same steps as above to set up DCM4CHEE. The only difference is that you need to navigate to the correct directory. `platform\app\.recipes\Nginx-Dcm4chee-Keycloak`
You can watch the following video, which will guide you through the process of setting up DCM4CHEE.
This means the redirect URL isn't set up correctly in the Keycloak client configuration. To resolve this, log in to Keycloak and adjust the settings in the correct client (ohif_viewer) and correct realm (ohif).
_Exit code 137_
This means Docker ran out of memory. Open Docker Desktop, go to the `advanced`
