From c387b21b180b6074543aa7740b4833bc73629768 Mon Sep 17 00:00:00 2001
From: Luke Ness <luke.ness@okta.com>
Date: Wed, 10 May 2023 16:21:51 -0600
Subject: [PATCH 1/2] doc: adding flow diagrams for interactions

---
 docs/flows.md | 139 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 139 insertions(+)
 create mode 100644 docs/flows.md

diff --git a/docs/flows.md b/docs/flows.md
new file mode 100644
index 00000000..f9a725d5
--- /dev/null
+++ b/docs/flows.md
@@ -0,0 +1,139 @@
+# AD Server Interactions
+
+AD LDAP Connector helps facilitate proxied interactions to an LDAP server. The connector provides a set of
+APIs that mirrors the interactions with other connections e.g. Custom Database Connections.
+
+In the diagrams below the following names will be used to indicate the defined participants:
+
+- CIC: The environment of Okta CIC (Auth0) that is being interacted with
+- Connector: A running instance of the application defined in this repository
+- AD: An active directory implementation that is the backend for the Auth0 connection
+
+All three components act as servers, only the first two act as clients.
+
+## Boot
+
+### Client Instantiation
+
+```mermaid
+sequenceDiagram
+  Connector ->> AD : Create Connection
+  Connector ->> AD : Bind Connection
+  Note right of Connector: referred to as Client
+  Connector ->> AD : Create Connection
+  Note right of Connector: referred to as Binder
+```
+
+### Health Check
+
+```mermaid
+sequenceDiagram
+  Connector ->> AD : Create Connection
+  loop HealthCheck
+    Connector ->> AD : Bind Connection
+    Connector ->> AD : Search
+    Connector ->> Connector : Update Health
+  end
+```
+
+## HTTP Server
+
+- Source: [endpoints.js](endpoints.js)
+- Handled by Password WindowsAuthentication implementation:
+  - https://github.com/auth0/passport-windowsauth
+
+### Login
+
+- Endpoint: `/wsfed`
+
+### List Users
+
+- Endpoint: `/users`
+
+## Proxied Interactions
+
+- Source: [ws_validator.js](ws_validator.js)
+- Ingress: Websocket
+
+### Authenticate User
+
+- Event: `authenticate_user`
+- 
+```mermaid
+sequenceDiagram
+  Auth0 ->> Connector : Authenticate User
+  note right of Auth0 : Username, Password
+  Connector ->> AD : Search with Client
+  AD ->> Connector : User
+  alt if user found
+  Connector ->> AD : Bind with Binder
+  alt not successful
+  Connector ->> Auth0 : Error
+  else
+  alt if groups enabled
+  Connector ->> Connector : Check Cache
+  alt if cache empty
+  Connector ->> AD : Search with Client
+  AD ->> Connector : Groups
+  end
+  end
+  Connector ->> Auth0 : User
+  end
+  end
+```
+
+### Search Users
+
+- Event: `search_users`
+
+```mermaid
+sequenceDiagram
+  Auth0 ->> Connector : Search Users
+  Connector ->> AD : Search with Client
+  AD ->> Connector : Users
+  alt if groups enabled
+  Connector ->> Connector : Check Cache
+  alt if cache empty
+  Connector ->> AD : Search with Client
+  AD ->> Connector : Groups
+  end
+  end
+```
+
+### Change Password
+
+- Event: `change_password`
+
+```mermaid
+sequenceDiagram
+  Auth0 ->> Connector : Change Password
+  note right of Auth0 : Username, Password  
+  Connector ->> AD : Search
+  AD ->> Connector : Users
+  alt if user found
+  Connector ->> AD : Modify
+  alt if groups enabled
+  Connector ->> Connector : Check Cache
+  alt if cache empty
+  Connector ->> AD : Search with Client
+  AD ->> Connector : Groups
+  end
+  end
+  Connector ->> Connector : Create Profile
+  Connector ->> Auth0 : User
+  else
+  Connector ->> Auth0 : Error
+  end
+```
+
+### List Groups
+
+- Event: `list_groups`
+
+```mermaid
+sequenceDiagram
+  Auth0 ->> Connector : List Groups
+  Connector ->> AD : Search with Client
+  AD ->> Connector : Groups
+  Connector ->> Auth0 : Groups
+```

From 207bbb91a1023cf467a366deef4c8066743020e0 Mon Sep 17 00:00:00 2001
From: Luke Ness <gausnes@gmail.com>
Date: Tue, 29 Aug 2023 12:52:56 -0600
Subject: [PATCH 2/2] cleanup: removing extra dash

---
 docs/flows.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/docs/flows.md b/docs/flows.md
index f9a725d5..e5ca0124 100644
--- a/docs/flows.md
+++ b/docs/flows.md
@@ -58,7 +58,6 @@ sequenceDiagram
 ### Authenticate User
 
 - Event: `authenticate_user`
-- 
 ```mermaid
 sequenceDiagram
   Auth0 ->> Connector : Authenticate User