Improve the sample config for SSO (OIDC, SAML, and CAS) #8635

clokep · 2020-10-22T18:24:21Z

This has annoyed me for a while so I figured I'd fix it:

Better follows our guidelines for the sample config for the saml2_config section by avoid the double # #.
Rejiggers the generic SSO documentation out of the SAML2 docs since it applies for SAML / OIDC / CAS.
Adds some prose to our CAS documentation.
Standardizes some wording across SAML / OIDC / CAS.

clokep · 2020-10-22T18:25:46Z

synapse/config/cas.py

+          # It is possible to configure Synapse to only allow logins if CAS attributes
+          # match particular values. All of the keys in the mapping below must exist
+          # and the values must match the given value. Alternately if the given value
+          # is None then any value is allowed (the attribute just must exist).
+          # All of the listed attributes must match for the login to be permitted.


I cribbed this from the saml2_config.attribute_requirements section, but I think I updated it to make sense.

Unfortunately this has a reversed name and works slightly differently. 😢

clokep · 2020-10-23T14:27:42Z

synapse/config/cas.py

+          # The public URL of the homeserver.
+          #
+          #service_url: "https://homeserver.domain.com:8448"


I think this example is bad, the redirect and ticket endpoints are both registered as part of ClientRestResource, so I think the port being here is confusing?

