From c8f3c3af6c758368747ffe346452f866f73e8494 Mon Sep 17 00:00:00 2001
From: dannyrb <danny.ri.brown@gmail.com>
Date: Wed, 8 May 2019 23:37:45 -0400
Subject: [PATCH] Add reusable diagram

---
 .../_user-account-control-flow-diagram.md     |  4 ++
 .../recipes/user-account-control.md           | 42 ++++++++++++++-----
 2 files changed, 35 insertions(+), 11 deletions(-)
 create mode 100644 docs/latest/deployment/_user-account-control-flow-diagram.md

diff --git a/docs/latest/deployment/_user-account-control-flow-diagram.md b/docs/latest/deployment/_user-account-control-flow-diagram.md
new file mode 100644
index 000000000..b6937cd6b
--- /dev/null
+++ b/docs/latest/deployment/_user-account-control-flow-diagram.md
@@ -0,0 +1,4 @@
+<div style="text-align: center;">
+  <img src="/assets/img/user-access-control-request-flow.png" alt="request flow example" style="margin: 0 auto;" />
+  <div><i>simplified request flow diagram</i></div>
+</div>
diff --git a/docs/latest/deployment/recipes/user-account-control.md b/docs/latest/deployment/recipes/user-account-control.md
index c496f8fbf..3f894e8c4 100644
--- a/docs/latest/deployment/recipes/user-account-control.md
+++ b/docs/latest/deployment/recipes/user-account-control.md
@@ -15,9 +15,9 @@ sensitive data.
 ## Overview
 
 This guide builds on top of our
-[Nginx + Orthanc guide](/deployment/recipes/nginx--image-archive.md), wherein we
-used a [`reverse proxy`](https://en.wikipedia.org/wiki/Reverse_proxy) to
-retrieve resources from our image archive (Orthanc).
+[Nginx + Image Archive guide](/deployment/recipes/nginx--image-archive.md),
+wherein we used a [`reverse proxy`](https://en.wikipedia.org/wiki/Reverse_proxy)
+to retrieve resources from our image archive (Orthanc).
 
 To add support for "User Account Control" we introduce
 [Keycloak](https://www.keycloak.org/about.html). Keycloak is an open source
@@ -30,14 +30,22 @@ applications and services with little to no code. We improve upon our
 > 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...
+This setup allows us to create a setup similar to the one pictured below:
 
-> https://www.nginx.com/blog/authenticating-users-existing-applications-openid-connect-nginx-plus/
+{% include "./../_user-account-control-flow-diagram.md" %}
 
-_Keycloak validates user identity using OAuth 2.0 and OpenID Connect for
-Google-based SSO_
+- 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.
 
-## Requirements
+## Getting Started
+
+### Requirements
 
 - Docker
   - [Docker for Mac](https://docs.docker.com/docker-for-mac/)
@@ -46,13 +54,27 @@ Google-based SSO_
 _Not sure if you have `docker` installed already? Try running `docker --version`
 in command prompt or terminal_
 
-## Getting Started
+### Spinning Things Up
 
 1. Navigate to `<project-root>/docker/OpenResty-Orthanc-Keycloak` in your shell
 2. Run `docker volume create --name=keycloak_postgres_data`
 3. Run `docker-compose build`
 4. Run `docker-compose up`
 
+### Configuration
+
+- [Env vars in Nginx](https://blog.doismellburning.co.uk/environment-variables-in-nginx-config/)
+
+### Authentication Flow
+
+- [Keycloak JavaScript Adapter](https://www.keycloak.org/docs/latest/securing_apps/index.html#_javascript_adapter)
+  - Not used, as to not lock vendor
+- [oidc-client-js](https://github.com/IdentityModel/oidc-client-js/wiki)
+- [Diagrams of OpenID Connect Flows](https://medium.com/@darutk/diagrams-of-all-the-openid-connect-flows-6968e3990660)
+- [KeyCloak: OpenID Connect Flows](https://www.keycloak.org/docs/latest/securing_apps/index.html#authorization-code)
+  - [Good description on SSO Protocols](https://www.keycloak.org/docs/2.5/server_admin/topics/sso-protocols/oidc.html)
+- [Lua Resty Openidc Docs](https://github.com/zmartzone/lua-resty-openidc)
+
 ### Create a new "Client" in Keycloak
 
 - What is a realm?
@@ -99,8 +121,6 @@ in command prompt or terminal_
   - `2dc6244a-1cba-4dbd-b3d6-f7409c2f68b3`
 - stop, `docker-compose up`
 
-### Configuration
-
 ## How it works
 
 _reverse proxy_