Add documentation for SAML SP metadata changes in KC 21 (#1760)

release_notes/topics/21_0_0.adoc

@@ -15,4 +15,26 @@ See the migration guide for details.
 
 We removed the out-of-box support for Hashicorp vault in this release.
 
-See this https://github.com/keycloak/keycloak/discussions/16446[discussion] for more details.
+See this https://github.com/keycloak/keycloak/discussions/16446[discussion] for more details.
+
+= SAML SP metadata changes
+
+Prior to this release, SAML SP metadata contained the same key for both
+signing and encryption use. Starting with this version of Keycloak,
+we include only encryption intended realm keys for encryption use
+in SP metadata. For each encryption key descriptor we also specify
+the algorithm that it is supposed to be used with. The following table shows
+the supported XML-Enc algorithms with the mapping to Keycloak realm keys.
+See the link:{upgradingguide_link}[{upgradingguide_name}] for more details.
+
+[cols="1,1"]
+|===
+|*XML-Enc algorithm*
+|*Keycloak realm key algorithm*
+
+|https://www.w3.org/TR/2002/REC-xmlenc-core-20021210/Overview.html#rsa-oaep-mgf1p[rsa-oaep-mgf1p]
+|RSA-OAEP
+
+|https://www.w3.org/TR/2002/REC-xmlenc-core-20021210/Overview.html#rsa-1_5[rsa-1_5]
+|RSA1_5
+|===

server_admin/topics/identity-broker/saml.adoc

@@ -64,8 +64,13 @@ We recommend to use some more secure algorithm instead of `*_SHA1`. Also, with `
 do not work if the SAML identity provider (for example another instance of {project_name}) runs on Java 17 or higher.
 
 |Encryption Algorithm
-|Encryption algorithm, which is used by SAML IDP for encryption of SAML documents, assertions or IDs. The corresponding decryption key
-for decrypt SAML document parts will be chosen based on this configured algorithm and should be available in realm keys for the encryption (ENC) usage.
+|Encryption algorithm, which is used by SAML IDP for encryption of SAML
+documents, assertions, or IDs. The corresponding decryption key for decrypt
+SAML document parts will be chosen based on this configured algorithm and
+should be available in realm keys for the encryption (ENC) usage. If the
+algorithm is not configured, any supported algorithm is allowed and a
+decryption key will be chosen based on the algorithm specified in SAML document
+itself.
 
 |SAML Signature Key Name
 |Signed SAML documents sent using POST binding contain the identification of signing key in `KeyName` element, which, by default, contains the {project_name} key ID. External SAML IDPs can expect a different key name. This switch controls whether `KeyName` contains:

upgrading/topics/keycloak/changes-21_0_0.adoc

@@ -34,3 +34,18 @@ algorithms do not work on Java 17 or higher. If you use this algorithm and the o
 
 The possible workaround is to remove algorithms such as `++http://www.w3.org/2000/09/xmldsig#rsa-sha1++` or `++http://www.w3.org/2000/09/xmldsig#dsa-sha1++` from the list
 of "disallowed algorithms" configured on property `jdk.xml.dsig.secureValidationPolicy` in the file `$JAVA_HOME/conf/security/java.security`.
+
+= SAML SP metadata changes
+
+In this version, Keycloak will refuse to decrypt assertions encrypted using
+a realm key generated for signing purpose. This change means all encrypted
+communication from IDP to SP (where Keycloak acts as the SP) will stop working.
+
+There are two ways to make this work:
+
+- either update the IDP configuration with the metadata generated by a newer
+version of Keycloak,
+- or run Keycloak in backward compatibility mode that will make Keycloak
+work with the metadata generated by older Keycloak versions. This mode can be
+enabled using `-Dkeycloak.saml.deprecated.encryption=true` flag. Note this
+backward compatibility mode is planned to be removed in Keycloak 24.