Adding doc for the new API introduced by #64517 - /_security/saml/metadata/{realm} (#65065)

x-pack/docs/build.gradle

@@ -56,6 +56,7 @@ testClusters.integTest {
   setting 'xpack.security.authc.realms.pki.pki1.certificate_authorities', '[ "testClient.crt" ]'
   setting 'xpack.security.authc.realms.pki.pki1.delegation.enabled', 'true'
   setting 'xpack.security.authc.realms.saml.saml1.order', '4'
+  setting 'xpack.security.authc.realms.saml.saml1.sp.logout', 'https://kibana.org/logout'
   setting 'xpack.security.authc.realms.saml.saml1.idp.entity_id', 'https://my-idp.org'
   setting 'xpack.security.authc.realms.saml.saml1.idp.metadata.path', 'idp-docs-metadata.xml'
   setting 'xpack.security.authc.realms.saml.saml1.sp.entity_id', 'https://kibana.org'

x-pack/docs/en/rest-api/security.asciidoc

@@ -103,6 +103,7 @@ realm when using a custom web application other than Kibana
 * <<security-api-saml-authenticate, Submit an authentication response>>
 * <<security-api-saml-logout, Logout an authenticated user>>
 * <<security-api-saml-invalidate, Submit a logout request from the IdP>>
+* <<security-api-saml-sp-metadata,Generate SAML metadata>>
 
 
 include::security/authenticate.asciidoc[]
@@ -141,4 +142,5 @@ include::security/saml-prepare-authentication-api.asciidoc[]
 include::security/saml-authenticate-api.asciidoc[]
 include::security/saml-logout-api.asciidoc[]
 include::security/saml-invalidate-api.asciidoc[]
+include::security/saml-sp-metadata.asciidoc[]
 include::security/ssl.asciidoc[]

x-pack/docs/en/rest-api/security/saml-sp-metadata.asciidoc

@@ -0,0 +1,49 @@
+[role="xpack"]
+[[security-api-saml-sp-metadata]]
+=== SAML service provider metadata API
+
+Generate SAML metadata for a SAML 2.0 Service Provider.
+
+[[security-api-saml-sp-metadata-request]]
+==== {api-request-title}
+
+`GET /_security/saml/metadata/<realm_name>`
+
+[[security-api-saml-sp-metadata-desc]]
+==== {api-description-title}
+
+The SAML 2.0 specification provides a mechanism for Service Providers to
+describe their capabilities and configuration using a metadata file. This API
+generates Service Provider metadata, based on the configuration of a SAML realm
+in {es}.
+
+[[security-api-saml-sp-metadata-path-params]]
+==== {api-path-parms-title}
+
+`<realm_name>`::
+  (Required, string) The name of the SAML realm in {es}.
+
+[[security-api-saml-sp-metadata-response-body]]
+==== {api-response-body-title}
+
+`metadata`::
+(string) An XML string that contains a SAML Service Provider's metadata for the realm.
+
+[[security-api-saml-sp-metadata-example]]
+==== {api-examples-title}
+
+The following example generates Service Provider metadata for
+SAML realm `saml1`:
+
+[source,console]
+--------------------------------------------------
+GET /_security/saml/metadata/saml1
+--------------------------------------------------
+The API returns the following response containing the SAML metadata as an XML string:
+
+[source,console-result]
+--------------------------------------------------
+{
+    "metadata" : "<?xml version=\"1.0\" encoding=\"UTF-8\"?><md:EntityDescriptor xmlns:md=\"urn:oasis:names:tc:SAML:2.0:metadata\" entityID=\"https://kibana.org\"><md:SPSSODescriptor AuthnRequestsSigned=\"false\" WantAssertionsSigned=\"true\" protocolSupportEnumeration=\"urn:oasis:names:tc:SAML:2.0:protocol\"><md:SingleLogoutService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect\" Location=\"https://kibana.org/logout\"/><md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</md:NameIDFormat><md:AssertionConsumerService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST\" Location=\"https://kibana.org/api/security/v1/saml\" index=\"1\" isDefault=\"true\"/></md:SPSSODescriptor></md:EntityDescriptor>"
+}
+--------------------------------------------------