From ed27babeac74904bd11481e6be56413a6b805263 Mon Sep 17 00:00:00 2001 From: Kerry Archibald Date: Wed, 18 Oct 2023 16:23:52 +1300 Subject: [PATCH 1/2] document OIDC config --- docs/SUMMARY.md | 1 + docs/oidc.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 46 insertions(+) create mode 100644 docs/oidc.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 00a81e9e417..7670cd3f536 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 00000000000..3640f6fcb91 --- /dev/null +++ b/docs/oidc.md @@ -0,0 +1,45 @@ +# 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) +Produces compatibility sessions. +This mode uses an SSO-like 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 only setting in `config.json` + +```json +{ + "settings_defaults": { + "feature_oidc_native_flow": true + } +} +``` + +See https://areweoidcyet.com/client-implementation-guide/. + +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 `client_ids` 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" + } + } +} +``` From a01df5c5e36fe99c93cd0a450ecb12e38461ce6a Mon Sep 17 00:00:00 2001 From: Kerry Archibald Date: Thu, 19 Oct 2023 10:17:50 +1300 Subject: [PATCH 2/2] tidy --- docs/oidc.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/docs/oidc.md b/docs/oidc.md index 3640f6fcb91..34387f92413 100644 --- a/docs/oidc.md +++ b/docs/oidc.md @@ -4,34 +4,32 @@ [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) -Produces compatibility sessions. -This mode uses an SSO-like flow to gain a `loginToken` from the authentication provider, then continues with SSO login. +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 only setting in `config.json` +Can be enabled by a config-level-only setting in `config.json` ```json { - "settings_defaults": { + "features": { "feature_oidc_native_flow": true } } ``` -See https://areweoidcyet.com/client-implementation-guide/. +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. +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 `client_ids` in `config.json`. +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