Remove deprecated SAML2 callback URL since it does not work. (#9434)

Updates documentation from #9289 and removes a deprecated
endpoint which didn't work as expected.

4 files changed, 16 insertions, 16 deletions

diff --git a/CHANGES.md b/CHANGES.md
index 9837710d06..9476fef72d 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -3,6 +3,8 @@ Synapse 1.xx.0 (2021-xx-xx)
 
 Note that this release drops support for ARMv7 in the official Docker images, due to repeated problems building for ARMv7 (and the associated maintenance burden this entails).
 
+This release also fixes the documentation included in v1.27.0 around the callback URI for SAML2 identity providers. If your server is configured to use single sign-on via a SAML2 IdP, you may need to make configuration changes. Please review [UPGRADE.rst](UPGRADE.rst) for more details on these changes.
+
 Removal warning
 ---------------
 
diff --git a/UPGRADE.rst b/UPGRADE.rst
index 22edfe0d60..6f628a6947 100644
--- a/UPGRADE.rst
+++ b/UPGRADE.rst
@@ -88,20 +88,21 @@ for example:
 Upgrading to v1.27.0
 ====================
 
-Changes to callback URI for OAuth2 / OpenID Connect
----------------------------------------------------
+Changes to callback URI for OAuth2 / OpenID Connect and SAML2
+-------------------------------------------------------------
 
-This version changes the URI used for callbacks from OAuth2 identity providers. If
-your server is configured for single sign-on via an OpenID Connect or OAuth2 identity
-provider, you will need to add ``[synapse public baseurl]/_synapse/client/oidc/callback``
-to the list of permitted "redirect URIs" at the identity provider.
+This version changes the URI used for callbacks from OAuth2 and SAML2 identity providers:
 
-See `docs/openid.md <docs/openid.md>`_ for more information on setting up OpenID
-Connect.
+* If your server is configured for single sign-on via an OpenID Connect or OAuth2 identity
+  provider, you will need to add ``[synapse public baseurl]/_synapse/client/oidc/callback``
+  to the list of permitted "redirect URIs" at the identity provider.
 
-(Note: a similar change is being made for SAML2; in this case the old URI
-``[synapse public baseurl]/_matrix/saml2`` is being deprecated, but will continue to
-work, so no immediate changes are required for existing installations.)
+  See `docs/openid.md <docs/openid.md>`_ for more information on setting up OpenID
+  Connect.
+
+* If your server is configured for single sign-on via a SAML2 identity provider, you will
+  need to add ``[synapse public baseurl]/_synapse/client/saml2/authn_response`` as a permitted
+  "ACS location" (also known as "allowed callback URLs") at the identity provider.
 
 Changes to HTML templates
 -------------------------
diff --git a/changelog.d/9434.doc b/changelog.d/9434.doc
new file mode 100644
index 0000000000..fd334136c2
--- /dev/null
+++ b/changelog.d/9434.doc
@@ -0,0 +1 @@
+Fix erroneous documentation from v1.27.0 about updating the SAML2 callback URL.
diff --git a/synapse/rest/synapse/client/__init__.py b/synapse/rest/synapse/client/__init__.py
index e5ef515090..8588b6d271 100644
--- a/synapse/rest/synapse/client/__init__.py
+++ b/synapse/rest/synapse/client/__init__.py
@@ -54,11 +54,7 @@ def build_synapse_client_resource_tree(hs: "HomeServer") -> Mapping[str, Resourc
     if hs.config.saml2_enabled:
         from synapse.rest.synapse.client.saml2 import SAML2Resource
 
-        res = SAML2Resource(hs)
-        resources["/_synapse/client/saml2"] = res
-
-        # This is also mounted under '/_matrix' for backwards-compatibility.
-        resources["/_matrix/saml2"] = res
+        resources["/_synapse/client/saml2"] = SAML2Resource(hs)
 
     return resources