From 48f53efd9a99442f0ef07288c6607e6815deacee Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Mon, 18 Nov 2019 09:58:47 -0800 Subject: [PATCH] [DOCS] Merges duplicate pages for SAML realms (#49209) --- docs/reference/redirects.asciidoc | 25 ++ .../configuring-saml-realm.asciidoc | 230 ------------------ .../authentication/saml-guide.asciidoc | 7 +- .../authentication/saml-realm.asciidoc | 21 -- .../docs/en/security/configuring-es.asciidoc | 4 +- 5 files changed, 30 insertions(+), 257 deletions(-) delete mode 100644 x-pack/docs/en/security/authentication/configuring-saml-realm.asciidoc diff --git a/docs/reference/redirects.asciidoc b/docs/reference/redirects.asciidoc index 6731b21985f08..927b2904bb817 100644 --- a/docs/reference/redirects.asciidoc +++ b/docs/reference/redirects.asciidoc @@ -920,3 +920,28 @@ See <>. See <>. +[role="exclude",id="configuring-saml-realm"] +=== Configuring a SAML realm + +See <>. + +[role="exclude",id="saml-settings"] +==== SAML realm settings + +See <>. + +[role="exclude",id="_saml_realm_signing_settings"] +==== SAML realm signing settings + +See <>. + +[role="exclude",id="_saml_realm_encryption_settings"] +==== SAML realm encryption settings + +See <>. + +[role="exclude",id="_saml_realm_ssl_settings"] +==== SAML realm SSL settings + +See <>. + diff --git a/x-pack/docs/en/security/authentication/configuring-saml-realm.asciidoc b/x-pack/docs/en/security/authentication/configuring-saml-realm.asciidoc deleted file mode 100644 index 07ad774353c08..0000000000000 --- a/x-pack/docs/en/security/authentication/configuring-saml-realm.asciidoc +++ /dev/null @@ -1,230 +0,0 @@ -[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 <> and <>. - -[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 <>. --- - -. 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 -<>. --- - -.. 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 -<>. The following settings (in the `elasticsearch.yml` -configuration file) are the most common settings: - -[source, yaml] ------------------------------------------------------------- -xpack.security.authc.realms: - saml: <1> - saml1: <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> The realm must be within the `xpack.security.authc.realms.saml` namespace. -<2> This setting defines a new authentication realm named "saml1". For an -introduction to realms, see <>. -<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. {es} -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 -<>. --- - -. 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.saml.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 -<>. --- - -. (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 -<>. --- - -. (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 -<>. --- - -. (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 <>. --- - -. 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 assigned roles. This can be done -through either the <>, or with -<>. - -NOTE: You cannot use <> -to grant roles to users authenticating via SAML. - --- - -. <>. - diff --git a/x-pack/docs/en/security/authentication/saml-guide.asciidoc b/x-pack/docs/en/security/authentication/saml-guide.asciidoc index e425aeb2c3aec..966cbc1682ed1 100644 --- a/x-pack/docs/en/security/authentication/saml-guide.asciidoc +++ b/x-pack/docs/en/security/authentication/saml-guide.asciidoc @@ -111,9 +111,10 @@ 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 -<>, this guide will walk you through -the most common settings. +The available settings are described in detail in <>. For +example, <>, <>, +<>, <>. +This guide will walk you through the most common settings. Create a realm by adding the following to your `elasticsearch.yml` configuration file. Each configuration value is explained below. diff --git a/x-pack/docs/en/security/authentication/saml-realm.asciidoc b/x-pack/docs/en/security/authentication/saml-realm.asciidoc index 44fc0ff5b8b32..cd91505f63d32 100644 --- a/x-pack/docs/en/security/authentication/saml-realm.asciidoc +++ b/x-pack/docs/en/security/authentication/saml-realm.asciidoc @@ -18,24 +18,3 @@ chain. In order to simplify the process of configuring SAML authentication within the Elastic Stack, there is a step-by-step guide to <>. - -The remainder of this document will describe {es} specific configuration options -for SAML realms. - -[[saml-settings]] -==== SAML realm settings - -See {ref}/security-settings.html#ref-saml-settings[SAML realm settings]. - -==== SAML realm signing settings - -See {ref}/security-settings.html#ref-saml-signing-settings[SAML realm signing settings]. - -==== SAML realm encryption settings - -See {ref}/security-settings.html#ref-saml-encryption-settings[SAML realm encryption settings]. - -==== SAML realm SSL settings - -See {ref}/security-settings.html#ref-saml-ssl-settings[SAML realm SSL settings]. - diff --git a/x-pack/docs/en/security/configuring-es.asciidoc b/x-pack/docs/en/security/configuring-es.asciidoc index a298fd501215a..6cb9252f1076c 100644 --- a/x-pack/docs/en/security/configuring-es.asciidoc +++ b/x-pack/docs/en/security/configuring-es.asciidoc @@ -78,7 +78,7 @@ your subscription. For more information, see https://www.elastic.co/subscription ** <> ** <> ** <> -** <> +** <> . Set up roles and users to control access to {es}. + @@ -149,8 +149,6 @@ include::authentication/configuring-active-directory-realm.asciidoc[] include::authentication/configuring-file-realm.asciidoc[] include::authentication/configuring-ldap-realm.asciidoc[] include::authentication/configuring-pki-realm.asciidoc[] -include::authentication/configuring-saml-realm.asciidoc[] - include::authentication/configuring-kerberos-realm.asciidoc[] include::reference/files.asciidoc[]