From 80ba22aba28fe7c66c4a92835cbacb0654f95e0b Mon Sep 17 00:00:00 2001
From: Kerry <kerrya@element.io>
Date: Fri, 20 Oct 2023 12:56:18 +1300
Subject: [PATCH] OIDC: document config (#26400)

* document OIDC config

* tidy
---
 docs/SUMMARY.md |  1 +
 docs/oidc.md    | 43 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 44 insertions(+)
 create mode 100644 docs/oidc.md

diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index 00a81e9e41..7670cd3f53 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -36,3 +36,4 @@
 -   [Memory profiling](memory-profiles-and-leaks.md)
 -   [Jitsi](jitsi-dev.md)
 -   [Feature flags](feature-flags.md)
+-   [OIDC and delegated authentication](oidc.md)
diff --git a/docs/oidc.md b/docs/oidc.md
new file mode 100644
index 0000000000..34387f9241
--- /dev/null
+++ b/docs/oidc.md
@@ -0,0 +1,43 @@
+# OIDC and delegated authentication
+
+## Compatibility/OIDC-aware mode
+
+[MSC2965: OIDC provider discovery](https://github.com/matrix-org/matrix-spec-proposals/pull/2965)
+[MSC3824: OIDC aware clients](https://github.com/matrix-org/matrix-spec-proposals/pull/3824)
+This mode uses an SSO flow to gain a `loginToken` from the authentication provider, then continues with SSO login.
+Element Web uses [MSC2965: OIDC provider discovery](https://github.com/matrix-org/matrix-spec-proposals/pull/2965) to discover the configured provider.
+Wherever valid MSC2965 configuration is discovered, OIDC-aware login flow will be the only option offered.
+
+## (🧪Experimental) OIDC-native flow
+
+Can be enabled by a config-level-only setting in `config.json`
+
+```json
+{
+    "features": {
+        "feature_oidc_native_flow": true
+    }
+}
+```
+
+See https://areweoidcyet.com/client-implementation-guide/ for implementation details.
+
+Element Web uses [MSC2965: OIDC provider discovery](https://github.com/matrix-org/matrix-spec-proposals/pull/2965) to discover the configured provider.
+Where OIDC native login flow is enabled and valid MSC2965 configuration is discovered, OIDC native login flow will be the only login option offered.
+Element Web will attempt to [dynamically register](https://openid.net/specs/openid-connect-registration-1_0.html) with the configured OP.
+Then, authentication will be completed [as described here](https://areweoidcyet.com/client-implementation-guide/).
+
+#### Statically configured OIDC clients
+
+Clients that are already registered with the OP can configure their `client_id` in `config.json`.
+Where static configuration exists for the OP dynamic client registration will not be attempted.
+
+```json
+{
+    "oidc_static_clients": {
+        "https://dummyoidcprovider.com/": {
+            "client_id": "abc123"
+        }
+    }
+}
+```