[DOCS] Merges duplicate pages for SAML realms (#49209)
This commit is contained in:
Lisa Cawley
lcawl
parent
b0b5fcc4f6
commit
48f53efd9a
|
|
@ -920,3 +920,28 @@ See <<native-realm-configuration>>.
|
|||
|
||||
See <<ref-native-settings>>.
|
||||
|
||||
[role="exclude",id="configuring-saml-realm"]
|
||||
=== Configuring a SAML realm
|
||||
|
||||
See <<saml-guide>>.
|
||||
|
||||
[role="exclude",id="saml-settings"]
|
||||
==== SAML realm settings
|
||||
|
||||
See <<ref-saml-settings>>.
|
||||
|
||||
[role="exclude",id="_saml_realm_signing_settings"]
|
||||
==== SAML realm signing settings
|
||||
|
||||
See <<ref-saml-signing-settings>>.
|
||||
|
||||
[role="exclude",id="_saml_realm_encryption_settings"]
|
||||
==== SAML realm encryption settings
|
||||
|
||||
See <<ref-saml-encryption-settings>>.
|
||||
|
||||
[role="exclude",id="_saml_realm_ssl_settings"]
|
||||
==== SAML realm SSL settings
|
||||
|
||||
See <<ref-saml-ssl-settings>>.
|
||||
|
||||
|
|
|
|||
|
|
@ -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 <<saml-realm>> and <<saml-guide>>.
|
||||
|
||||
[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
|
||||
<<saml-guide-idp>>.
|
||||
--
|
||||
|
||||
.. 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:
|
||||
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 <<realms>>.
|
||||
<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
|
||||
<<saml-create-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.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
|
||||
<<saml-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
|
||||
<<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
|
||||
<<saml-enc-sign>>.
|
||||
--
|
||||
|
||||
. (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 assigned roles. This can be done
|
||||
through either the <<saml-role-mapping,role mapping API>>, or with
|
||||
<<authorization_realms,authorization realms>>.
|
||||
|
||||
NOTE: You cannot use <<mapping-roles-file,role mapping files>>
|
||||
to grant roles to users authenticating via SAML.
|
||||
|
||||
--
|
||||
|
||||
. <<saml-kibana,Configure {kib} to use SAML SSO>>.
|
||||
|
||||
|
|
@ -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
|
||||
<<saml-settings, SAML realm documentation>>, this guide will walk you through
|
||||
the most common settings.
|
||||
The available settings are described in detail in <<security-settings>>. For
|
||||
example, <<ref-saml-settings>>, <<ref-saml-signing-settings>>,
|
||||
<<ref-saml-encryption-settings>>, <<ref-saml-ssl-settings>>.
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
<<saml-guide, Configuring Elasticsearch and Kibana to use SAML single sign-on>>.
|
||||
|
||||
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].
|
||||
|
||||
|
|
|
|||
|
|
@ -78,7 +78,7 @@ your subscription. For more information, see https://www.elastic.co/subscription
|
|||
** <<configuring-ldap-realm,LDAP realms>>
|
||||
** <<native-realm,Native realms>>
|
||||
** <<configuring-pki-realm,PKI realms>>
|
||||
** <<configuring-saml-realm,SAML realms>>
|
||||
** <<saml-realm,SAML realms>>
|
||||
|
||||
. 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[]
|
||||
|
|
|
|||
Loading…
Reference in New Issue