[DOCS] Add RequestedAuthnContext Documentation (#32946)

Add documentation for #31238

- Add documentation for the req_authn_context_class_ref setting
- Add a section in SAML Guide regarding the use of SAML
  Authentication Context.

docs/reference/settings/security-settings.asciidoc

@@ -861,6 +861,15 @@ The maximum amount of skew that can be tolerated between the IdP's clock and the
 {es} node's clock.
 Defaults to `3m` (3 minutes).
 
+`req_authn_context_class_ref`::
+A comma separated list of Authentication Context Class Reference values to be
+included in the Requested Authentication Context when requesting the IdP to
+authenticate the current user. The Authentication Context of the corresponding
+authentication response should contain at least one of the requested values.
++
+For more information, see
+{stack-ov}/saml-guide-authentication.html#req-authn-context[Requesting specific authentication methods].
+
 [float]
 [[ref-saml-signing-settings]]
 ===== SAML realm signing settings

x-pack/docs/en/security/authentication/saml-guide.asciidoc

@@ -76,12 +76,13 @@ binding.
 
 There are five configuration steps to enable SAML authentication in {es}:
 
-. Enable SSL/TLS for HTTP
-. Enable the Token Service
-. Create one or more SAML realms
-. Configure role mappings
+. <<saml-enable-http,Enable SSL/TLS for HTTP>>
+. <<saml-enable-token,Enable the Token Service>>
+. <<saml-create-realm,Create one or more SAML realms>>
+. <<saml-role-mapping,Configure role mappings>>
 . Generate a SAML Metadata file for use by your Identity Provider _(optional)_
 
+[[saml-enable-http]]
 ==== Enable TLS for HTTP
 
 If your {es} cluster is operating in production mode, then you must
@@ -91,6 +92,7 @@ authentication.
 For more information, see
 {ref}/configuring-tls.html#tls-http[Encrypting HTTP Client Communications].
 
+[[saml-enable-token]]
 ==== Enable the token service
 
 The {es} SAML implementation makes use of the {es} Token Service.  This service
@@ -356,6 +358,35 @@ address such as `admin@staff.example.com.attacker.net`. It is important that
 you make sure your regular expressions are as precise as possible so that
 you do not inadvertently open an avenue for user impersonation attacks.
 
+[[req-authn-context]]
+==== Requesting specific authentication methods
+
+It is sometimes necessary for a SAML SP to be able to impose specific
+restrictions regarding the authentication that will take place at an IdP,
+in order to assess the level of confidence that it can place in
+the corresponding authentication response. The restrictions might have to do
+with the authentication method (password, client certificates, etc), the
+user identification method during registration, and other details. {es} implements
+https://docs.oasis-open.org/security/saml/v2.0/saml-authn-context-2.0-os.pdf[SAML 2.0 Authentication Context], which can be used for this purpose as defined in SAML 2.0 Core 
+Specification.
+
+In short, the SAML SP defines a set of Authentication Context Class Reference
+values, which describe the restrictions to be imposed on the IdP, and sends these
+in the Authentication Request. The IdP attempts to grant these restrictions. 
+If it cannot grant them, the authentication attempt fails. If the user is 
+successfully authenticated, the Authentication Statement of the SAML Response 
+contains an indication of the restrictions that were satisfied.
+
+You can define the Authentication Context Class Reference values by using the `req_authn_context_class_ref` option in the SAML realm configuration. See 
+{ref}/security-settings.html#ref-saml-settings[SAML realm settings]. 
+
+{es} supports only the `exact` comparison method for the Authentication Context. 
+When it receives the Authentication Response from the IdP, {es} examines the 
+value of the Authentication Context Class Reference that is part of the
+Authentication Statement of the SAML Assertion. If it matches one of the 
+requested values, the authentication is considered successful. Otherwise, the 
+authentication attempt fails.
+
 [[saml-logout]]
 ==== SAML logout
 
@@ -573,6 +604,7 @@ The passphrase for the keystore, if the file is encypted. This is a
 {ref}/secure-settings.html[secure setting] that must be set with the
 `elasticsearch-keystore` tool.
 
+[[saml-sp-metadata]]
 === Generating SP metadata
 
 Some Identity Providers support importing a metadata file from the Service