diff --git a/changelog.d/4-docs/plantuml b/changelog.d/4-docs/plantuml
new file mode 100644
index 0000000000..cb65f564c9
--- /dev/null
+++ b/changelog.d/4-docs/plantuml
@@ -0,0 +1 @@
+Extend docs to support render plantuml directly, rewrote the saml flow diagram in plantuml
diff --git a/docs/src/conf.py b/docs/src/conf.py
index 939c35ae68..352e744f5c 100644
--- a/docs/src/conf.py
+++ b/docs/src/conf.py
@@ -34,6 +34,7 @@
 # ones.
 extensions = [
     'sphinxcontrib.kroki',
+    'sphinxcontrib.plantuml',
     "myst_parser",
     'rst2pdf.pdfbuilder',
     'sphinx_multiversion',
diff --git a/docs/src/understand/single-sign-on/understand/Wire_SAML_Flow.png b/docs/src/understand/single-sign-on/understand/Wire_SAML_Flow.png
deleted file mode 100644
index 6efa902500..0000000000
Binary files a/docs/src/understand/single-sign-on/understand/Wire_SAML_Flow.png and /dev/null differ
diff --git a/docs/src/understand/single-sign-on/understand/main.md b/docs/src/understand/single-sign-on/understand/main.md
index 3192231755..068569ee47 100644
--- a/docs/src/understand/single-sign-on/understand/main.md
+++ b/docs/src/understand/single-sign-on/understand/main.md
@@ -147,7 +147,33 @@ Here is a blog post we like about how SAML works: <https://duo.com/blog/the-beer
 
 And here is a diagram that explains it in slightly more technical terms:
 
-```{image} Wire_SAML_Flow.png
+```{uml}
+@startuml
+
+title Wire SAML Authentication Flow
+hide footbox
+skinparam responseMessageBelowArrow true
+
+actor "**End User**\n(Mobile, Desktop, WebApp)" as user #a3d977
+entity "**Wire Server**" as wireserver #99d2f2
+entity "**Identity Provider**\n(IdP)" as idp #ffdf71
+
+user -> wireserver : User starts authentication in Wire
+wireserver -> user: HTTP POST to IdP w/auth request
+user -> idp : (HTML FORM redirect in browser)
+note right: Auth request is passed, verified
+
+idp --> idp: end user is sent to login page at IdP \n user logs in, or browser sends cookie
+
+...
+
+
+idp -> user: Redirect to Wire w/ SAML token
+note right: SAML token is generated
+user -> wireserver: (HTML FORM redirect in browser)
+wireserver -> user: User is logged into Wire
+
+@enduml
 ```
 
 Here is a critique of XML/DSig security (which SAML relies on): <https://www.cs.auckland.ac.nz/~pgut001/pubs/xmlsec.txt>
diff --git a/nix/default.nix b/nix/default.nix
index c377bf7102..6f75f4e105 100644
--- a/nix/default.nix
+++ b/nix/default.nix
@@ -26,6 +26,7 @@ let
 
   # packages necessary to build wire-server docs
   docsPkgs = [
+    pkgs.plantuml
     pkgs.texlive.combined.scheme-full
     (pkgs.python3.withPackages
       (ps: with ps; [
@@ -39,6 +40,7 @@ let
         sphinx-copybutton
         sphinxcontrib-fulltoc
         sphinxcontrib-kroki
+        sphinxcontrib-plantuml
       ]))
   ];