(Changing the code to use public_baseurl is #7198.)

clokep · 2020-10-29T18:24:04Z

synapse/config/saml2_config.py

+        # Enable SAML2 for registration and login. Uses pysaml2.
+        #
+        # At least one of `sp_config` or `config_path` must be set in this section to
+        # enable SAML login.


I moved this section down since the bits above apply to all of the SSO code. I actually wonder if it should be part of the sso_config class and that should go before SAML/OIDC/CAS? 🤷

erikjohnston

I think this makes sense? I don't know if @richvdh would like to give it a once over.

richvdh

seems generally good to me.

Whenever we have this sort of thing I am reminded that having the example config and the default config be the same file is problematic.

richvdh · 2020-10-30T10:43:06Z

docs/sample_config.yaml

+  # Uncomment the following to enable authorization against a SAML server.
+  # Defaults to true, but is unused unless sp_config exists.
+  #
+  #enabled: true


this was omitted because it seemed to be redundant.

Yeah it is a little confusing. OIDC did the reasonable thing and defaults this to false unless it exists, so was trying to make it consistent. I can remove it if you'd like.

OIDC did the reasonable thing and defaults this to false unless it exists, so was trying to make it consistent

In the past, I've waged a bit of a war on enabled options: my feeling is that you should just omit the section if you don't want that functionality. So I'm not convinced that is the reasonable thing, and hence leaving the enabled setting undocumented here.

In short, I'd vote for leaving it undocumented.

"Reasonable" meaning that if it exists it should default to disabled. I'm OK removing this section though.

docs/sample_config.yaml

@dklimpel

Synapse 1.23.0 (2020-11-18) =========================== This release changes the way structured logging is configured. See the [upgrade notes](UPGRADE.rst#upgrading-to-v1230) for details. **Note**: We are aware of a trivially exploitable denial of service vulnerability in versions of Synapse prior to 1.20.0. Complete details will be disclosed on Monday, November 23rd. If you have not upgraded recently, please do so. Bugfixes -------- - Fix a dependency versioning bug in the Dockerfile that prevented Synapse from starting. ([\#8767](matrix-org/synapse#8767)) Synapse 1.23.0rc1 (2020-11-13) ============================== Features -------- - Add a push rule that highlights when a jitsi conference is created in a room. ([\#8286](matrix-org/synapse#8286)) - Add an admin api to delete a single file or files that were not used for a defined time from server. Contributed by @dklimpel. ([\#8519](matrix-org/synapse#8519)) - Split admin API for reported events (`GET /_synapse/admin/v1/event_reports`) into detail and list endpoints. This is a breaking change to #8217 which was introduced in Synapse v1.21.0. Those who already use this API should check their scripts. Contributed by @dklimpel. ([\#8539](matrix-org/synapse#8539)) - Support generating structured logs via the standard logging configuration. ([\#8607](matrix-org/synapse#8607), [\#8685](matrix-org/synapse#8685)) - Add an admin API to allow server admins to list users' pushers. Contributed by @dklimpel. ([\#8610](matrix-org/synapse#8610), [\#8689](matrix-org/synapse#8689)) - Add an admin API `GET /_synapse/admin/v1/users/<user_id>/media` to get information about uploaded media. Contributed by @dklimpel. ([\#8647](matrix-org/synapse#8647)) - Add an admin API for local user media statistics. Contributed by @dklimpel. ([\#8700](matrix-org/synapse#8700)) - Add `displayname` to Shared-Secret Registration for admins. ([\#8722](matrix-org/synapse#8722)) Bugfixes -------- - Fix fetching of E2E cross signing keys over federation when only one of the master key and device signing key is cached already. ([\#8455](matrix-org/synapse#8455)) - Fix a bug where Synapse would blindly forward bad responses from federation to clients when retrieving profile information. ([\#8580](matrix-org/synapse#8580)) - Fix a bug where the account validity endpoint would silently fail if the user ID did not have an expiration time. It now returns a 400 error. ([\#8620](matrix-org/synapse#8620)) - Fix email notifications for invites without local state. ([\#8627](matrix-org/synapse#8627)) - Fix handling of invalid group IDs to return a 400 rather than log an exception and return a 500. ([\#8628](matrix-org/synapse#8628)) - Fix handling of User-Agent headers that are invalid UTF-8, which caused user agents of users to not get correctly recorded. ([\#8632](matrix-org/synapse#8632)) - Fix a bug in the `joined_rooms` admin API if the user has never joined any rooms. The bug was introduced, along with the API, in v1.21.0. ([\#8643](matrix-org/synapse#8643)) - Fix exception during handling multiple concurrent requests for remote media when using multiple media repositories. ([\#8682](matrix-org/synapse#8682)) - Fix bug that prevented Synapse from recovering after losing connection to the database. ([\#8726](matrix-org/synapse#8726)) - Fix bug where the `/_synapse/admin/v1/send_server_notice` API could send notices to non-notice rooms. ([\#8728](matrix-org/synapse#8728)) - Fix PostgreSQL port script fails when DB has no backfilled events. Broke in v1.21.0. ([\#8729](matrix-org/synapse#8729)) - Fix PostgreSQL port script to correctly handle foreign key constraints. Broke in v1.21.0. ([\#8730](matrix-org/synapse#8730)) - Fix PostgreSQL port script so that it can be run again after a failure. Broke in v1.21.0. ([\#8755](matrix-org/synapse#8755)) Improved Documentation ---------------------- - Instructions for Azure AD in the OpenID Connect documentation. Contributed by peterk. ([\#8582](matrix-org/synapse#8582)) - Improve the sample configuration for single sign-on providers. ([\#8635](matrix-org/synapse#8635)) - Fix the filepath of Dex's example config and the link to Dex's Getting Started guide in the OpenID Connect docs. ([\#8657](matrix-org/synapse#8657)) - Note support for Python 3.9. ([\#8665](matrix-org/synapse#8665)) - Minor updates to docs on running tests. ([\#8666](matrix-org/synapse#8666)) - Interlink prometheus/grafana documentation. ([\#8667](matrix-org/synapse#8667)) - Notes on SSO logins and media_repository worker. ([\#8701](matrix-org/synapse#8701)) - Document experimental support for running multiple event persisters. ([\#8706](matrix-org/synapse#8706)) - Add information regarding the various sources of, and expected contributions to, Synapse's documentation to `CONTRIBUTING.md`. ([\#8714](matrix-org/synapse#8714)) - Migrate documentation `docs/admin_api/event_reports` to markdown. ([\#8742](matrix-org/synapse#8742)) - Add some helpful hints to the README for new Synapse developers. Contributed by @chagai95. ([\#8746](matrix-org/synapse#8746)) Internal Changes ---------------- - Optimise `/createRoom` with multiple invited users. ([\#8559](matrix-org/synapse#8559)) - Implement and use an `@lru_cache` decorator. ([\#8595](matrix-org/synapse#8595)) - Don't instansiate Requester directly. ([\#8614](matrix-org/synapse#8614)) - Type hints for `RegistrationStore`. ([\#8615](matrix-org/synapse#8615)) - Change schema to support access tokens belonging to one user but granting access to another. ([\#8616](matrix-org/synapse#8616)) - Remove unused OPTIONS handlers. ([\#8621](matrix-org/synapse#8621)) - Run `mypy` as part of the lint.sh script. ([\#8633](matrix-org/synapse#8633)) - Correct Synapse's PyPI package name in the OpenID Connect installation instructions. ([\#8634](matrix-org/synapse#8634)) - Catch exceptions during initialization of `password_providers`. Contributed by Nicolai Søborg. ([\#8636](matrix-org/synapse#8636)) - Fix typos and spelling errors in the code. ([\#8639](matrix-org/synapse#8639)) - Reduce number of OpenTracing spans started. ([\#8640](matrix-org/synapse#8640), [\#8668](matrix-org/synapse#8668), [\#8670](matrix-org/synapse#8670)) - Add field `total` to device list in admin API. ([\#8644](matrix-org/synapse#8644)) - Add more type hints to the application services code. ([\#8655](matrix-org/synapse#8655), [\#8693](matrix-org/synapse#8693)) - Tell Black to format code for Python 3.5. ([\#8664](matrix-org/synapse#8664)) - Don't pull event from DB when handling replication traffic. ([\#8669](matrix-org/synapse#8669)) - Abstract some invite-related code in preparation for landing knocking. ([\#8671](matrix-org/synapse#8671), [\#8688](matrix-org/synapse#8688)) - Clarify representation of events in logfiles. ([\#8679](matrix-org/synapse#8679)) - Don't require `hiredis` package to be installed to run unit tests. ([\#8680](matrix-org/synapse#8680)) - Fix typing info on cache call signature to accept `on_invalidate`. ([\#8684](matrix-org/synapse#8684)) - Fail tests if they do not await coroutines. ([\#8690](matrix-org/synapse#8690)) - Improve start time by adding an index to `e2e_cross_signing_keys.stream_id`. ([\#8694](matrix-org/synapse#8694)) - Re-organize the structured logging code to separate the TCP transport handling from the JSON formatting. ([\#8697](matrix-org/synapse#8697)) - Use Python 3.8 in Docker images by default. ([\#8698](matrix-org/synapse#8698)) - Remove the "draft" status of the Room Details Admin API. ([\#8702](matrix-org/synapse#8702)) - Improve the error returned when a non-string displayname or avatar_url is used when updating a user's profile. ([\#8705](matrix-org/synapse#8705)) - Block attempts by clients to send server ACLs, or redactions of server ACLs, that would result in the local server being blocked from the room. ([\#8708](matrix-org/synapse#8708)) - Add metrics the allow the local sysadmin to track 3PID `/requestToken` requests. ([\#8712](matrix-org/synapse#8712)) - Consolidate duplicated lists of purged tables that are checked in tests. ([\#8713](matrix-org/synapse#8713)) - Add some `mdui:UIInfo` element examples for `saml2_config` in the homeserver config. ([\#8718](matrix-org/synapse#8718)) - Improve the error message returned when a remote server incorrectly sets the `Content-Type` header in response to a JSON request. ([\#8719](matrix-org/synapse#8719)) - Speed up repeated state resolutions on the same room by caching event ID to auth event ID lookups. ([\#8752](matrix-org/synapse#8752)) Synapse 1.22.1 (2020-10-30) =========================== Bugfixes -------- - Fix a bug where an appservice may not be forwarded events for a room it was recently invited to. Broke in v1.22.0. ([\#8676](matrix-org/synapse#8676)) - Fix `Object of type frozendict is not JSON serializable` exceptions when using third-party event rules. Broke in v1.22.0. ([\#8678](matrix-org/synapse#8678))

clokep added 2 commits October 22, 2020 13:45

Follow our documentation guidelines for the SAML docs.

fb1cdb0

Rework the CAS sample config.

dc49fc4

clokep commented Oct 22, 2020

View reviewed changes

Add a newsfragment.

b8d010f

clokep requested a review from a team October 22, 2020 18:34

clokep self-assigned this Oct 22, 2020

clokep commented Oct 23, 2020

View reviewed changes

clokep commented Oct 29, 2020

View reviewed changes

erikjohnston approved these changes Oct 29, 2020

View reviewed changes

richvdh reviewed Oct 30, 2020

View reviewed changes

clokep changed the title ~~Add better sample config documentation for SAML and CAS~~ Improve the sample config for SSO (OIDC, SAML, and CAS) Oct 30, 2020

Review comments.

88a64f2

clokep merged commit 8f1aefa into develop Oct 30, 2020

clokep deleted the clokep/sso-config branch October 30, 2020 14:02

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve the sample config for SSO (OIDC, SAML, and CAS) #8635

Improve the sample config for SSO (OIDC, SAML, and CAS) #8635

clokep commented Oct 22, 2020

clokep Oct 22, 2020

clokep Oct 23, 2020

clokep Oct 29, 2020

erikjohnston left a comment

richvdh left a comment

richvdh Oct 30, 2020

clokep Oct 30, 2020

richvdh Oct 30, 2020

clokep Oct 30, 2020

Improve the sample config for SSO (OIDC, SAML, and CAS) #8635

Improve the sample config for SSO (OIDC, SAML, and CAS) #8635

Conversation

clokep commented Oct 22, 2020

clokep Oct 22, 2020

Choose a reason for hiding this comment

clokep Oct 23, 2020

Choose a reason for hiding this comment

clokep Oct 29, 2020

Choose a reason for hiding this comment

erikjohnston left a comment

Choose a reason for hiding this comment

richvdh left a comment

Choose a reason for hiding this comment

richvdh Oct 30, 2020

Choose a reason for hiding this comment

clokep Oct 30, 2020

Choose a reason for hiding this comment

richvdh Oct 30, 2020

Choose a reason for hiding this comment

clokep Oct 30, 2020

Choose a reason for hiding this comment