[DOCS] Add SAML configuration information (#30548)

x-pack/docs/en/security/authentication/configuring-saml-realm.asciidoc

@@ -0,0 +1,225 @@
+[role="xpack"]
+[[configuring-saml-realm]]
+=== Configuring a SAML realm
+
+The {stack} supports Security Assertion Markup Language Single Sign On (SAML SSO) 
+into {kib} with {es} as a backend service. In particular, the {stack} supports 
+the SAML 2.0 Web Browser SSO and the SAML 2.0 Single Logout profiles. It can 
+integrate with any identity provider (IdP) that supports at least the SAML 2.0 
+Web Browser SSO Profile. 
+
+In SAML terminology, the {stack} is operating as a _service provider_ (SP). For more 
+information, see {stack-ov}/saml-realm.html[SAML authentication] and 
+{stack-ov}/saml-guide.html[Configuring SAML SSO on the {stack}]. 
+
+[NOTE]
+--
+
+* If you configure a SAML realm for use in {kib}, you should also configure
+another realm, such as the native realm in your authentication chain.
+* These instructions assume that you have an existing SAML identity provider.
+--
+
+To enable SAML authentication in {es} and add the {stack} as a service provider:
+
+. Enable SSL/TLS for HTTP. 
++
+--
+If your {es} cluster is operating in production mode, you must
+configure the HTTP interface to use TLS before you can enable SAML 
+authentication.
+
+See <<tls-http>>.
+--
+
+. Enable the Token Service. 
++
+--
+The {es} SAML implementation makes use of the {es} Token Service.  This service
+is automatically enabled if you configure TLS on the HTTP interface. You can 
+explicitly enable it by including the following setting in your 
+`elasticsearch.yml` file:
+
+[source, yaml]
+------------------------------------------------------------
+xpack.security.authc.token.enabled: true
+------------------------------------------------------------
+--
+
+. Configure a SAML IdP metadata file. 
++
+--
+The {stack} uses a standard SAML metadata document in XML format, which defines 
+the capabilities and features of your identity provider. You should be able to
+download or generate such a document within your IdP administration interface. 
+
+Most IdPs will provide an appropriate metadata file with all the features that
+the {stack} requires. For more information, see 
+{stack-ov}/saml-guide-idp.html[The identity provider].
+--
+
+.. Download the IdP metadata document and store it within the `config` directory 
+on each {es} node. For example, store it as `config/saml/idp-metadata.xml`.
+
+.. Get the identifier for your identity provider. 
++
+--
+The IdP will have been assigned an identifier (_EntityID_ in SAML terminology),
+which is most commonly expressed in Uniform Resource Identifier (URI) form. Your 
+admin interface might tell you what this is or you might need to read the 
+metadata document to find it. Look for the `entityID` attribute on the
+`EntityDescriptor` element.
+--
+
+. Create one or more SAML realms.
++
+--
+SAML authentication is enabled by configuring a SAML realm within the
+authentication chain for {es}.
+
+This realm has a few mandatory settings, and a number of optional settings.
+The available settings are described in detail in the
+<<ref-saml-settings>>. The following settings (in the `elasticsearch.yml` 
+configuration file) are the most common settings:
+
+[source, yaml]
+------------------------------------------------------------
+xpack.security.authc.realms.saml1: <1>
+  type: saml <2>
+  order: 2 <3>
+  idp.metadata.path: saml/idp-metadata.xml <4>
+  idp.entity_id: "https://sso.example.com/" <5>
+  sp.entity_id:  "https://kibana.example.com/" <6>
+  sp.acs: "https://kibana.example.com/api/security/v1/saml" <7>
+  sp.logout: "https://kibana.example.com/logout" <8>
+------------------------------------------------------------
+<1> This setting defines a new authentication realm named "saml1". For an 
+introduction to realms, see {stack-ov}/realms.html[Realms]. 
+<2> The `type` must be `saml`.
+<3>  You should define a unique order on each realm in your authentication chain.
+It is recommended that the SAML realm be at the bottom of your authentication 
+chain (that is, it has the _highest_ order).
+<4> This is the path to the metadata file that you saved for your identity provider.
+The path that you enter here is relative to your `config/` directory. {security} 
+automatically monitors this file for changes and reloads the configuration 
+whenever it is updated.
+<5> This is the identifier (SAML EntityID) that your IdP uses. It should match 
+the `entityID` attribute within the metadata file.
+<6> This is a unique identifier for your {kib} instance, expressed as a URI.
+You will use this value when you add {kib} as a service provider within your IdP.
+We recommend that you use the base URL for your {kib} instance as the entity ID.
+<7> The Assertion Consumer Service (ACS) endpoint is the URL within {kib} that 
+accepts authentication messages from the IdP. This ACS endpoint supports the 
+SAML HTTP-POST binding only. It must be a URL that is accessible from the web 
+browser of the user who is attempting to login to {kib}; it does not need to be 
+directly accessible by {es} or the IdP. The correct value can vary depending on 
+how you have installed {kib} and whether there are any proxies involved, but it 
+is typically +$\{kibana-url}/api/security/v1/saml+ where _$\{kibana-url}_ is the 
+base URL for your {kib} instance.
+<8> This is the URL within {kib} that accepts logout messages from the IdP.
+Like the `sp.acs` URL, it must be accessible from the web browser, but does
+not need to be directly accessible by {es} or the IdP. The correct value can 
+vary depending on how you have installed {kib} and whether there are any
+proxies involved, but it will typically be +$\{kibana-url}/logout+ where
+_$\{kibana-url}_ is the base URL for your {kib} instance.
+
+IMPORTANT: SAML is used when authenticating via {kib}, but it is not an
+effective means of authenticating directly to the {es} REST API. For this reason
+we recommend that you include at least one additional realm such as the
+native realm in your authentication chain for use by API clients.
+
+For more information, see 
+{stack-ov}/saml-guide-authentication.html#saml-create-realm[Create a SAML realm].
+--
+
+. Add attribute mappings. 
++
+--
+When a user connects to {kib} through the identity provider, the IdP supplies a 
+SAML assertion that includes attributes for the user. You can configure the SAML 
+realm to map these attributes to properties on the authenticated user. 
+
+The recommended steps for configuring these SAML attributes are as follows:
+--
+.. Consult your IdP to see what user attributes it can provide. This varies 
+greatly between providers, but you should be able to obtain a list from the 
+documentation or from your local admin.
+
+.. Read through the list of user properties that {es} supports and decide which 
+of them are useful to you and can be provided by your IdP. At a minimum, the 
+`principal` attribute is required. The `groups` attribute is recommended.
+
+.. Configure your IdP to release those attributes to your {kib} SAML service
+provider.
++
+--
+This process varies by provider - some provide a user interface for this, while 
+others might require that you edit configuration files. Usually the IdP (or your 
+local administrator) have suggestions about what URI to use for each attribute. 
+You can simply accept those suggestions, as the {es} service is entirely 
+configurable and does not require that any specific URIs are used.
+--
+
+.. Configure the SAML realm to associate the {es} user properties to the URIs 
+that you configured in your IdP. 
++
+--
+For example, add the following settings to the `elasticsearch.yml` configuration 
+file:
+
+[source, yaml]
+------------------------------------------------------------
+xpack.security.authc.realms.saml1: 
+  ...
+  attributes.principal: "urn:oid:0.9.2342.19200300.100.1.1"
+  attributes.groups: "urn:oid:1.3.6.1.4.1.5923.1.5.1."
+------------------------------------------------------------
+
+For more information, see 
+{stack-ov}/saml-guide-authentication.html#saml-attribute-mapping[Attribute mapping]. 
+--
+
+. (Optional) Configure logout services. 
++
+--
+The SAML protocol supports the concept of Single Logout (SLO). The level of 
+support for SLO varies between identity providers. 
+
+For more information, see 
+{stack-ov}/saml-guide-authentication.html#saml-logout[SAML logout]. 
+--
+
+. (Optional) Configure encryption and signing.
++
+--
+The {stack} supports generating signed SAML messages (for authentication and/or 
+logout), verifying signed SAML messages from the IdP (for both authentication 
+and logout), and processing encrypted content.
+
+You can configure {es} for signing, encryption, or both, with the same or 
+separate keys. For more information, see 
+{stack-ov}/saml-guide-authentication.html#saml-enc-sign[Encryption and signing]. 
+--
+
+. (Optional) Generate service provider metadata.
++
+--
+There are some extra configuration steps that are specific to each identity 
+provider. If your identity provider can import SP metadata, some of those steps 
+can be automated or expedited. You can generate SP metadata for the {stack} by 
+using the <<saml-metadata,`elasticsearch-saml-metadata` command>>.
+--
+
+. Configure role mappings.
++
+--
+When a user authenticates using SAML, they are identified to the {stack},
+but this does not automatically grant them access to perform any actions or
+access any data.
+
+Your SAML users cannot do anything until they are mapped to {security}
+roles. See {stack-ov}/saml-role-mapping.html[Configuring role mappings]. 
+--
+
+. {stack-ov}/saml-kibana.html[Configure {kib} to use SAML SSO]. 
+

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

@@ -22,6 +22,7 @@ the primary (or sole) authentication method for users of that {kib} instance.
 Once you enable SAML authentication in {kib} it will affect all users who try
 to login. The <<saml-kibana>> section provides more detail about how this works.
 
+[[saml-guide-idp]]
 === The identity provider
 
 The Elastic Stack supports the SAML 2.0 _Web Browser SSO_ and the SAML
@@ -70,6 +71,7 @@ For `<LogoutRequest>` messages, the message itself must be signed, and the
 signature should be provided as a URL parameter, as required by the HTTP-Redirect
 binding.
 
+[[saml-guide-authentication]]
 === Configure {es} for SAML authentication
 
 There are five configuration steps to enable SAML authentication in {es}:

x-pack/docs/en/security/configuring-es.asciidoc

@@ -76,6 +76,7 @@ user API.
 ** <<configuring-ldap-realm,Configure an LDAP realm>>.
 ** <<configuring-native-realm,Configure a native realm>>.
 ** <<configuring-pki-realm,Configure a PKI realm>>.
+** <<configuring-saml-realm,Configure a SAML realm>>.
 
 . Set up roles and users to control access to {es}.
 For example, to grant _John Doe_ full access to all indices that match
@@ -140,5 +141,6 @@ include::authentication/configuring-file-realm.asciidoc[]
 include::authentication/configuring-ldap-realm.asciidoc[]
 include::authentication/configuring-native-realm.asciidoc[]
 include::authentication/configuring-pki-realm.asciidoc[]
+include::authentication/configuring-saml-realm.asciidoc[]
 include::{xes-repo-dir}/settings/security-settings.asciidoc[]
 include::{xes-repo-dir}/settings/audit-settings.asciidoc[]