ohif-viewer/docs/latest/deployment/recipes/user-account-control.md

User Account Control

DISCLAIMER! We make no claims or guarantees of this approach's security. If in doubt, enlist the help of an expert and conduct proper 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 sensitive data.

Overview

This guide builds on top of our Nginx + Image Archive guide, wherein we used a reverse proxy to retrieve resources from our image archive (Orthanc).

To add support for "User Account Control" we introduce Keycloak. Keycloak is an open source Identity and Access Management solution that makes it easy to secure applications and services with little to no code. We improve upon our reverse proxy setup by integrating Keycloak and Nginx to create an authenticating reverse proxy.

An authenticating reverse proxy is a reverse proxy that only retrieves the resources on behalf of a client if the client has been authenticated. If a client is not authenticated they can be redirected to a login page.

This setup allows us to create a setup similar to the one pictured below:

{% include "./../_user-account-control-flow-diagram.md" %}

• All web requests are routed through nginx on our OpenResty image
• /pacs is a reverse proxy for orthanc's DICOM Web endpoints
  • Requires valid Authorization: Bearer <token> header
• /pacs-admin is a reverse proxy for orthanc's Web Admin
• /auth is a reverse proxy for keycloak
• All static resources for OHIF Viewer are unprotected and accessible. We have application logic that will redirect unauthenticated users to the appropriate keycloak login screen.

Getting Started

Requirements

• Docker
  • Docker for Mac
  • Docker for Windows

Not sure if you have docker installed already? Try running docker --version in command prompt or terminal

Setup

Spin Things Up

• Navigate to <project-root>/docker/OpenResty-Orthanc-Keycloak in your shell
• Run docker-compose up

Create Your First User

• Navigate to: http://127.0.0.1/auth/admin
• Sign in with: admin/password
• From the top left dropdown, select the Ohif realm (it should say Master)
• From the left sidebar, under Manage, select Users
• Click Add User
  • Username: test
  • Email Verified: ON
  • Click Save
• Click the Credentials Tab
  • New Pasword: test
  • Password Confirmation: test
  • Temporary: OFF
  • Click: Reset Password
• From the top right dropdown, select Admin, then Sign Out

Sign In

• Navigate to http://127.0.0.1/
• Username: test, Password: test
• Click Log In

Upload Your First Study

• Navigate to http://127.0.0.1/pacs-admin
• If you're not already logged in, use test/test
• From the top right, select "Upload"
• Click "Select files to upload..." (DICOM)
• Click "Start the upload"
• Navigate back to http://127.0.0.1/ to view your studies in the Study List

Troubleshooting

Exit code 137

This means Docker ran out of memory. Open Docker Desktop, go to the advanced tab, and increase the amount of Memory available.

Cannot create container for service X

Use this one with caution: docker system prune

X is already running

Stop running all containers:

• Win: docker ps -a -q | ForEach { docker stop $_ }
• Linux: docker stop $(docker ps -a -q)

Configuration

After verifying that everything runs with default configuration values, you will likely want to update:

• The domain: http://127.0.0.1
• Set secure, non-default passwords
• Regenerate Keycloak Client Secrets

OHIF Viewer

The OHIF Viewer's configuration is imported from a static .js file and made available globally at window.config. The configuration we use is set to a specific file when we build the viewer, and determined by the env variable: REACT_APP_CONFIG. You can see where we set its value in the dockerfile for this solution:

ENV REACT_APP_CONFIG=config/docker_openresty-orthanc-keycloak.js

You can find the configuration we're using here: /public/config/docker_openresty-orthanc-keycloak.js

To rebuild the webapp image created by our dockerfile after updating the Viewer's configuration, you can run:

• docker-compose build OR

• docker-compose up --build

• Env vars in Nginx

Authentication Flow

• Keycloak JavaScript Adapter
  • Not used, as to not lock vendor
• oidc-client-js
• Diagrams of OpenID Connect Flows
• KeyCloak: OpenID Connect Flows
  • Good description on SSO Protocols
• Lua Resty Openidc Docs

Create a new "Client" in Keycloak

• What is a realm?

• What is a client?

• OAuth 2.0 and implict flow; why?

• Can we set all of this up via config instead of manual?

• Navigate to http://127.0.0.1/auth/admin/ in your browser. You should see:

• Sign in with admin/password
• Configure: Clients --> Create Client
  • ClientID: pacs
  • Client Protocol: openid-connect
  • Click "save"

Rebuild Client

• Set in config/nginx.conf?
  • Env variable???
  • 2dc6244a-1cba-4dbd-b3d6-f7409c2f68b3
• stop, docker-compose up

How it works

reverse proxy

A reverse proxy is a type of proxy server that retrieves resources on behalf of a client from one or more servers. The resources from these servers are returned to the client as if they originate from the Web server itself.

OpenResty

OpenResty® is a full-fledged web platform that integrates the standard Nginx core, LuaJIT, many carefully written Lua libraries, lots of high quality 3rd-party Nginx modules, and most of their external dependencies. It is designed to help developers easily build scalable web applications, web services, and dynamic web gateways.

Lua Nginx Module access_by_lua_block

Next Steps

Deploying to Production

While these configuration and docker-compose files model an environment suitable for production, they are not easy to deploy "as is". You can either:

• Manually recreate this environment and deploy built application files OR
• Deploy to a cloud kubernetes provider like Digital Ocean OR
  • See a full list of cloud providers here
• Find and follow your preferred provider's guide on setting up swarms and stacks

Add SSL

Adding SSL registration and renewal for your domain with Let's Encrypt that terminates at Nginx is an incredibly important step toward securing your data. Here are some resources, specific to this setup, that may be helpful:

• lua-resty-auto-ssl
• Let's Encrypt + Nginx

While we terminate SSL at Nginx, it may be worth using self signed certificates for communication between services.

• SSL Termination for TCP Upstream Servers

Use PostgresSQL w/ Orthanc

Orthanc can handle a large amount of data and requests, but if you find that requests start to slow as you add more and more studies, you may want to configure your Orthanc instance to use PostgresSQL. Instructions on how to do that can be found in the Orthanc Server Book, under "PostgreSQL and Orthanc inside Docker"

Resources

Misc. Helpful Commands

Check if nginx.conf is valid:

docker run --rm -t -a stdout --name my-openresty -v $PWD/config/:/usr/local/openresty/nginx/conf/:ro openresty/openresty:alpine-fat openresty -c /usr/local/openresty/nginx/conf/nginx.conf -t

Interact w/ running container:

docker exec -it CONTAINER_NAME bash

List running containers:

docker ps

Clear Keycloak DB so you can re-seed values:

• docker volume prune OR
• docker volume ls and docker volume rm VOLUME_NAME VOLUME_NAME

Referenced Articles

The inspiration for our setup was driven largely by these articles:

• Securing Nginx with Keycloak
• Authenticating Reverse Proxy with Keycloak
• Securing APIs with Kong and Keycloak

For more documentation on the software we've chosen to use, you may find the following resources helpful:

• Clientside library we use to manage OpenID-Connect implicit flow
• Orthanc for Docker
• OpenResty Guide
• Lua Ngx API
• Auth0: Picking a Grant Type