Add note in breaking changes for nameid_format (#77785)

* Add note in breaking changes for nameid_format

We changed the default for `nameid_format` in 8.0 in #44090 but
did not add anything to the breaking changes in the release notes.
This change amends that.

* remove reference to settings

* Fix docs build

* Accepting most of James' suggested changes

Thanks James!

Co-authored-by: James Rodewig <[email protected]>

* Incorporating changes from Ioannis

* Apply suggestions from code review

Co-authored-by: Tim Vernum <[email protected]>

* Apply suggestions from code review

Co-authored-by: Ioannis Kakavas <[email protected]>

Co-authored-by: James Rodewig <[email protected]>
Co-authored-by: Adam Locke <[email protected]>
Co-authored-by: Tim Vernum <[email protected]>

Author: 4 people

docs/reference/migration/migrate_8_0/security.asciidoc

@@ -165,6 +165,37 @@ Specifying this setting in a transport profile in `elasticsearch.yml` will
 result in an error on startup.
 ====
 
+[discrete]
+[[saml-realm-nameid-changes]]
+.The `nameid_format` SAML realm setting no longer has a default value.
+[%collapsible]
+====
+*Details* +
+In SAML, Identity Providers (IdPs) can either be explicitly configured to
+release a `NameID` with a specific format, or configured to attempt to conform 
+with the requirements of a Service Provider (SP). The SP declares its
+requirements in the `NameIDPolicy` element of a SAML Authentication Request.
+In {es}, the `nameid_format` SAML realm setting controls the `NameIDPolicy`
+value.
+
+Previously, the default value for `nameid_format` was
+`urn:oasis:names:tc:SAML:2.0:nameid-format:transient`. This setting created
+authentication requests that required the IdP to release `NameID` with a
+`transient` format.
+
+The default value has been removed, which means that {es} will create SAML Authentication Requests by default that don't put this requirement on the
+IdP. If you want to retain the previous behavior, set `nameid_format` to
+`urn:oasis:names:tc:SAML:2.0:nameid-format:transient`.
+
+*Impact* +
+If you currently don't configure `nameid_format` explicitly, it's possible
+that your IdP will reject authentication requests from {es} because the requests 
+do not specify a `NameID` format (and your IdP is configured to expect one).
+This mismatch can result in a broken SAML configuration. If you're unsure whether 
+your IdP is explicitly configured to use a certain `NameID` format and you want to retain current behavior
+, try setting `nameid_format` to `urn:oasis:names:tc:SAML:2.0:nameid-format:transient` explicitly.
+====
+
 [discrete]
 [[ssl-validation-changes]]
 ===== SSL/TLS configuration validation
@@ -287,7 +318,7 @@ on startup.
 
 [discrete]
 [[ssl-misc-changes]]
-===== Other SSL/TLS changes 
+===== Other SSL/TLS changes
 
 .PKCS#11 keystores and trustores cannot be configured in `elasticsearch.yml`
 [%collapsible]
@@ -307,7 +338,7 @@ Use of a PKCS#11 keystore or truststore as the JRE's default store is not affect
 
 *Impact* +
 If you have a PKCS#11 keystore configured within your `elasticsearch.yml` file, you must remove that
-configuration and switch to a supported keystore type, or configure your PKCS#11 keystore as the 
+configuration and switch to a supported keystore type, or configure your PKCS#11 keystore as the
 JRE default store.
 ====
 
@@ -360,6 +391,7 @@ renamed to better reflect its intended use.
 Assign users with the `kibana_user` role to the `kibana_admin` role.
 Discontinue use of the `kibana_user` role.
 ====
+
 // end::notable-breaking-changes[]
 
 // These are non-notable changes
@@ -373,7 +405,7 @@ Discontinue use of the `kibana_user` role.
 [%collapsible]
 ====
 *Details* +
-If `xpack.security.fips_mode.enabled` is true (see <<fips-140-compliance>>), 
+If `xpack.security.fips_mode.enabled` is true (see <<fips-140-compliance>>),
 the value of `xpack.security.authc.password_hashing.algorithm` now defaults to
 `pbkdf2_stretch`.