Skip to content

Commit 31fc805

Browse files
lcawllcawl
committed
[DOCS] Add SAML configuration information (#30548)
1 parent d7a4441 commit 31fc805

File tree

3 files changed

+229
-0
lines changed

3 files changed

+229
-0
lines changed

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

Lines changed: 225 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,225 @@
1+
[role="xpack"]
2+
[[configuring-saml-realm]]
3+
=== Configuring a SAML realm
4+
5+
The {stack} supports Security Assertion Markup Language Single Sign On (SAML SSO)
6+
into {kib} with {es} as a backend service. In particular, the {stack} supports
7+
the SAML 2.0 Web Browser SSO and the SAML 2.0 Single Logout profiles. It can
8+
integrate with any identity provider (IdP) that supports at least the SAML 2.0
9+
Web Browser SSO Profile.
10+
11+
In SAML terminology, the {stack} is operating as a _service provider_ (SP). For more
12+
information, see {stack-ov}/saml-realm.html[SAML authentication] and
13+
{stack-ov}/saml-guide.html[Configuring SAML SSO on the {stack}].
14+
15+
[NOTE]
16+
--
17+
18+
* If you configure a SAML realm for use in {kib}, you should also configure
19+
another realm, such as the native realm in your authentication chain.
20+
* These instructions assume that you have an existing SAML identity provider.
21+
--
22+
23+
To enable SAML authentication in {es} and add the {stack} as a service provider:
24+
25+
. Enable SSL/TLS for HTTP.
26+
+
27+
--
28+
If your {es} cluster is operating in production mode, you must
29+
configure the HTTP interface to use TLS before you can enable SAML
30+
authentication.
31+
32+
See <<tls-http>>.
33+
--
34+
35+
. Enable the Token Service.
36+
+
37+
--
38+
The {es} SAML implementation makes use of the {es} Token Service. This service
39+
is automatically enabled if you configure TLS on the HTTP interface. You can
40+
explicitly enable it by including the following setting in your
41+
`elasticsearch.yml` file:
42+
43+
[source, yaml]
44+
------------------------------------------------------------
45+
xpack.security.authc.token.enabled: true
46+
------------------------------------------------------------
47+
--
48+
49+
. Configure a SAML IdP metadata file.
50+
+
51+
--
52+
The {stack} uses a standard SAML metadata document in XML format, which defines
53+
the capabilities and features of your identity provider. You should be able to
54+
download or generate such a document within your IdP administration interface.
55+
56+
Most IdPs will provide an appropriate metadata file with all the features that
57+
the {stack} requires. For more information, see
58+
{stack-ov}/saml-guide-idp.html[The identity provider].
59+
--
60+
61+
.. Download the IdP metadata document and store it within the `config` directory
62+
on each {es} node. For example, store it as `config/saml/idp-metadata.xml`.
63+
64+
.. Get the identifier for your identity provider.
65+
+
66+
--
67+
The IdP will have been assigned an identifier (_EntityID_ in SAML terminology),
68+
which is most commonly expressed in Uniform Resource Identifier (URI) form. Your
69+
admin interface might tell you what this is or you might need to read the
70+
metadata document to find it. Look for the `entityID` attribute on the
71+
`EntityDescriptor` element.
72+
--
73+
74+
. Create one or more SAML realms.
75+
+
76+
--
77+
SAML authentication is enabled by configuring a SAML realm within the
78+
authentication chain for {es}.
79+
80+
This realm has a few mandatory settings, and a number of optional settings.
81+
The available settings are described in detail in the
82+
<<ref-saml-settings>>. The following settings (in the `elasticsearch.yml`
83+
configuration file) are the most common settings:
84+
85+
[source, yaml]
86+
------------------------------------------------------------
87+
xpack.security.authc.realms.saml1: <1>
88+
type: saml <2>
89+
order: 2 <3>
90+
idp.metadata.path: saml/idp-metadata.xml <4>
91+
idp.entity_id: "https://sso.example.com/" <5>
92+
sp.entity_id: "https://kibana.example.com/" <6>
93+
sp.acs: "https://kibana.example.com/api/security/v1/saml" <7>
94+
sp.logout: "https://kibana.example.com/logout" <8>
95+
------------------------------------------------------------
96+
<1> This setting defines a new authentication realm named "saml1". For an
97+
introduction to realms, see {stack-ov}/realms.html[Realms].
98+
<2> The `type` must be `saml`.
99+
<3> You should define a unique order on each realm in your authentication chain.
100+
It is recommended that the SAML realm be at the bottom of your authentication
101+
chain (that is, it has the _highest_ order).
102+
<4> This is the path to the metadata file that you saved for your identity provider.
103+
The path that you enter here is relative to your `config/` directory. {security}
104+
automatically monitors this file for changes and reloads the configuration
105+
whenever it is updated.
106+
<5> This is the identifier (SAML EntityID) that your IdP uses. It should match
107+
the `entityID` attribute within the metadata file.
108+
<6> This is a unique identifier for your {kib} instance, expressed as a URI.
109+
You will use this value when you add {kib} as a service provider within your IdP.
110+
We recommend that you use the base URL for your {kib} instance as the entity ID.
111+
<7> The Assertion Consumer Service (ACS) endpoint is the URL within {kib} that
112+
accepts authentication messages from the IdP. This ACS endpoint supports the
113+
SAML HTTP-POST binding only. It must be a URL that is accessible from the web
114+
browser of the user who is attempting to login to {kib}; it does not need to be
115+
directly accessible by {es} or the IdP. The correct value can vary depending on
116+
how you have installed {kib} and whether there are any proxies involved, but it
117+
is typically +$\{kibana-url}/api/security/v1/saml+ where _$\{kibana-url}_ is the
118+
base URL for your {kib} instance.
119+
<8> This is the URL within {kib} that accepts logout messages from the IdP.
120+
Like the `sp.acs` URL, it must be accessible from the web browser, but does
121+
not need to be directly accessible by {es} or the IdP. The correct value can
122+
vary depending on how you have installed {kib} and whether there are any
123+
proxies involved, but it will typically be +$\{kibana-url}/logout+ where
124+
_$\{kibana-url}_ is the base URL for your {kib} instance.
125+
126+
IMPORTANT: SAML is used when authenticating via {kib}, but it is not an
127+
effective means of authenticating directly to the {es} REST API. For this reason
128+
we recommend that you include at least one additional realm such as the
129+
native realm in your authentication chain for use by API clients.
130+
131+
For more information, see
132+
{stack-ov}/saml-guide-authentication.html#saml-create-realm[Create a SAML realm].
133+
--
134+
135+
. Add attribute mappings.
136+
+
137+
--
138+
When a user connects to {kib} through the identity provider, the IdP supplies a
139+
SAML assertion that includes attributes for the user. You can configure the SAML
140+
realm to map these attributes to properties on the authenticated user.
141+
142+
The recommended steps for configuring these SAML attributes are as follows:
143+
--
144+
.. Consult your IdP to see what user attributes it can provide. This varies
145+
greatly between providers, but you should be able to obtain a list from the
146+
documentation or from your local admin.
147+
148+
.. Read through the list of user properties that {es} supports and decide which
149+
of them are useful to you and can be provided by your IdP. At a minimum, the
150+
`principal` attribute is required. The `groups` attribute is recommended.
151+
152+
.. Configure your IdP to release those attributes to your {kib} SAML service
153+
provider.
154+
+
155+
--
156+
This process varies by provider - some provide a user interface for this, while
157+
others might require that you edit configuration files. Usually the IdP (or your
158+
local administrator) have suggestions about what URI to use for each attribute.
159+
You can simply accept those suggestions, as the {es} service is entirely
160+
configurable and does not require that any specific URIs are used.
161+
--
162+
163+
.. Configure the SAML realm to associate the {es} user properties to the URIs
164+
that you configured in your IdP.
165+
+
166+
--
167+
For example, add the following settings to the `elasticsearch.yml` configuration
168+
file:
169+
170+
[source, yaml]
171+
------------------------------------------------------------
172+
xpack.security.authc.realms.saml1:
173+
...
174+
attributes.principal: "urn:oid:0.9.2342.19200300.100.1.1"
175+
attributes.groups: "urn:oid:1.3.6.1.4.1.5923.1.5.1."
176+
------------------------------------------------------------
177+
178+
For more information, see
179+
{stack-ov}/saml-guide-authentication.html#saml-attribute-mapping[Attribute mapping].
180+
--
181+
182+
. (Optional) Configure logout services.
183+
+
184+
--
185+
The SAML protocol supports the concept of Single Logout (SLO). The level of
186+
support for SLO varies between identity providers.
187+
188+
For more information, see
189+
{stack-ov}/saml-guide-authentication.html#saml-logout[SAML logout].
190+
--
191+
192+
. (Optional) Configure encryption and signing.
193+
+
194+
--
195+
The {stack} supports generating signed SAML messages (for authentication and/or
196+
logout), verifying signed SAML messages from the IdP (for both authentication
197+
and logout), and processing encrypted content.
198+
199+
You can configure {es} for signing, encryption, or both, with the same or
200+
separate keys. For more information, see
201+
{stack-ov}/saml-guide-authentication.html#saml-enc-sign[Encryption and signing].
202+
--
203+
204+
. (Optional) Generate service provider metadata.
205+
+
206+
--
207+
There are some extra configuration steps that are specific to each identity
208+
provider. If your identity provider can import SP metadata, some of those steps
209+
can be automated or expedited. You can generate SP metadata for the {stack} by
210+
using the <<saml-metadata,`elasticsearch-saml-metadata` command>>.
211+
--
212+
213+
. Configure role mappings.
214+
+
215+
--
216+
When a user authenticates using SAML, they are identified to the {stack},
217+
but this does not automatically grant them access to perform any actions or
218+
access any data.
219+
220+
Your SAML users cannot do anything until they are mapped to {security}
221+
roles. See {stack-ov}/saml-role-mapping.html[Configuring role mappings].
222+
--
223+
224+
. {stack-ov}/saml-kibana.html[Configure {kib} to use SAML SSO].
225+

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ the primary (or sole) authentication method for users of that {kib} instance.
2222
Once you enable SAML authentication in {kib} it will affect all users who try
2323
to login. The <<saml-kibana>> section provides more detail about how this works.
2424

25+
[[saml-guide-idp]]
2526
=== The identity provider
2627

2728
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
7071
signature should be provided as a URL parameter, as required by the HTTP-Redirect
7172
binding.
7273

74+
[[saml-guide-authentication]]
7375
=== Configure {es} for SAML authentication
7476

7577
There are five configuration steps to enable SAML authentication in {es}:

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,7 @@ user API.
7676
** <<configuring-ldap-realm,Configure an LDAP realm>>.
7777
** <<configuring-native-realm,Configure a native realm>>.
7878
** <<configuring-pki-realm,Configure a PKI realm>>.
79+
** <<configuring-saml-realm,Configure a SAML realm>>.
7980

8081
. Set up roles and users to control access to {es}.
8182
For example, to grant _John Doe_ full access to all indices that match
@@ -140,5 +141,6 @@ include::authentication/configuring-file-realm.asciidoc[]
140141
include::authentication/configuring-ldap-realm.asciidoc[]
141142
include::authentication/configuring-native-realm.asciidoc[]
142143
include::authentication/configuring-pki-realm.asciidoc[]
144+
include::authentication/configuring-saml-realm.asciidoc[]
143145
include::{xes-repo-dir}/settings/security-settings.asciidoc[]
144146
include::{xes-repo-dir}/settings/audit-settings.asciidoc[]

0 commit comments

Comments
 (0)