2 files changed, 8 insertions, 0 deletions
diff --git a/UPGRADE.rst b/UPGRADE.rst
index 031e02bda9..8bc2ff91ab 100644
--- a/UPGRADE.rst
+++ b/UPGRADE.rst
@@ -124,6 +124,13 @@ This version changes the URI used for callbacks from OAuth2 and SAML2 identity p
   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.
 
+  The "Issuer" in the "AuthnRequest" to the SAML2 identity provider is also updated to
+  ``[synapse public baseurl]/_synapse/client/saml2/metadata.xml``. If your SAML2 identity
+  provider uses this property to validate or otherwise identify Synapse, its configuration
+  will need to be updated to use the new URL. Alternatively you could create a new, separate
+  "EntityDescriptor" in your SAML2 identity provider with the new URLs and leave the URLs in
+  the existing "EntityDescriptor" as they were.
+
 Changes to HTML templates
 -------------------------
 
diff --git a/changelog.d/9550.doc b/changelog.d/9550.doc
new file mode 100644
index 0000000000..adbbeb0ae4
--- /dev/null
+++ b/changelog.d/9550.doc
@@ -0,0 +1 @@
+Improve the SAML2 upgrade notes for 1.27.0.