Skip to content

Improve SSO/delegated authentication worker docs #19752

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
benbz wants to merge 4 commits into
base: develop
Choose a base branch
from
+11 −2
Open

Improve SSO/delegated authentication worker docs #19752

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
defd7c3
Highlight that some endpoints are only available in experimental MAS …
benbz May 5, 2026
06f007c
Fix endpoints handled by DeviceRestServlet and DevicesRestServlet
benbz May 5, 2026
f0d7eb8
Document stabilised delegated authentication workers
benbz May 5, 2026
f6b33b6
Highlight that the SSO paths aren't need if either form of delegated …
benbz May 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/19752.1.doc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Document the paths that can be handled on workers with stabilised delegated authentication.

@MadLittleMods MadLittleMods May 19, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this PR should be reviewed by someone else from @element-hq/mas-maintainers for accuracy.

I can't seem to select the team as a reviewer

1 change: 1 addition & 0 deletions changelog.d/19752.doc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Improve documentation around endpoints that can be enabled with MSC3861.

@MadLittleMods MadLittleMods May 19, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Where is this change spawning from? I assume you ran into this foot-gun somewhere

@benbz benbz May 20, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

element-hq/ess-helm#1278 and backlinks in both that issue and here

11 changes: 9 additions & 2 deletions docs/workers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -290,6 +290,9 @@ information.
# Unstable MSC4140 support
^/_matrix/client/unstable/org.matrix.msc4140/delayed_events(/.*/restart)?$

# Stabilised Delegated Authentication support (`matrix_authentication_service.enabled: true`)
^/_synapse/mas/
Comment on lines +293 to +294

@benbz benbz May 5, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Documented up here rather than next to the experimental_features.msc3861.enabled paths as AFAICT it can be handled by any worker rather than a worker with a single process only


Additionally, the following REST endpoints can be handled for GET requests:

# Push rules requests
Expand All @@ -314,7 +317,7 @@ for the room are in flight:

Additionally, the following endpoints should be included if Synapse is configured
to use SSO (you only need to include the ones for whichever SSO provider you're
using):
using) and delegated authentication isn't enabled:

@benbz benbz May 5, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've made the assertion here that none of these paths are useful in delegated auth world (be it experimental config or stabilised)


# for all SSO providers
^/_matrix/client/(api/v1|r0|v3|unstable)/login/sso/redirect
Expand Down Expand Up @@ -343,7 +346,11 @@ set to `true`), the following endpoints can be handled by the worker:
^/_synapse/admin/v2/users/[^/]+$
^/_synapse/admin/v1/username_available$
^/_synapse/admin/v1/users/[^/]+/_allow_cross_signing_replacement_without_uia$
^/_synapse/admin/v1/users/[^/]+/devices$
^/_synapse/admin/v2/users/[^/]+/devices(/|$)

Do note that these endpoints can't be handled by workers if the stabilised delegated
authentication support is enabled (`matrix_authentication_service.enabled` set to
`true`).
Comment on lines +351 to +353

@MadLittleMods MadLittleMods May 19, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How do you know?

Why is this the case?

@MadLittleMods MadLittleMods May 19, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

From #19752 (comment), it seems like it doesn't matter whether these are handled. It just isn't necessary.

Which means the phrasing of these updates should change. Or perhaps, isn't necessary to call this out at all. You can handle whatever with workers.

@benbz benbz May 20, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How do you know?

Why is this the case?

https://github.com/element-hq/synapse/pull/18759/changes#diff-21eb1b3b6455b7011ccbffc74b0279d87d5c69752d62d0196479b1bbc0bdbee3R274-R278 and discussion with @sandhose

From #19752 (comment), it seems like it doesn't matter whether these are handled. It just isn't necessary.

Which means the phrasing of these updates should change. Or perhaps, isn't necessary to call this out at all. You can handle whatever with workers.

My comment above is about the main block of paths. I think that the sentence I'm commenting is accurate and the additional assertion I've made (not useful with delegated auth) holds given Synapse won't be receiving any OIDC/SAML/CAS callbacks or doing any of the SSO dance.

These paths here can't be be put on a worker at all if the stabilised MAS configuration is used

@MadLittleMods MadLittleMods May 20, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These paths here can't be be put on a worker at all if the stabilised MAS configuration is used

I feel like it doesn't matter. As far as I know, when MAS is enabled, it disables all of the relevant endpoints.

@benbz benbz May 20, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

https://github.com/element-hq/synapse/blob/v1.153.0/synapse/rest/admin/__init__.py#L391-L401 these still appear enabled on workers with the experimental MAS configuration. Just not with the stable MAS configuration (or without MAS).


Note that a [HTTP listener](usage/configuration/config_documentation.md#listeners)
with `client` and `federation` `resources` must be configured in the
Expand Down
Loading